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 ( |
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
multiplevalue for a text field, aplaceholderfor a checkbox field oroptionsfor a field other thanselect/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.
Updated 4 days ago