Собственный CSS, JavaScript и HTML

Для своего CSS, JavaScript и HTML в Slate предусмотрены отдельные файлы. Используйте их в рабочей копии темы: так оформление сайта можно менять без правок поставляемых стилей и шаблонов.

Где хранить изменения

Общий каталог custom/ находится в рабочей копии темы приложения «Сайт». При стандартном идентификаторе темы это wa-data/public/site/themes/slate/custom/. У копии с другим идентификатором последняя часть пути будет другой.

Это правило действует и для изменений страниц магазина, блога, фотогалереи, сообщества, поддержки и рассылок: их пользовательские подмены тема ищет в общей site-теме. Каталог custom/ в копии темы магазина для таких подмен не используется.

Создайте рабочую копию через редактор дизайна и проверьте, что она используется нужной витриной. Новые файлы можно добавить в редакторе либо загрузить средствами доступа к серверу. Если добавленный на сервере файл должен появиться в редакторе дизайна, его также регистрируют в списке файлов theme.xml рабочей копии с признаком custom="1". Существующие настройки манифеста менять для этого не нужно.

Для вставки, которую нужно редактировать из бэкенда без доступа к файлам, предусмотрены также фиксированные блоки «Сайт → Блоки»: в <head>, конце страницы, возле цены, после галереи и в других местах. Их коды и ограничения перечислены в справочнике точек расширения. Данные этих блоков хранятся в приложении, отдельно от файлов темы.

Собственные стили

Создайте custom/css/site.css и подключите его в custom/head.html:

{call assets file="custom/css/site.css"}

Функция темы подключит существующий файл из общей темы и добавит версию по времени его изменения. Путь относится к локальному файлу темы; это не способ подключения внешнего CDN.

Для небольшого изменения используйте классы нужного блока. Например, отступ между карточками категорий или размер своего заголовка можно задать собственным правилом внутри .slate. Сначала проверьте класс в разметке и убедитесь, что изменение не затронуло другие варианты блока.

Для общей палитры и оформления предусмотрены также custom/ds/tokens.css и custom/ds/skin.css: эти файлы подключаются автоматически, когда существуют. Значения токенов и готовые классы описаны в документации для агента настройки.

Не редактируйте assets/css/theme.css, стили приложений (shop.css, blog.css, photos.css и другие) и их минифицированные версии: обновление заменяет поставляемые файлы. Стили приложений загружаются по составу страницы; при установленном магазине его полный набор может подключаться и на страницах других приложений, где товары выводят плагины. Пользовательские файлы из custom/ подключаются после базовых стилей темы. Используйте обычный CSS, совместимый с поддерживаемыми браузерами. Добавляя собственные блоки, сохраняйте область .slate и выбирайте отдельные имена классов. При конфликте с поздно подключёнными стилями приложения или плагина проверьте порядок и точность селекторов. Окна и выпадающие списки плагинов, которые вставляются прямо в body вне .slate, получают шрифт темы, но не её правила блоков: для них пишите отдельные селекторы.

Страница оформления заказа

Обёртки оформления заказа носят штатные идентификаторы Shop-Script: #js-order-page — вся страница, #js-order-cart — корзина, #js-order-form — форма. Прежние #slate-order-cart и #slate-order-form больше не печатаются: собственные стили и скрипты с ними перепишите на новые идентификаторы или на классы s-order-cart__body и s-order-form__body. Сами идентификаторы в своей версии шаблона не переименовывайте — по ним плагины находят оформление заказа.

JavaScript, счётчики и виджеты

custom/head.html подключается в конце <head>, а custom/scripts.html — в конце страницы после скриптов темы. Для своего локального JavaScript можно создать custom/js/site.js и добавить в custom/scripts.html:

{call assets file="custom/js/site.js"}

Счётчик аналитики, чат или другой внешний виджет подключайте по инструкции его поставщика. Если она требует размещение в <head>, используйте custom/head.html; в остальных случаях подойдёт custom/scripts.html. Внешний адрес подключается обычным тегом <script>, а не функцией assets.

Внутри Smarty-шаблона фрагмент JavaScript или CSS с фигурными скобками при необходимости заключают в {literal}…{/literal}. В отдельном .js или .css это не требуется.

Для собственного поведения Slate использует обычный JavaScript. Не копируйте вызовы компонентов Preline или внутренние функции другой темы. Сторонние виджеты работают по API своих поставщиков. Проверяйте их на телефоне: кнопка чата может перекрывать нижнюю навигацию, кнопку заявки или действия товара.

