Theme options

Each theme can define its own configuration options. This can enable website administrator to use theme options panel for adjusting theme's colors, fonts or other settings. It is extremely valuable if you create themes for sale, as then your theme can be easily adjusted without additional coding.

Theme options are defined in options section of Theme/myTheme/setup/theme.json file:

"options": [
        {
            "label": "Body background color",
            "name": "bodyBackgroundColor",
            "type": "Color",
            "default": "#fff"
        },
        {
           ...
        }
]

Field types

You can use almost any field type available in Construct forms. Most commonly used field types are: Select, Text, Textarea, Color, Range, Checkbox, RepositoryFile. All these options accept label, name, note, default parameters.

Select option accepts additional values attribute.

"options": [
    {
        "label": "Header type",
        "name": "headerType",
        "type": "Select",
        "default": "Minimal",
        "values": ['Minimal', 'Medium', 'Full']
    }
]

All values except Select, Color and RepositoryFile may have an additional parameter units which value may be px, %, etc. If this value is set, units will be automatically added before passing the value to the LESS.

Also, all variables are automatically escaped before passing to LESS. You can turn this off on per field basis by adding "escape" : 0.

Not all field types are meaningful in theme options box. E.g. Antispam, Hidden, Captcha fields make no sense in this context.

Get theme options in theme layout or plugin

You as a developer have to take care to make options work. You can access selected values in theme's layout file using function ipGetThemeOption and render output differently or include different CSS files.

<?php echo ipGetThemeOption('bodyBackgroundColor'); ?>

All option values are by default available in LESS CSS files.

Grouping theme options

If you have many options, you can group them. Create the option with "type": "group" and use the following format:

"options": [
    {
        "label": "Group label",
        "type": "group",
        "options": [
            {
                ...
            },
            {
                ...
            },
            {
                ...
            }
        ]
    },
    {
        "label": "Group2 label",
        "type": "group",
        "options": [
            {
                ...
            },
            {
                ...
            },
            {
                ...
            }
        ]
    }
]

Real time preview

By default, when the user changes the value in options, he has to refresh the preview window to see how the result looks like. You can implement a real-time preview of options for convenience.

To do so, create a JavaScript preview method for options that are possible to preview in real time. Put those functions in Theme/myTheme/setup/options.js file in following structure:

var ipDesignOptions = {
    bodyBackgroundColor: function (value) {
        'use strict';
        $('body').css('background-color', value);
    }
};

Example

See the sample Air theme provided within default Construct installation. Theme/Air/setup folder contains theme.json and option.js files, which illustrate the usage of theme options.

Custom input fields (since 4.3.1)

You can create your own field types and use them in option box. To do so, extend \Construct\Form\Field class (e.g. http://www.impresspages.org/docs/custom-form-field-example) and use full class name as field type setting. E.g.

"options": [
    {
        "label": "My custom field",
        "name": "xxx",
        "type": "Theme\\MyTheme\\MyCustomField",
        "default": "defaultValue"
    }
]