Configuration Schema

The default input for a component configuration is a JSON text area.

Generic configuration screenshot

If you define a JSON schema, we are able to display a nice form and let the user to fill the JSON using a set of defined inputs.

Configuration schema

Using the configuration schema also allows us to validate the user input on frontend.

Creating Schema

JSON schemas are well documented on the json-schema.org website. For their developing and testing, use, for example, JSON Editor available on-line. Remember to list all configuration properties as required. This is to make sure that the actual configuration will always contain all properties. If you want a property to be optional, set a default value for it. The supported formatting options for the editor are available in the official editor documentation.

Example

Let’s assume your component accepts the following configuration:

{
    "username": "foo",
    "#password": "baz",
    "dateFrom": "yesterday",
    "dateTo": "today"
}

This looks like an appropriate form:

Configuration form

The form above can be created using this JSON Schema:

{
    "title": "Parameters",
    "type": "object",
    "required": [
        "dateFrom",
        "dateTo",
        "username",
        "#password"
    ],
    "properties": {
        "username": {
            "title": "Username",
            "type": "string",
            "minLength": 1,
            "default": "",
            "propertyOrder": 1
        },
        "#password": {
            "title": "Password",
            "type": "string",
            "format": "password",
            "minLength": 1,
            "default": "",
            "propertyOrder": 2
        },
        "dateFrom": {
            "title": "Date from",
            "type": "string",
            "description": "Any date accepted by strtotime (http://php.net/manual/en/function.strtotime.php) function",
            "minLength": 1,
            "default": "",
            "propertyOrder": 3
        },
        "dateTo": {
            "title": "Date to",
            "type": "string",
            "description": "Any date accepted by strtotime (http://php.net/manual/en/function.strtotime.php) function",
            "minLength": 1,
            "default": "",
            "propertyOrder": 4
        }
    }
}