theme.xml: settings


In addition to the direct access to its source code (HTML, CSS, JavaScript), a design theme can also enable a Webasyst to specify various parameters which will affect the visual appearance of his website; e.g., header color, background color, logo image, navigation menu style, etc. Use of such settings prevents modifications of the theme's source code yet enables a user to easily change something in his website. Here is how the settings screen may appear in Webasyst backend:

The following types of controls can be used to specify various design theme parameters:

  • text field (text)
  • dropdown list (select)
  • checkbox (checkbox)
  • radio buttons (radio)
  • color selector (color)
  • image file uploading field (image)
  • image list (image_select)
  • text hint (paragraph)
If the control type is not specified for a settings control, then that control will be displayed and handled as a simple text field (text).

In order to add settings controls to your design theme's manifest file theme.xml, create one common settings element with nested setting elements, each having a control_type attribute containing the control type (according to above control type list) and a var attribute containing the variable name to access its value in HTML templates.

Settings parameters

Required parameters

Each setting element must contain the following set of nested elements (in the specified order):

  • value: default value used by the design theme, if a user has not specified anything.
  • filename (only for image type controls): format of the path, inside the design theme directory, at which the uploaded file must be saved; e.g., if format images/logo.* is specified for logo uploading settings field, then the file selected by a user will be saved inside the images/ subdirectory of the design theme directory, with name logo and its original file name extension preserved.
  • name: the name of the settings control displayed in the design theme settings screen.
  • description: optional element with arbitrary descriptive text displayed in the design theme settings screen.
  • options (only for select, image_select, and radio type controls): common element containing nested option elements corresponding to the selectable control values, each having either a value attribute, or a nested value element with a text block. For image_select type controls, the value attribute must contain paths to selectable image files relative to the design theme directory path (recommended).
You may specify multiple name, description, and value elements, for each of language locale. In this case, each such element must contain a locale attribute with the name of the corresponding locale.

Optional parameters

A setting element can contain the following optional nested elements:

  • tooltip: a descriptive string of text for a user; the locale attribute must contain the locale name for which this text is written; e.g.,
    <tooltip locale="en_US">hint text</tooltip>

Hidden settings

Any setting can be made hidden. To do so, add the invisible attribute to a setting XML element and assign it value true.

<setting var="..." control_type="..." invisible="true">

Hidden settings are by default not displayed to a user. They can be displayed using “Show hidden settings” checkbox.

Grouping settings

Large lists of settings can be grouped so that users can see a list of groups rather than the entire long list of all available settings. Each group can be expanded to view only the settings within that group, other groups’ settings not interfering with the process.

To create a settings group, add a setting element with group_divider type before the first setting to be included in the new group.

<setting var="group_1" control_type="group_divider">
    <name locale="en_US">Group 1</name>

<setting var="settings_1">
    <name locale="en_US">Setting #1 for group 1</name>

<setting var="settings_2">
    <name locale="en_US">Setting #2 for group 1</name>

Settings groups can be placed inside each other. To do so, add a value element for the nested setting containing a value in the “parent_ID/own_ID” format.

<setting var="group_1" control_type="group_divider">
    <name locale="en_US">Group 1</name>


<setting var="group_2" control_type="group_divider">
    <name locale="en_US">Group 2</name>

<setting var="settings_3">
    <name locale="en_US">Setting #3 for group 2</name>

Design theme settings file example

Below is shown a portion of a theme.xml file with examples of different design theme settings controls:

    <setting control_type="text" var="caption">
        <value locale="en_US">Sample caption</value>
        <value locale="ru_RU">Пример заголовка</value>
        <name locale="en_US">Header caption</name>
        <name locale="ru_RU">Заголовок сайта</name>
    <setting control_type="select" var="color_scheme">
        <name locale="en_US">Color scheme</name>
        <name locale="ru_RU">Цветовая схема</name>
            <option value="light">
                <name locale="en_US">light</name>
                <name locale="ru_RU">светлая</name>
            <option value="dark">
                <name locale="en_US">dark</name>
                <name locale="ru_RU">темная</name>
    <setting control_type="checkbox" var="show_subscription_form">
        <name locale="en_US">Show subscription form</name>
        <name locale="ru_RU">Показывать форму подписки</name>
    <setting control_type="radio" var="menu_type">
        <name locale="en_US">Main menu type</name>
        <name locale="ru_RU">Тип главного меню</name>
            <option value="simple">
                <name locale="en_US">simple</name>
                <name locale="ru_RU">простое</name>
                <description locale="en_US">Simple tree-like menu in the left sidebar.</description>
                <description locale="ru_RU">Простое древовидное меню в левой панели сайта.</description>
            <option value="dropdown">
                <name locale="en_US">dropdown</name>
                <name locale="ru_RU">выпадающее</name>
                <description locale="en_US">Dynamic menu with great visual effects.</description>
                <description locale="ru_RU">Динамическое меню с привлекательными визуальными эффектами.</description>
    <setting control_type="color" var="header_color">
        <name locale="en_US">Header color</name>
        <name locale="ru_RU">Цвет заголовка</name>
    <setting control_type="image" var="logo">
        <name locale="en_US">Your logo</name>
        <name locale="ru_RU">Логотип</name>
        <description locale="en_US">128×128px large image.</description>
        <description locale="ru_RU">Изображение размером 128×128 пикселей.</description>
    <setting control_type="image_select" var="background_image">
        <name locale="en_US">Background image</name>
        <name locale="ru_RU">Фоновое изображение</name>
            <option value="images/themesettings/backgrounds/01.png" />
            <option value="images/themesettings/backgrounds/02.png" />
            <option value="images/themesettings/backgrounds/03.png" />
            <option value="images/themesettings/backgrounds/04.png" />

Use of setting values in Smarty templates

Settings values specified by a user are accessible in design theme templates in the form {$theme_settings.var}, where the var part must be replaced with the variable name specified in the var attribute of the corresponding settings control. For example, in order to display the user-uploaded logo (suppose that the corresponding settings control has value var="logo"), you may add the following code to a design theme template:

{if $theme_settings.logo}
<img src="{$theme_settings.logo}">