Configuration

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

To simplify the configuration of plug-ins, COYO 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 COYO. In this way, created forms are perfectly embedded in the COYO UI/UX. The configuration values will be handed to the plug-in during the initialization process.

📘

Hint

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

COYO 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 COYO 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 COYO's response to the initialization message of your plugin. If the initialization has been successful, COYO sends a signed JWT response that includes all configuration values. They can be found in the cfg-scoped fields of the response token.


Did this page help you?