# Construire un composant pour UI Builder

> Le format d’un composant UI Builder : un fichier HTML avec son style, un script qui exporte ses métadonnées et une fonction make, un formulaire de réglages et un readme, plus les indicateurs, méthodes et événements d’une instance.

Framework: uibuilder
Product: UI Builder (uibuilder@1)
Language: fr
Content-SHA256: 291b78e14f53f7a04e9dcabe68f5ff22e130504036204275d8af836c69895418
Snapshot: c0700e321579725c5cf4f5ace1ad7d2866d1b4f93c24a63c0b41b6b7998e976c
Sources: 
Review: not-recorded

Un composant UI Builder est **un fichier HTML** d’au plus quatre parties. Le squelette que l’éditeur propose pour un nouveau composant (`public/template.txt`) est une horloge :

```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>
```

| Partie | Ce qu’elle fait |
|---|---|
| `<style>` | le CSS du composant ; `CLASS` est remplacé par une classe propre au composant |
| `<script>` | exporte les métadonnées (`id`, `name`, `group`, `author`, `icon`, `version`, `config` avec les valeurs par défaut) et la fonction `make` |
| `<readme>` | le texte d’aide affiché dans l’éditeur (Markdown) |
| `<settings>` | le formulaire qui modifie `config` : des champs jComponent dont le `path` commence par `?.` suivi de la clé de la configuration |

## La fonction make

`make(instance, config, element, cls, iseditor)` s’exécute quand le composant est créé :

- `instance` est l’instance du composant (`set`, `on`, `emit`, `state`...).
- `config` est sa configuration et `element` l’élément jQuery à remplir.
- `cls` est la classe qui a remplacé `CLASS` et `iseditor` indique s’il est dessiné dans l’éditeur ou dans un design rendu (ainsi, par exemple, un minuteur n’a pas besoin de tourner pendant que vous concevez).

À l’intérieur, vous écoutez des événements (`instance.on('configure', ...)` quand les réglages changent et `instance.on('destroy', ...)` pour nettoyer les minuteurs) et vous écrivez la valeur avec `instance.set('value', date)`.

## Métadonnées, indicateurs, méthodes et événements

Extrait du README de l’éditeur :

- **Métadonnées :** `exports.follow = true` affiche le composant dans le formulaire de réglages *Path for reading/writing* (pour le concepteur seulement) et `exports.hidden = true` le masque de la liste des composants.
- **Indicateurs d’une instance :** `instance.state.bind = true` lie automatiquement le composant dans un formulaire, pour ceux qui lisent et écrivent des données ; `instance.state.notify = true` n’émet que l’événement `notify` quand la valeur change, au lieu de définir directement la valeur du composant (le composant Counter en est l’exemple).
- **Méthode :** `instance.datasource(CLID_OR_@INSTANCEID__OR__#VIEWID, function(value) {})` lit une source de données et renvoie un tableau de `[id, name]`.
- **Événement :** `instance.on('refresh', function(meta) {})` se déclenche quand certains objets ont changé : `meta.type` vaut `remove` ou `configure`, avec `meta.items` ou `meta.item`.
- **Propriétés de l’éditeur** qu’un composant peut lire : `DEF.cl.datasource` (listes de codes et composants avec `follow`), `DEF.cl.paths`, `DEF.cl.list` (toutes les instances), `DEF.cl.inputs`, `DEF.cl.outputs`, `DEF.cl.views` et `DEF.cl.apps` (designs frères).
- **Suivre :** un `config.path` qui commence par `@` signifie que le composant en suit un autre.

Publiez le fichier dans votre propre liste de composants ([exécuter l’éditeur](/en/uibuilder/run-the-designer/)) et votre équipe pourra l’utiliser depuis l’éditeur.