Theme options

Each theme can define its own configuration options. This can enable web site 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 ImpressPages forms. Most commonly used field types are: Select, Text, Textarea, Color, Range, Checkbox. 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']
    }
]

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 differnet 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 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 ImpressPages 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 \Ip\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"
    }
]