# Build a component for UI Builder

> The format of a UI Builder component: one HTML file with its style, a script that exports its metadata and a make function, a settings form and a readme, plus the flags, methods and events of an instance.

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

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:

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

| 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](/en/uibuilder/run-the-designer/)) and your team can use it from the editor.