Настройки темы

WS 0.971

Файл theme-settings.json описывает настройки, которые пользователь может изменять через административную панель.

Сохранённые значения доступны в шаблонах через статический класс CurrentTheme.

Расположение файла

Разместите файл в корне темы рядом с theme-info.json:

text

example/
  index.php
  theme-info.json
  theme-settings.json

Файл является необязательным. Если настраиваемые значения теме не нужны, создавать его не требуется.

Минимальный пример

json

{
    "general": {
        "logo": {
            "type": "image",
            "name": {
                "ru": "Логотип"
            },
            "default": ""
        }
    }
}

После выбора темы поле logo появится в её настройках.

Получение сохранённого значения:

php

$logo = CurrentTheme::data('logo');

Группы настроек

На верхнем уровне поддерживаются две группы:

Группа	Назначение
`general`	Основные настройки темы.
`variables`	Дополнительные переменные шаблона.

Обе группы необязательны:

json

{
    "general": {},
    "variables": {}
}

Другие группы не поддерживаются и делают файл настроек некорректным.

В PHP значения обеих групп получаются одинаково через CurrentTheme::data().

Структура поля

Каждое поле записывается под уникальным ключом:

json

{
    "general": {
        "accent-color": {
            "type": "color",
            "name": {
                "ru": "Основной цвет",
                "en": "Accent color"
            },
            "default": "#000000"
        }
    }
}

Поле содержит:

Параметр	Описание
`type`	Тип элемента административной формы.
`name`	Локализованные названия поля.
`default`	Значение по умолчанию.

Ключ поля может содержать:

латинские буквы
цифры
_
-

Один ключ нельзя повторять в разных группах.

Названия полей

Параметр name должен быть массивом переводов:

json

{
    "name": {
        "ru": "Логотип",
        "en": "Logo"
    }
}

Название на русском языке обязательно.

Код языка записывается строчными латинскими буквами и может содержать цифры или -.

Если перевода для текущего языка административной панели нет, используется русское название.

Поддерживаемые типы

Тип	Значение
`input`	Однострочный текст.
`textarea`	Многострочный текст.
`editor`	Содержимое визуального редактора.
`checkbox`	Логическое значение.
`multi`	Массив повторяющихся значений.
`table`	Массив табличных данных.
`image`	Значение поля выбора изображения.
`video`	Значение поля выбора видео.
`file-all`	Значение поля выбора файла.
`color`	Строковое значение цвета.

Неизвестный тип делает весь theme-settings.json некорректным.

Значения по умолчанию

Тип значения default зависит от типа поля.

Строковые поля

Для текстовых полей, файлов и цвета используется строка:

json

{
    "type": "input",
    "name": {
        "ru": "Телефон"
    },
    "default": ""
}

Скалярные значения приводятся к строке. Логическое значение для строкового поля превращается в пустую строку.

Checkbox

Для checkbox используется true или false:

json

{
    "type": "checkbox",
    "name": {
        "ru": "Показывать контакты"
    },
    "default": true
}

Другой тип значения будет заменён на false.

Multi и table

Для multi и table используется массив:

json

{
    "type": "multi",
    "name": {
        "ru": "Социальные сети"
    },
    "default": []
}

Другой тип значения будет заменён на пустой массив.

Полный пример

json

{
    "general": {
        "logo": {
            "type": "image",
            "name": {
                "ru": "Логотип",
                "en": "Logo"
            },
            "default": ""
        },
        "accent-color": {
            "type": "color",
            "name": {
                "ru": "Основной цвет",
                "en": "Accent color"
            },
            "default": "#1b1b1b"
        },
        "show-contacts": {
            "type": "checkbox",
            "name": {
                "ru": "Показывать контакты",
                "en": "Show contacts"
            },
            "default": true
        }
    },
    "variables": {
        "phone": {
            "type": "input",
            "name": {
                "ru": "Телефон",
                "en": "Phone"
            },
            "default": ""
        },
        "legal": {
            "type": "textarea",
            "name": {
                "ru": "Реквизиты",
                "en": "Legal information"
            },
            "default": ""
        }
    }
}

Получение значений

Строка

php

$phone = CurrentTheme::data('phone');

Значение по умолчанию

Второй аргумент используется, если ключ отсутствует:

php

$phone = CurrentTheme::data(
    'phone',
    'Телефон не указан'
);

Checkbox

php

if (CurrentTheme::data('show-contacts', true)) {
    ?>
    <div class="contacts">
        <?php echo CurrentTheme::data('phone'); ?>
    </div>
    <?php
}

Массив

php

$items = CurrentTheme::data('social-links', []);

foreach ($items as $item) {
    // Вывод элемента.
}

Форма массива зависит от настройки поля в административной панели.

Использование изображения

php

$logo = CurrentTheme::data('logo');

if ($logo !== '') {
    ?>
    <img src="<?php echo $logo; ?>" alt="Логотип">
    <?php
}

CurrentTheme::data() возвращает сохранённое значение. Метод не формирует URL ресурса и не изменяет его.

Сохранение настроек

После создания или изменения theme-settings.json:

Откройте раздел тем в административной панели.
Выберите нужную тему.
Заполните появившиеся поля.
Сохраните настройки.
Проверьте значения в шаблоне темы.

Значения сохраняются отдельно для каждой папки темы.

Если сохранённого значения нет, используется default из theme-settings.json.

Если поле удалено из manifest, его сохранённое значение больше не попадает в данные активной темы.

Проверка файла

Настройки не будут сохранены, если:

JSON содержит синтаксическую ошибку
файл находится не в корне темы
используется неизвестная группа
ключ поля имеет недопустимый формат
ключ повторяется в группах
отсутствует поддерживаемый type
отсутствует русское название поля
название поля пустое

Некорректный файл не делает theme-info.json недействительным, но CMS не загружает значения настроек и не позволяет сохранить настройки выбранной темы.

Проверка результата

После сохранения проверьте:

появились ли поля в нужных разделах административной панели
сохраняются ли строковые значения
возвращает ли checkbox логическое значение
возвращают ли multi и table массивы
применяются ли значения default
возвращает ли второй аргумент CurrentTheme::data() резервное значение