Своя разметка блоков и страниц

Для замены одного блока создайте custom/<путь блока>.html. Например, custom/blocks/about.html заменяет вывод блока «О компании», а custom/product/buttons.html — блок кнопок товара. Такая подмена имеет приоритет перед выбором варианта в панели.

При более сложной настройке можно добавить собственные варианты и части блока в custom/<путь блока>/. Точные имена, доступные данные и обязательные элементы сверяйте с документацией конкретного блока в поставляемом каталоге agent/.

Для подмены страницы целиком предусмотрены пути вида custom/<приложение>/<страница>.html, например custom/shop/home.html или custom/hub/topic.html. Это работа для разработчика: нужно сохранить обязательные элементы страницы и вывод расширений Webasyst. Для обычного наполнения сначала используйте состав блоков и настройки темы.

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

Картинки в своём блоке

Для картинки, которую владелец задаёт в настройке или в данных своего блока, используйте макрос темы responsive_img. Он доступен в шаблонах блоков и вариантов без отдельного подключения:

{call responsive_img src=$data.image widths="card"
    desk=0.33 tab=0.5 mob=1
    alt=$data.title class="s-my-block__image" width="960" height="720"}

src — один основной адрес, например /wa-data/public/site/img/hall-640.webp. Если рядом лежат копии того же кадра с шириной в имени (hall-480.webp, hall-960.webp), макрос добавит в srcset только существующие файлы; без копий выводится обычная картинка. widths — набор ширин: card (480, 640, 960), half (640, 960, 1400), hero (960, 1400, 1920), video (640) или свои числа через запятую.

desk, tab и mob — доля ширины контейнера, которую занимает картинка на компьютере (от 1024 px), планшете (768–1023 px) и телефоне; по умолчанию 1. desk="bleed" означает всю ширину окна. Из этих долей и настройки ширины контейнера макрос сам собирает sizes; готовая строка в параметре sizes их заменяет. width и height задают пропорцию кадра, чтобы страница не прыгала при загрузке. priority=1 — для картинки первого экрана: она загружается сразу и с высоким приоритетом, остальные — лениво.

Внешние адреса и файлы вне сайта выводятся как есть, без srcset. Как подготовить копии разных ширин — в статье об изображениях. Чтобы картинки своей галереи открывались в окне просмотра, добавьте ссылкам атрибут data-slate-lightbox — см. JavaScript API.

Шаблоны плагинов

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

В Slate уже есть поставляемые шаблоны ряда плагинов — плоскими файлами в корне темы (например, окно «Регионов без поддоменов» в теме магазина) и каталогами plugins/<плагин>/ (найденные категории «Умного поиска», баннер и окно «Согласия на cookie»). Изменения существующего файла поставки могут быть заменены при обновлении. Если достаточно изменить оформление, предпочтите собственный CSS. Список предусмотренных интеграций — в отдельной статье.

Служебные файлы готовой конфигурации

В корне темы «Сайта» предусмотрены пустые в базовой поставке файлы готовой конфигурации. u-head-layer.html подключается в конце <head> всех приложений — для скриптов и метатегов конфигурации. u-early-layer.html подключается раньше, до решений <head>: там конфигурация ставит флаги, которые нужны заранее, например slate.hd_forms для формы «Поддержки» в окне — см. «Глобальные и дополнительные параметры». Это файлы поставки, а не custom/: собственные правки сайта в них не делайте.

Ограничения шаблонов и обновления

HTML-шаблоны работают под политикой безопасности Smarty Webasyst. Они не выполняют произвольный PHP: чтение файлов через file_get_contents, запуск команд и ряд статических вызовов запрещены. Используйте доступные данные приложений и разрешённые функции темы; обработку новых данных размещают в приложении или плагине.

Текст и адреса из собственных данных экранируйте при выводе в HTML. HTML, который приложение специально возвращает как готовую разметку, требует отдельной оценки: не заменяйте им обычный текст из произвольного источника.

Каталог custom/ в поставку Slate не входит. Новые пользовательские файлы регистрируйте в theme.xml рабочей копии с custom="1". Если всё же изменили поставляемый файл вне редактора дизайна, обязательно пометьте его в том же манифесте как modified="1": без пометки автоматическое обновление может заменить его без предупреждения. Это разные признаки: custom — собственный файл, modified — изменённый файл поставки. Сохраняйте резервную копию и проверяйте пользовательские подмены после обновлений: сохранение файла не гарантирует совместимость со всеми изменениями темы. Подробнее — об обновлениях.