Construire un composant pour UI Builder

UI Builder · uibuilder@1 uibuildercomponentsextensions

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 :

<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) et votre équipe pourra l’utiliser depuis l’éditeur.