# Construir um componente para o UI Builder

> O formato de um componente do UI Builder: um ficheiro HTML com o seu estilo, um script que exporta os seus metadados e uma função make, um formulário de definições e um readme, mais os indicadores, métodos e eventos de uma instância.

Framework: uibuilder
Product: UI Builder (uibuilder@1)
Language: pt
Content-SHA256: 4748619c84212bf7ebb63ebd450adc81a05ecf70473b442767054d8749e40de4
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Um componente do UI Builder é **um ficheiro HTML** com até quatro partes. O esqueleto que o editor oferece para um componente novo (`public/template.txt`) é um relógio:

```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 | O que faz |
|---|---|
| `<style>` | o CSS do componente; `CLASS` é substituído por uma classe que pertence ao componente |
| `<script>` | exporta os metadados (`id`, `name`, `group`, `author`, `icon`, `version`, `config` com os valores predefinidos) e a função `make` |
| `<readme>` | o texto de ajuda mostrado no editor (Markdown) |
| `<settings>` | o formulário que edita `config`: entradas do jComponent cujo `path` começa por `?.` seguido da chave da configuração |

## A função make

`make(instance, config, element, cls, iseditor)` corre quando o componente é criado:

- `instance` é a instância do componente (`set`, `on`, `emit`, `state`...).
- `config` é a sua configuração e `element` o elemento jQuery a preencher.
- `cls` é a classe que substituiu `CLASS` e `iseditor` indica se é desenhado dentro do editor ou num design renderizado (assim, por exemplo, um temporizador não precisa de correr enquanto desenha).

Lá dentro escuta eventos (`instance.on('configure', ...)` quando as definições mudam e `instance.on('destroy', ...)` para limpar temporizadores) e escreve o valor com `instance.set('value', date)`.

## Metadados, indicadores, métodos e eventos

Do README do editor:

- **Metadados:** `exports.follow = true` mostra o componente no formulário de definições *Path for reading/writing* (apenas para o desenhador) e `exports.hidden = true` oculta-o da lista de componentes.
- **Indicadores de uma instância:** `instance.state.bind = true` liga o componente automaticamente dentro de um formulário, para os que leem e escrevem dados; `instance.state.notify = true` emite apenas o evento `notify` quando o valor muda, em vez de definir diretamente o valor do componente (o componente Counter é o exemplo).
- **Método:** `instance.datasource(CLID_OR_@INSTANCEID__OR__#VIEWID, function(value) {})` lê uma fonte de dados e devolve um array de `[id, name]`.
- **Evento:** `instance.on('refresh', function(meta) {})` dispara quando alguns objetos mudaram: `meta.type` é `remove` ou `configure`, com `meta.items` ou `meta.item`.
- **Propriedades do editor** que um componente pode ler: `DEF.cl.datasource` (listas de códigos e componentes com `follow`), `DEF.cl.paths`, `DEF.cl.list` (todas as instâncias), `DEF.cl.inputs`, `DEF.cl.outputs`, `DEF.cl.views` e `DEF.cl.apps` (designs irmãos).
- **Seguir:** um `config.path` que começa por `@` significa que o componente segue outro.

Publique o ficheiro na sua própria lista de componentes ([executar o editor](/en/uibuilder/run-the-designer/)) e a sua equipa poderá usá-lo a partir do editor.