Construir um componente para o UI Builder

UI Builder · uibuilder@1 uibuildercomponentsextensions

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:

<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) e a sua equipa poderá usá-lo a partir do editor.