theme.xml: настройки

Содержание...

Помимо прямого доступа к исходному кода дизайна фронтенда (HTML, CSS, JavaScript), тема дизайна может также предоставлять пользователю возможность указывать различные параметры, влияющие на отображение сайта, например: заголовок в шапке сайта, цвет фона, логотип, вариант оформления меню и т. п. Такие настройки позволяют пользователю изменять внешний вид сайта, не внося изменений в исходный код шаблонов. Вот так может выглядеть раздел настроек темы дизайна в бекенде Вебасиста:

Для настройки темы дизайна могут использоваться следующие виды элементов управления:

  • текст (text)
  • выпадающий список (select)
  • флажок (checkbox)
  • список радио-кнопок (radio)
  • выбор цвета (color)
  • выбор цвета с помощью кнопок (color_select)
  • изображение (image)
  • список изображений (image_select)
  • текстовая подсказка (paragraph)
Если тип элемента настроек не указан, то он будет интерпретирован как поле для ввода текста (text).

Для создания элементов настроек необходимо в файле-манифесте theme.xml указать общий элемент settings с вложенными элементами setting, каждый из которых должен содержать атрибут control_type с указанием типа элемента настроек (см. список выше) и атрибут var с именем переменной для доступа к значению элемента настройки в шаблонах темы дизайна.

Параметры настроек

Обязательные элементы настройки

Каждый элемент setting должен содержать следующий набор вложенных элементов (именно в таком порядке):

  • value — значение по умолчанию, которое должно использоваться темой дизайна, если пользователь не указал собственное значение.
  • filename — только для элемента настроек типа image: формат пути, по которому должен быть сохранен файл внутри директории темы; например, если для элемента настроек для загрузки изображения (логотипа) указан формат images/logo.*, то пользовательский файл, загруженный с помощью такого элемента, будет сохранен в поддиректории images/ внутри директории темы дизайна с именем logo и сохранением своего оригинального расширения.
  • name — название элемента настроек, которое будет видно пользователю на странице настроек.
  • description — необязательный элемент с текстом описания элемента настроек, видимый пользователю, который выполняет настройку темы дизайна.
  • options — только для элементов типов select, image_select и radio: общий элемент, содержащий вложенные элементы option, каждый из которых может содержать либо атрибут value со значением, либо вложенный элемент value со значением в виде текстового блока. Для элементов настроек типа image_select в значении атрибута value должен быть указан путь к одному из изображений (рекомендуется указывать сокращенные пути к файлам изображений относительно директории темы дизайна).
Элементы name, description и value могут указываться для каждого элемента настроек в нескольких экземплярах — по одному для каждой языковой локали. У каждого такого элемента должен присутствовать атрибут locale с указанием локали, для которой предназначено значение элемента.

Необязательные элементы настройки

Элемент setting может также содержать следующие необязательные элементы:

  • tooltip — поясняющая подсказка для пользователя; в атрибуте locale нужно указать языковую локаль, для пользователей которой предназначена подсказка, например: 
    <tooltip locale="ru_RU">текст подсказки</tooltip>

Скрытые настройки

Любую настройку можно сделать скрытой. Для этого XML-элементу настройки нужно добавить атрибут invisible со значением true.

Пример
<setting var="..." control_type="..." invisible="true">
...
</setting>

Скрытые настройки по умолчанию не видны пользователю, но их можно показать, включив флажок «Показать скрытые настройки».

Группировка настроек

Большие списки настроек удобно группировать: на странице настроек темы дизайна виден не сразу весь список настроек, а только названия групп. Каждую группу можно отдельно развернуть и посмотреть, какие настройки входят в состав группы. Настройки из других групп при этом не мешают.

Чтобы создать группу настроек, перед элементом setting той настройки, которая должна стать первой в этой группе, нужно добавить элемент настройки с типом group_divider. Если добавить в этот элемент атрибут icon_class="..." с классом иконки Font Awesome, то эта иконка будет показана рядом с названием этой группы настроек.

Пример
<setting var="group_1" control_type="group_divider">
    <name locale="ru_RU">Группа 1</name>
</setting>

<setting var="settings_1">
    <name locale="ru_RU">Настройка №1 для группы 1</name>
</setting>

<setting var="settings_2">
    <name locale="ru_RU">Настройка №2 для группы 1</name>
</setting>

Группы настроек можно вкладывать друг в друга. Для этого вложенной группе нужно указать значение value в виде «ID_родителя/свой_ID».

Пример
<setting var="group_1" control_type="group_divider">
    <name locale="ru_RU">Группа 1</name>
</setting>

...

<setting var="group_2" control_type="group_divider">
    <value>group_1/group_2</value>
    <name locale="ru_RU">Группа 2</name>
</setting>

<setting var="settings_3">
    <name locale="ru_RU">Настройка №3 для группы 2</name>
</setting>

Пример файла настроек темы дизайна

Ниже показан фрагмент файла theme.xml с примером указания различных элементов настроек темы дизайна:

Пример
<settings>
    <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>
    <setting control_type="select" var="color_scheme">
        <value>light</value>
        <name locale="en_US">Color scheme</name>
        <name locale="ru_RU">Цветовая схема</name>
        <options>
            <option value="light">
                <name locale="en_US">light</name>
                <name locale="ru_RU">светлая</name>
            </option>
            <option value="dark">
                <name locale="en_US">dark</name>
                <name locale="ru_RU">темная</name>
            </option>
        </options>
    </setting>
    <setting control_type="checkbox" var="show_subscription_form">
        <value>1</value>
        <name locale="en_US">Show subscription form</name>
        <name locale="ru_RU">Показывать форму подписки</name>
    </setting>
    <setting control_type="radio" var="menu_type">
        <value>dropdown</value>
        <name locale="en_US">Main menu type</name>
        <name locale="ru_RU">Тип главного меню</name>
        <options>
            <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>
            <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>
            </option>
        </options>
    </setting>
    <setting control_type="color" var="header_color">
        <value>#777777</value>
        <name locale="en_US">Header color</name>
        <name locale="ru_RU">Цвет заголовка</name>
    </setting>
    <setting var="color_accent" control_type="color_select">
        <value>#A538DC</value>
        <name locale="ru_RU">Акцентный цвет</name>
        <name locale="en_US">Accent color</name>
        <description locale="ru_RU"></description>
        <description locale="en_US"></description>
        <options>
        <option value="#BA2621">
            <name locale="ru_RU">Красный</name>
            <name locale="en_US">Red</name>
        </option>
        <option value="#2E941A">
            <name locale="ru_RU">Зеленый</name>
            <name locale="en_US">Green</name>
        </option>
        <option value="#516DE0">
            <name locale="ru_RU">Синий</name>
            <name locale="en_US">Blue</name>
        </option>
        </options>
    </setting>
    <setting control_type="image" var="logo">
        <value></value>
        <filename>images/logo.*</filename>
        <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>
    <setting control_type="image_select" var="background_image">
        <value>images/themesettings/backgrounds/01.png</value>
        <name locale="en_US">Background image</name>
        <name locale="ru_RU">Фоновое изображение</name>
        <options>
            <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" />
        </options>
    </setting>
</settings>

Использование значений настроек в шаблонах

Значения, выбранные или введенные пользователем на странице настройки темы дизайна, доступны в шаблонах темы в виде конструкций {$theme_settings.var}, где вместо var нужно подставить значение атрибута var соответствующего элемента настроек. Например, чтобы добавить в дизайн сайта загруженный пользователем логотип (допустим, для поля загрузки логотипа указано значение var="logo"), необходимо добавить в шаблон темы дизайна код следующего вида:

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