# Crear un componente para UI Builder

> El formato de un componente de UI Builder: un archivo HTML con su estilo, un script que exporta sus metadatos y una función make, un formulario de ajustes y un readme, además de las banderas, métodos y eventos de una instancia.

Framework: uibuilder
Product: UI Builder (uibuilder@1)
Language: es
Content-SHA256: 0a8c292ccc21fc3354506d2e3050a640af93f7f2f3030da5f00754694e56127c
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Un componente de UI Builder es **un archivo HTML** con hasta cuatro partes. El esqueleto que ofrece el editor para un componente nuevo (`public/template.txt`) es un reloj:

```html
<style>
	.CLASS { font-size: 14px; }
</style>

<script>
	exports.id = '';
	exports.name = 'Clock';
	exports.group = 'Controls';
	exports.author = 'Total.js';
	exports.icon = 'ti ti-clock';
	exports.config = { bold: false, flash: true, seconds: true };
	exports.version = '1';
	exports.follow = true;

	exports.make = function(instance, config, element, cls, iseditor) {
		// build the component inside element
	};
</script>

<readme>
The component renders the current time and the model contains a `Date` object.
</readme>

<settings>
	<div class="padding">
		<ui-component name="input" path="?.bold" config="type:checkbox">Apply bold font</ui-component>
	</div>
</settings>
```

| Parte | Qué hace |
|---|---|
| `<style>` | el CSS del componente; `CLASS` se sustituye por una clase que pertenece al componente |
| `<script>` | exporta los metadatos (`id`, `name`, `group`, `author`, `icon`, `version`, `config` con los valores por defecto) y la función `make` |
| `<readme>` | el texto de ayuda que muestra el editor (Markdown) |
| `<settings>` | el formulario que edita `config`: entradas de jComponent cuyo `path` empieza por `?.` seguido de la clave de la configuración |

## La función make

`make(instance, config, element, cls, iseditor)` se ejecuta cuando se crea el componente:

- `instance` es la instancia del componente (`set`, `on`, `emit`, `state`...).
- `config` es su configuración y `element` el elemento jQuery que hay que rellenar.
- `cls` es la clase que sustituyó a `CLASS` e `iseditor` indica si se dibuja dentro del editor o en un diseño renderizado (así, por ejemplo, un temporizador no necesita ejecutarse mientras diseñas).

Dentro escuchas eventos (`instance.on('configure', ...)` cuando cambian los ajustes e `instance.on('destroy', ...)` para limpiar temporizadores) y escribes el valor con `instance.set('value', date)`.

## Metadatos, banderas, métodos y eventos

Del README del editor:

- **Metadatos:** `exports.follow = true` muestra el componente en el formulario de ajustes *Path for reading/writing* (solo para el diseñador) y `exports.hidden = true` lo oculta de la lista de componentes.
- **Banderas de una instancia:** `instance.state.bind = true` enlaza el componente automáticamente dentro de un formulario, para los que leen y escriben datos; `instance.state.notify = true` emite solo el evento `notify` cuando cambia el valor, en lugar de establecer directamente el valor del componente (el componente Counter es el ejemplo).
- **Método:** `instance.datasource(CLID_OR_@INSTANCEID__OR__#VIEWID, function(value) {})` lee una fuente de datos y devuelve un array de `[id, name]`.
- **Evento:** `instance.on('refresh', function(meta) {})` se dispara cuando cambian algunos objetos: `meta.type` es `remove` o `configure`, con `meta.items` o `meta.item`.
- **Propiedades del editor** que puede leer un componente: `DEF.cl.datasource` (listas de códigos y componentes con `follow`), `DEF.cl.paths`, `DEF.cl.list` (todas las instancias), `DEF.cl.inputs`, `DEF.cl.outputs`, `DEF.cl.views` y `DEF.cl.apps` (diseños hermanos).
- **Seguir:** un `config.path` que empieza por `@` significa que el componente sigue a otro.

Publica el archivo en tu propia lista de componentes ([ejecutar el editor](/en/uibuilder/run-the-designer/)) y tu equipo podrá usarlo desde el editor.