Theme Configuration

Theme Configuration is the feature that allows theme developers to make a storefront theme configurable by a store owner.

The theme developers can include a list of the supported configuration options and available values.

The store owners can apply the theme configuration settings on various levels.

Theme Configuration Definition

To define theme configuration options, it is enough to add the configuration section in the theme configuration file, for example, DemoBundle/Resources/views/layouts/first_theme/theme.yml.

A theme configuration

options are organized into sections
section identifiers must be unique within the theme in which they are defined
each section must have a label as well (required, cannot be empty)
options must have type and label (required, cannot be empty)

The theme configuration has the following option types:

Type	Description
checkbox	A single input field with two static values: checked and unchecked.
select	A multi-purpose field is used to choose one or more defined options from a drop-down list.
radio	A single radio button is used to choose one defined option from group.
menu_selector	A single field is used to choose one menu name from a list. The menu names are provided dynamically.
content_block_selector	A single field is used to choose one content block from a list. The block names are provided dynamically. Previews keys depend on content block alias.
product_page_template	A single field is used to choose one page template from a list (static values: default, tabs, wide).
quick_access_button_config	A multi-purpose field is used to represent QuickAccessButton settings. Previews depend on type field values (menu, web_catalog_node).
integer	An input field looks like a text box and accepts only integer numbers.
number	An input field looks like a text box and accepts numbers. This type has options for the scale and rounding.
text	An input field represents the most basic text field.

The theme configuration has the following option parameters:

Option	Description	Required
label	The label is displayed in the admin panel for a option in theme configuration UI.	yes
type	The type of the option in theme configuration UI.	yes
default	The value is displayed by default.	no
values	Available option values.	no
attr	Attributes to be added to the form field HTML tag.	no
options	Options to be added to the form field.	no
previews	Images that will illustrate UI changes if this option is selected.	no

Example:

#DemoBundle/Resources/views/layouts/first_theme/theme.yml
configuration:
    sections:
        header:
            label: Header
            options:
                header_menu:
                    label: Header Menu
                    type: checkbox
                    default: unchecked
                    options:
                        required: false
                    previews:
                        checked: 'path/to/image/checked.png'
                        unchecked: 'path/to/image/unchecked.png'
        general:
            label: General
            options:
                screen:
                    label: Screen
                    type: select
                    values:
                        integrated: Integrated
                        standalone: Standalone
                    previews: []
                filters_position:
                    label: Filters Position
                    type: radio
                    default: top
                    values:
                        top: top
                        sidebar: sidebar
                negative_number:
                    label: Negative Number
                    type: number
                    default: -2.35
                    options:
                        constraints: [] # overrides the default PositiveOrZero constraint

Note

Translation keys can be used for the labels section, and the labels and values options. Also, if preview images are defined in the DemoBundle/Resources/public/images directory, make sure they are in the project’s public directory.

Note

For default previews and options when they don’t have images, the reserved preview key _default can be used.

Theme Configuration Validation

To validate theme configuration options, use the following command:

bin/console oro:theme:configuration:validate