# Темы публичного сайта Раздел **Темы** управляет файлами публичного оформления без загрузки через FTP: CSS, JavaScript, изображениями, SVG, шрифтами и Twig-представлениями. Во вкладке **Настройки** также выбирается, кто собирает общую страницу: нативные шаблоны AVE.cms или файловая Twig-оболочка темы. ## Где находятся темы Каждая тема имеет отдельный каталог: ```text templates/<код-темы>/ ├── theme.json ├── css/ ├── js/ ├── images/ └── fonts/ ``` Активная тема выбирается в разделе **Темы**. Код каталога состоит из строчных латинских букв, цифр, `_` и `-` и начинается с буквы. Служебные каталоги `include`, `templates`, `lang`, каталоги превью и скрытые файлы не показываются в файловом менеджере. Это отделяет статические ассеты от скомпилированных шаблонов и других внутренних файлов темы. ## Подключение CSS и JavaScript Вкладка **Подключения** редактирует `theme.json`. В ней можно: - выбрать CSS-файлы и задать `media`; - выбрать JS-файлы и включить `defer`, `async` или `type="module"`; - изменить порядок файлов перетаскиванием; - указать название и версию темы. В основном шаблоне сайта используются теги: ```html [tag:theme-styles] [tag:maincontent] [tag:theme-scripts] ``` Один отдельный файл можно получить независимо от реестра: ```text [tag:asset:images/logo.svg] ``` Движок проверяет существование файла и добавляет к URL короткую SHA-1-версию. После сохранения файла браузер получает новый адрес вида `?v=...`, поэтому старый CSS или JavaScript не остаётся в кеше. Новые теги являются явными. Создание или активация темы не добавляет их в существующий шаблон и не меняет текущий публичный вид сайта. ## Настройки витрины Тема может объявить в `theme.json` собственные редактируемые настройки. Для каждой темы они автоматически появляются во вкладке **Темы -> Настройки**. Так редактируются контакты, подписи и лимиты подборок без изменения файлов. Состав полей принадлежит теме: после переключения темы панель управления покажет настройки нового оформления, а значения прежней темы сохранит под её собственными ключами. Скалярное значение можно вывести и в нативном шаблоне, запросе или блоке: ```html [tag:theme-setting:retail_phone] ``` Тег читает только параметр, объявленный активной темой, и безопасно экранирует его. Для стандартных полей `retail_phone` и `wholesale_phone` дополнительно доступны ключи с суффиксом `_href`. Поле типа `section_order` управляет секциями только файловой Twig-оболочки. Порядок нативной страницы меняют в шаблоне её рубрики: там явно видны блоки, запросы и модульные теги, из которых собрана страница. Переключатель секции не удаляет её документы или товары. ## Нативный режим и оболочка темы Во вкладке **Настройки** доступны два способа сборки публичной страницы: - **Нативные шаблоны AVE** — общий шаблон сайта, рубрики, запросы, блоки и навигация собирают страницу штатным способом. Это основной и рекомендуемый режим; - **Twig-оболочка темы** — файл из `page_shell` управляет общей структурой страницы. Режим доступен только если такой файл объявлен в `theme.json`. Переключатель не отключает оформление. Подключённые CSS/JS, изображения и переопределения представлений модулей работают в обоих режимах. Он меняет только способ сборки общей страницы. ```json { "presentation_mode": "native", "page_shell": "views/storefront/page.twig", "page_shell_mode": "replace" } ``` После сохранения публичный кеш очищается автоматически. Благодаря этому можно подготовить Twig-оболочку заранее, проверить её, а затем вернуться к нативным шаблонам одним переключателем. ## Редактирование и ревизии CSS, JavaScript, JSON, XML, SVG и текстовые файлы открываются в редакторе кода. Перед перезаписью сохраняется предыдущая версия. Вкладка **Ревизии** позволяет: - просмотреть содержимое и автора изменения; - восстановить выбранную версию; - удалить одну ревизию или всю историю темы. Бинарные изображения и шрифты не копируются в таблицу ревизий. Для их резервного копирования используйте экспорт темы. ## Создание и ZIP Кнопка **Создать** формирует каркас темы с `css/app.css`, `js/app.js` и `theme.json`. **Экспорт** собирает только разрешённые публичные файлы темы. Импортируемый ZIP должен содержать `theme.json`: ```json { "format": "ave-theme-v1", "name": "Название темы", "version": "1.0.0", "styles": [ {"file": "css/app.css", "media": ""} ], "scripts": [ {"file": "js/app.js", "defer": true, "async": false, "module": false} ] } ``` Архив может содержать один общий корневой каталог или файлы непосредственно в корне. Символические ссылки, абсолютные пути, `..`, исполняемые PHP-файлы, скрытые файлы и неизвестные расширения отклоняются до записи. SVG очищается от скриптов и обработчиков событий. ## Разделение ответственности | Задача | Где настраивать | | --- | --- | | Контакты и параметры оформления | **Темы -> Настройки** | | Порядок секций нативной страницы | **Рубрики и поля -> шаблон рубрики** | | Ссылки в меню и подвале | **Навигация** | | HTML оболочки, `head`, шапки и подвала | **Шаблоны** | | Товарная карточка и фильтр каталога | **Каталог -> Карточки / Шаблоны фильтров** | | Корзина, оформление и кабинет покупателя | **Заказы -> Шаблоны** | | CSS, JS, изображения, шрифты | **Темы** | | HTML одного типа документа | **Рубрики и поля** | | Переиспользуемый фрагмент | **Блоки** | | Собственные CSS/JS устанавливаемого расширения | Внутри пакета **Модуля** | Модульные ассеты остаются у владельца-модуля. Не переносите их в тему, если они обязательны для работы модуля. Тема может лишь переопределять их внешний вид собственным CSS, подключённым позже. Файловая Twig-оболочка `page_shell` полезна для пакетных демо, готовых файловых тем и специальных интеграций. Для обычного контентного сайта предпочтительна нативная композиция из шаблона сайта, рубрик, запросов, блоков и навигации. Точечное Twig-представление сложного модуля подключается только через его зарегистрированный тег. Подробнее: [Точечные Twig-компоненты](twig-components.md).