Plugin Configurations with YAML
Each plugin should have a configuration file written in YAML. YAML is a widespread and easy-to-understand configuration language that can be transformed into an array easily. Like an array, YAML uses simple key-value pairs. Deeper levels for multidimensional arrays are indicated with indentation. Indentation is made by two spaces. Do not use tabs for indentation, because it will break the transformation.
Three Parts of the Configuration File
The YAML-configuration file for TYPEMILL can have up to three parts:
- The first part is mandatory and defines the basic meta information about a plugin like the name, the version, and the author.
- The second part is optional and defines the default values of the plugin. It must start with
- The third part is optional and defines the input fields for the user interface. It must start with
In the first part, the following meta information is used by TYPEMILL, and displayed in the TYPEMILL user interface:
name: The name of the plugin version: 1.0.0 description: A short description. author: The name of the plugin author. homepage: a link to a website with informations about the plugin licence: Licence like MIT or others
The version number is used by TYPEMILL to check for updates, and to notify the user of new versions. Please use a valid schema for versioning. We recommend a simple system like
1.2.3 where position
1 is a major release,
2 is a minor or feature release, and
3 is a bugfix (as a rule of thumb).
The Default Settings
The second part defines the default settings and always starts with
settings:, followed by simple key-value pairs indented with two spaces:
settings: key1: value1 Key2: value2 key3: value3
The default settings are merged into the main settings of TYPEMILL, and are available across the whole platform for plugins and themes. The default settings are overwritten by the individual settings of the user, if present.
The Field Definitions
The third part defines the user interface for individual settings, and always starts with
fields:. If users should overwrite the default settings with individual settings in the interface, then the name of the defined field must be the same as the name of the default setting that should be overwritten. For example:
settings: position: top forms: fields: position: type: select label: Position of Element bottom: Bottom top: Top
This way, the user input for the field
position will overwrite the default value for
This is the rule if you want to bind default settings and user inputs. But you don't have to do this:
- You can define a value with
settings:and skip the
fields:if you don't want a user to be able to change the default value.
- You can define a
field:and skip the
settings:if you don't need a default value for an input field.
Learn more about fields and field-types in the chapter about forms.