# Costruire un componente per UI Builder

> Il formato di un componente di UI Builder: un file HTML con il suo stile, uno script che esporta i metadati e una funzione make, un modulo di impostazioni e un readme, più i flag, i metodi e gli eventi di un’istanza.

Framework: uibuilder
Product: UI Builder (uibuilder@1)
Language: it
Content-SHA256: 90970bcd890f715c7200e39252113d4f97928d07c7ed3cd2d38d5332d37a1f58
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Un componente di UI Builder è **un file HTML** con fino a quattro parti. Lo scheletro che l’editor offre per un nuovo componente (`public/template.txt`) è un orologio:

```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 | Cosa fa |
|---|---|
| `<style>` | il CSS del componente; `CLASS` viene sostituito da una classe che appartiene al componente |
| `<script>` | esporta i metadati (`id`, `name`, `group`, `author`, `icon`, `version`, `config` con i valori predefiniti) e la funzione `make` |
| `<readme>` | il testo di aiuto mostrato nell’editor (Markdown) |
| `<settings>` | il modulo che modifica `config`: input di jComponent il cui `path` inizia con `?.` seguito dalla chiave della configurazione |

## La funzione make

`make(instance, config, element, cls, iseditor)` viene eseguita quando il componente è creato:

- `instance` è l’istanza del componente (`set`, `on`, `emit`, `state`...).
- `config` è la sua configurazione e `element` l’elemento jQuery da riempire.
- `cls` è la classe che ha sostituito `CLASS` e `iseditor` indica se viene disegnato dentro l’editor o in un design renderizzato (così, per esempio, un timer non ha bisogno di girare mentre progetti).

Al suo interno ascolti eventi (`instance.on('configure', ...)` quando cambiano le impostazioni e `instance.on('destroy', ...)` per ripulire i timer) e scrivi il valore con `instance.set('value', date)`.

## Metadati, flag, metodi ed eventi

Dal README dell’editor:

- **Metadati:** `exports.follow = true` mostra il componente nel modulo di impostazioni *Path for reading/writing* (solo per il progettista) e `exports.hidden = true` lo nasconde dall’elenco dei componenti.
- **Flag di un’istanza:** `instance.state.bind = true` lega automaticamente il componente dentro un modulo, per quelli che leggono e scrivono dati; `instance.state.notify = true` emette solo l’evento `notify` quando il valore cambia, invece di impostare direttamente il valore del componente (il componente Counter ne è l’esempio).
- **Metodo:** `instance.datasource(CLID_OR_@INSTANCEID__OR__#VIEWID, function(value) {})` legge una fonte di dati e restituisce un array di `[id, name]`.
- **Evento:** `instance.on('refresh', function(meta) {})` scatta quando alcuni oggetti sono cambiati: `meta.type` è `remove` o `configure`, con `meta.items` o `meta.item`.
- **Proprietà dell’editor** che un componente può leggere: `DEF.cl.datasource` (elenchi di codici e componenti con `follow`), `DEF.cl.paths`, `DEF.cl.list` (tutte le istanze), `DEF.cl.inputs`, `DEF.cl.outputs`, `DEF.cl.views` e `DEF.cl.apps` (design fratelli).
- **Seguire:** un `config.path` che inizia con `@` significa che il componente ne segue un altro.

Pubblica il file nel tuo elenco di componenti ([eseguire l’editor](/en/uibuilder/run-the-designer/)) e il tuo team potrà usarlo dall’editor.