Build a component for UI Builder

UI Builder · uibuilder@1 uibuildercomponentsextensions

A UI Builder component is one HTML file with up to four parts. The skeleton that the editor offers for a new component (public/template.txt) is a clock:

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

Part	What it does
`<style>`	the CSS of the component; `CLASS` is replaced by a class that belongs to the component
`<script>`	exports the metadata (`id`, `name`, `group`, `author`, `icon`, `version`, `config` with the defaults) and the function `make`
`<readme>`	the help text shown in the editor (Markdown)
`<settings>`	the form that edits `config`: jComponent inputs whose `path` starts with `?.` followed by the key of the config

The function make

make(instance, config, element, cls, iseditor) runs when the component is created:

instance is the instance of the component (set, on, emit, state...).
config is its configuration and element the jQuery element to fill.
cls is the class that replaced CLASS and iseditor tells whether it is drawn inside the editor or in a rendered design (so, for example, a timer does not need to run while you design).

Inside it you listen to events (instance.on('configure', ...) when the settings change and instance.on('destroy', ...) to clean timers), and write the value with instance.set('value', date).

Metadata, flags, methods and events

From the README of the editor:

Metadata: exports.follow = true shows the component in the settings form Path for reading/writing (for the designer only) and exports.hidden = true hides it from the list of components.
Flags of an instance: instance.state.bind = true binds the component automatically inside a form, for the ones that read and write data; instance.state.notify = true emits only the notify event when the value changes, instead of setting the value of the component directly (the Counter component is the example).
Method: instance.datasource(CLID_OR_@INSTANCEID__OR__#VIEWID, function(value) {}) reads a source of data and gives an array of [id, name].
Event: instance.on('refresh', function(meta) {}) fires when some objects changed: meta.type is remove or configure, with meta.items or meta.item.
Properties of the editor that a component can read: DEF.cl.datasource (code lists and components with follow), DEF.cl.paths, DEF.cl.list (all the instances), DEF.cl.inputs, DEF.cl.outputs, DEF.cl.views and DEF.cl.apps (sibling designs).
Following: a config.path that starts with @ means the component follows another one.

Publish the file in your own list of components (run the editor) and your team can use it from the editor.