Настройки тем
Обновлено
Откуда берутся настройки
Собственных настроек у плагина нет. Он читает настройки выбранной темы через themes_get_settings. Их названия, состав и значения по умолчанию определяет установленная тема, поэтому единой таблицы названий полей для всех сайтов не существует.
Агент получает ключ key, название name, тип поля control_type, текущее значение value, значение из поставки default и варианты options, если они есть. Название возвращается с учётом текущей локали Webasyst. В запросе к агенту называйте поле так, как оно подписано в русском интерфейсе вашей темы.
| Вид настройки | Что можно сделать | Значения / по умолчанию |
|---|---|---|
Текст и многострочный текст (text, textarea) |
Изменить обычный текст без HTML, скриптов и Smarty | Строка UTF-8 до 8192 байт; значение по умолчанию берётся из поставки темы |
Список, переключатель вариантов, выбор изображения-варианта (select, radio, image_select) |
Выбрать существующий вариант | Точный ключ из options; для image_select это может быть полный путь к картинке варианта |
Флажок (checkbox) |
Включить или выключить | В запросе JSON true / false; выключенное значение хранится как пустая строка либо уже используемый темой 0 |
Цвет и палитра (color, color_select) |
Задать цвет или пустое значение | #RGB, #RRGGBB либо пустая строка; смысл пустого значения определяет тема |
| JSON в текстовом поле | Изменить объект или список с учётом правил слияния | Объект или массив, в том числе строкой JSON; результат до 64 КиБ |
Загрузка изображения или файла (image, file) |
Только прочитать доступное значение | Загрузка через этот инструмент не поддерживается |
| Многоязычное значение, представленное массивом | Только прочитать | Изменение не поддерживается |
| Поля с кодом, HTML, CSS, скриптами и счётчиками | Только прочитать | Изменение через настройки запрещено; код в файлах темы меняется инструментами файлов |
| Пароли и ключи с защищёнными именами | Значения скрыты | Возвращаются null и redacted: true |
| Другие типы полей, несовместимые текущие значения | Только прочитать | Причина указывается в read_only_reason |
image_select выбирает готовый вариант, а image загружает изображение — это разные типы полей.
Порядок изменения
- Прочитать настройки и сохранить
revision. - Передать выбранные ключи в
patch, а полученную ревизию — вexpected_revision. - Выполнить предпросмотр, проверить
diffиnormalized_patch. - Подтвердить и применить изменение.
За один запрос допускается от 1 до 50 настроек, общий размер передаваемого изменения — до 64 КиБ. Если тема успела измениться, инструмент вернёт revision_conflict: нужно прочитать её заново и повторить предпросмотр.
Для длинных списков запрашивайте конкретные ключи через keys: это позволяет получить JSON целиком в пределах ограничения ответа. При чтении общего списка можно использовать prefix, offset, limit; по умолчанию возвращается до 100 настроек, максимально — 200 на страницу.
Агент показывает прежний и новый цвет, ключ настройки и предупреждение об изменении для всех поселений с этой темой.
Как меняется JSON
Правило зависит от структуры текущего значения.
| Структура | Правило |
|---|---|
| Объект | Переданные поля меняются, остальные сохраняются; null удаляет поле |
Массив записей с уникальным uid либо id и, при наличии, app |
Поля записей объединяются по идентификатору. Итоговый порядок и состав записей берутся из переданного массива |
| Прочий массив | Заменяется целиком |
В массиве с идентификаторами нужно передать все записи, которые требуется оставить. Пропущенные записи удаляются. Совет «передать только изменяемое поле» применим к объекту и полям сохраняемой записи, но не к составу массива.
Форму значения сохраняют: массив остаётся массивом, объект — объектом. Объект с ключами "0", "1" не становится массивом.
Записи списка, уже содержащие HTML или код, можно сохранить, переместить или удалить, но нельзя изменить. Добавлять HTML, Smarty, исполняемые ссылки и поля с кодом или реквизитами доступа инструмент не разрешает. Некорректный JSON в текущем значении делает поле доступным только для чтения.
В предпросмотре JSON проверяйте не только полное новое значение, но и changed_paths — пути изменённых данных.
Особенности Slate
Встроенная инструкция «Тема Slate» рекомендует сначала использовать настройки и только затем менять файлы. Настройки и каталог custom/ находятся в теме «Сайта»; дочерние темы используют её данные.
Перед специальными действиями агент читает agent/mcp-contract.txt: инструкция рассчитана на contract=1. Если файл отсутствует, применяется общий порядок работы; если номер другой, нужно сверить совместимость. Документация agent/*.md из установленной темы имеет приоритет перед встроенной инструкцией плагина.
Не переносите ключи и варианты настроек из другой версии Slate без чтения текущей темы.