In this article, we go through examples of using custom theme settings.

Also read:

Implementing a selection list (<select>)

In this example, a select list type setting is used to determine the font of <h1>-level headings.

  1. Add a select list setting to the theme.xml settings file and specify the selectable values there:
    <?xml version="1.0"?>
<Theme>
    ...
    <ThemeSettings>
        <Setting
                type="select"
                name="font_family_heading"
                name="font_family_heading_label"
                description="font_family_heading_description"
                default="Lato">

            <Option value="font-family-heading-cormorant" label="Cormorant Garamond" />
            <Option value="font-family-heading-contrail" label="Contrail One" />
            <Option value="font-family-heading-mochiy" label="Lato" />
        </Setting>
    </ThemeSettings>
    ...
</Theme>
  2. Add the texts used by the setting to the theme's language file (e.g. translations/theme.en.yaml):
    font_family_heading_label: Main heading font
font_family_heading_description: Select font for main heading
  3. Add a function to the <head> element of the theme that uses the values of the dropdown list:
    {Doctype}
<html>
    ...
    <head>
        ...
        <style type="text/css">
            h1 {
                font-family: {Setting(name: 'primary_color')};
            }
        </style>

Now, in the theme settings menu, there is a new Main heading font named <select> menu, from which you can choose a font for <h1> headings.

Implementing a number selection

In this example we implement a number field that allows the theme user to set a general default font size for all text (for the <body> element):

  1. Add a number field setting to the theme settings:

    You can set a default value, minimum and maximum values, a step value, and a unit for the field:

    <?xml version="1.0"?>
<Theme>
    ...
    <ThemeSetting>
        <Setting
            type="integer"
            name="font_size"
            label="font_size_label"
            description="font_size_description"
            default="12"
            min="0"
            max="24"
            step="1"
            unit="px" />
    </ThemeSetting>
    ...
</Theme>
  2. Add the texts used by the setting to the theme's language file:
    font_size_label: Font size
font_size_description: Enter font size for all text
  3. Add a function to the theme that uses the value of the number field:
    {Doctype}
<html>
    ...
    <head>
    ...
        <style>
            body {
                font-size: {Setting(name: 'font_size')}
            }
        </style>

    In the font-size specification, there is no need to use a unit, as it is already included in the setting specification.

Now, in the theme settings menu, there is a new Main heading font dropdown list, from which you can choose a font for <h1> headings.

Implementing a color specification

In this example, you add a color selection field to theme settings that specifies the text color of the <p> elements:

  1. Add a color code selection option to the theme.xml settings file.
    <?xml version="1.0"?>
<Theme>
    ...
    <ThemeSettings>
        <Setting
            type="color"
            name="primary_color"
            label="primary_color_label"
            description="primary_color_description"
            default="#378940"/>
    </ThemeSettings>
    ...
</Theme>

    The setting adds a WYSIWYG color wheel element to the theme settings, from which the theme user can choose a color.

  2. Add the texts used by the setting to the theme's language file (e.g. translations/theme.en.yaml):
    primary_color_label: Primary color
primary_color_description: Primary color description
  3. Add a CSS markup to the theme that uses the color chosen by the user.

    This example sets the color you select as the text color for all <p> elements:

    {Doctype}
<html>
    ...
    <head>
        ...
        <style type="text/css">
            p {
                color: {Setting(name: 'primary_color')};
            }
        </style>

    The color selected by the user is printed on the theme as hex code.

Now the theme settings have a new Primary color setting, where the color chosen by the user acts as the color of the text pieces.