Configuration

As described in the Getting started section, plug-ins are embedded into the Haiilo Home widget system using iFrames. This offers a simple yet very powerful and versatile approach. In order for a plug-in to fit into Haiilo Home as naturally as possible, there are a few things to consider.

To simplify the configuration of plug-ins, Haiilo Home offers a built-in option to create and display dynamic configuration forms. The configuration fields of a plug-in are defined in the associated manifest and then read and interpreted by Haiilo Home. In this way, created forms are perfectly embedded in the Haiilo Home UI/UX. The configuration values will be handed to the plug-in during the initialization process.

📘
Hint
Haiilo Home will automatically reload your plug-in every time a configuration value is changed.

Configuration Definition

To define a global or instance-specific configuration form, a list of field definitions can be added to the manifest. They can either be added at the top level of the manifest to define global configurations or on the entry point level to allow for instance specific configuration forms. Haiilo Home will render the configuration forms at the right spot and also take care of checking user authorization for you.

The manifest allows the following set of field definitions:

Attribute	Type	Description
key	string	The key that relates to the configuration model.
type	string	The type of field to be rendered.
label	Translation map	A label for the field.
placeholder	Translation map	A placeholder for the field.
description	Translation map	A description for the field.
options	object[]	A list of field option for a form field with options (`radio`/`select`).
options.value	boolean \| number \| string	The option value.
options.label	Translation map	The option label.
options.description	Translation map	The option description.
default	boolean \| number \| string	A default value for the field.
required	boolean	Specifies whether the config field needs to be filled in before the form can be submitted.
minLength	integer	Specifies the minimum length of textual config data.
maxLength	integer	Specifies the maximum length of textual config data.
min	number	Specifies the minimum value of numerical config data.
max	number	Specifies the maximum value of numerical config data.
pattern	regular expression	Specifies a regular expression that defines a pattern the entered config data needs to follow.
multiple	boolean	Specifies that multiple config options can be selected at once.

🚧
Note
Haiilo Home will ignore invalid configuration attributes (e.g. if the manifest defines a multiple value for a text field, a placeholder for a checkbox field or options for a field other than select/radio).

Field types

The following field types are currently supported as a type property:

"text" defines a single-line text input field.
"textarea" defines a multi-line text input field (a text area).
"number" defines a numeric input field.
"checkbox" defines a checkbox.
"radio" defines a radio button.
This fields requires the definition of options.
"select" defines a drop-down list (allows multi-selection via the "multiple" flag).
This fields requires the definition of options.
"user" defines a Haiilo Home user selection field (allows multi-selection via the "multiple" flag).

Global configuration

A plug-in configuration can not only be rendered on an instance basis. You can also provide global configuration options that apply per plug-in installation. Simply add a "config" definition on the top level of your manifest instead of the entry point level. This global configuration will be placed in the list of plug-ins in the administration area. Note that only plug-ins with a valid global configuration can be activated.

Global and local configurations will be merged when they are requested. Local configurations will override global configuration values, if they use the same key and are provided by the user. However, global configuration values will not be used as a default value for local configuration fields, since the two field definitions may differ in their type and might not be compatible.

Retrieving configuration values

Plug-in configuration (both global and local) are automatically included in Haiilo Home's response to the initialization message of your plugin. If the initialization has been successful, Haiilo Home sends a signed JWT response that includes all configuration values. They can be found in the cfg-scoped fields of the response token.