Интеграции

Интеграция панели темы

Обновлено 25 октября 2026

Область работы

Эта статья для разработчика панели темы. Все изменяющие маршруты работают с темой приложения «Сайт», даже если панель открыта из другого приложения. Передать другое приложение параметром запроса нельзя. Идентификатор темы в панели должен соответствовать установленной теме «Сайта».

URL формируйте через маршрутизацию Webasyst, без жёстко заданного домена или каталога установки:

{$preview_url = $wa->getUrl('themesettings/frontend/default')}
{$save_url = $wa->getUrl('themesettings/frontend/save')}
{$reset_url = $wa->getUrl('themesettings/frontend/reset')}
{$token_url = $wa->getUrl('themesettings/frontend/token')}

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

Маршруты и права

Маршрут	Метод	Назначение	Доступ
`token/`	GET	Инициализировать сессию и CSRF-cookie, получить `data._csrf`	Администратор «Сайта» или посетитель при включённом демо
`default/`	POST	Заменить собственный черновик	Те же права
`reset/`	POST	Удалить собственный черновик и загрузки указанной темы	Те же права
`save/`	POST	Применить присланные изменения к рабочей теме «Сайта»	Только администратор «Сайта»

Запросы выполняются с cookies той же сессии. Для POST обязательна CSRF-cookie и совпадающий токен: поле _csrf либо заголовок X-CSRF-Token. Отсутствующие токены не принимаются. CORS приложением не включается.

Для анонимной панели сначала вызовите хелпер до {$wa->csrf()} либо выполните GET к token/. При выключенном демо посетителю этот маршрут вернёт отказ доступа. Ответ инициализации помечается Cache-Control: no-store.

Поля запроса

Поле	Где используется	Содержание
`theme_id`	Все POST-маршруты	Идентификатор темы «Сайта»: 1–128 латинских букв, цифр, `_` или `-`
`settings[ключ]`	`default/`, `save/`	Непустой набор значений по реальным ключам `theme.xml`
`image[ключ]`	`default/`, `save/`, при загрузке	Файл для настройки с типом `image`; соответствующий ключ должен присутствовать и в `settings`
`_csrf`	Все POST-маршруты	Токен, совпадающий с cookie; вместо поля можно передать заголовок

При загрузке файлов используйте multipart/form-data. Идентификатор сессии в полях не передаётся: приложение определяет её на сервере.

save/ применяет значения из запроса, а не автоматически берёт весь черновик из базы. Передавайте все изменения, которые требуется сохранить. Сессионный URL изображения передавайте в соответствующем поле image-настройки внутри settings: приложение проверяет принадлежность файла своей сессии и теме, копирует файл в тему и сохраняет относительное имя.

Валидация настроек

Панель может отправлять полную форму или отличия от сохранённой темы. Неизвестные, скрытые, наследуемые и неподдерживаемые поля отфильтровываются. Настройки непосредственного родителя доступны только для чтения; попытка загрузить изображение родителя отклоняется.

Тип	Проверка
`text`, `textarea`	Скалярное значение, UTF-8, ограничение размера
`checkbox`	`0` или `1`; пустое значение приводится к `0`
`select`, `radio`, `image_select`	Значение должно быть ключом допустимого варианта
`color`	`#RGB`, `#RRGGBB` или пустое значение
`number`	Число с учётом заданных `min`, `max`, `step`; пустое значение допускается
`image`	Отдельная проверка относительного пути или URL собственного изображения; загрузка JPEG/PNG/GIF

Зависимость show_if обрабатывается как ключ=значение с учётом текущих и присланных значений. Изменения зависимого обычного поля исключаются, если условие не выполнено. Неподдерживаемое выражение show_if скрывает поле для записи. Произвольные выражения не исполняются.

Для посетителя изменённые значения с HTML или исполняемыми протоколами запрещены. Неизменённые сохранённые значения не проходят эту проверку заново. Переводы строк CRLF/LF и регистр шестнадцатеричных цветов не считаются изменением, значимые пробелы сохраняются.

Ограничения изображений и черновиков перечислены в статье «Черновики».

Ответы и ошибки

При успешном запросе Webasyst возвращает status: "ok" и объект data.

Маршрут	Полезные поля `data`
`token/`	`_csrf` — токен
`default/`	`settings` — принятые изменения и URL загруженных изображений; `error` — пустая строка
`save/`	`settings` — применённые значения, для новых изображений относительные имена; `error` — пустой массив
`reset/`	`resetAction: true`

Ответ default/ содержит дельту, а не полный черновик. Полный черновик читает getSettings($theme_id).

Безопасные ошибки ввода в default/ и save/ дают HTTP 400 и status: "fail" с массивом errors. Неожиданные исключения дают HTTP 500 и общее сообщение; подробности пишутся в themesettings.log. Превышение некоторых квот также может попасть в общий обработчик ошибок, поэтому не полагайтесь на один HTTP-код для всех отказов.

Код	Типичная причина
403	Нет прав или отсутствует/не совпадает CSRF-токен
405	Неподходящий HTTP-метод
429	Превышен общий лимит запросов предпросмотра и сброса

Проверяйте HTTP-код, status, errors и ожидаемые поля data. Перезагружайте страницу только после подтверждённого успеха. При сетевой ошибке или неожиданном ответе покажите ошибку пользователю.

Большая форма и max_input_vars

Перед обработкой проверяется рекурсивное количество полей POST и метаданных файлов. При достижении порога max_input_vars - 10 запрос отклоняется без записи. Подсчёт консервативный: отказ возможен раньше фактического лимита PHP.

Сообщение: «Форма отправлена не полностью: превышен max_input_vars (N). Увеличьте max_input_vars или отправляйте только изменённые настройки.» Здесь N — текущее значение лимита PHP.

Увеличьте серверный лимит с запасом либо отправляйте только изменения относительно рабочей темы, включая все актуальные изменения предпросмотра. Повторный default/ заменяет прежний черновик.

Сохранение рабочей темы

Приложение объединяет разрешённые присланные изменения с текущими значениями темы; отсутствующие настройки сохраняются. Перед записью используются блокировка и внутренняя защищённая резервная копия. При ошибке приложение пытается восстановить файлы. Это механизм обработки неудачной записи, без пользовательского интерфейса истории и восстановления.

Изменения общей темы действуют на все витрины, использующие эту тему «Сайта». Учитывайте это при проверке результата.