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:

AttributeTypeDescription
keystringThe key that relates to the configuration model.
typestringThe type of field to be rendered.
labelTranslation mapA label for the field.
placeholder Translation mapA placeholder for the field.
description Translation mapA description for the field.
options object[]A list of field option for a form field with options (radio/select).
options.valueboolean | number | stringThe option value.
options.labelTranslation mapThe option label.
options.description Translation mapThe option description.
default boolean | number | stringA default value for the field.
required booleanSpecifies whether the config field needs to be filled in before the form can be submitted.
minLength integerSpecifies the minimum length of textual config data.
maxLength integerSpecifies the maximum length of textual config data.
min numberSpecifies the minimum value of numerical config data.
max numberSpecifies the maximum value of numerical config data.
pattern regular expressionSpecifies a regular expression that defines a pattern the entered config data needs to follow.
multiple booleanSpecifies 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.