Из чего состоит тема

Тема — это папка с четырьмя частями: манифест, шаблоны, файлы оформления и тексты.

themes/ваша-тема/
    theme.json          манифест: имя, версия и настройки темы
    templates/          шаблоны страниц
    assets/             css, js, картинки, шрифты
    locale/             надписи темы: ru.json, uk.json, en.json

Магазин считает папку темой, только если в ней лежит theme.json. Всё остальное необязательно — тема без единой картинки и без единого перевода работает.

Шаблоны#

Имя файла страницы — это ещё и название раздела витрины: оно приходит в шаблон переменной $action (у главной — default). По ней удобно подсвечивать активный пункт меню.

Если файла страницы нет, магазин возьмёт его из стандартной темы. Так работает тема, написанная раньше, чем в магазине появилась новая страница: подборка товаров, блог. Недостающий шаблон берётся из themes/default/templates, а каркас layout.html, шапка, подвал и всё из partials/ — по-прежнему из вашей темы, потому что она проверяется первой. Страница открывается и выглядит частью сайта, но внутри у неё разметка стандартной темы, а её стили (например, css/blog.css) ищутся в вашей теме и могут не найтись.

Чтобы такая страница была оформлена как остальной сайт, скопируйте шаблон из стандартной темы к себе и доработайте его:

themes/default/templates/product-list.html        → themes/ваша-тема/templates/product-list.html
themes/default/templates/blog.html                → themes/ваша-тема/templates/blog.html
themes/default/templates/blog-category.html       → themes/ваша-тема/templates/blog-category.html
themes/default/templates/blog-post.html           → themes/ваша-тема/templates/blog-post.html
themes/default/templates/blog-tag.html            → themes/ваша-тема/templates/blog-tag.html
themes/default/templates/partials/blog-card.html  → themes/ваша-тема/templates/partials/blog-card.html

Подставляется только отсутствующий файл. Свой шаблон всегда главнее, и правки стандартной темы его не трогают.

Каркас и страницы#

Блог#

У витрины может быть несколько блогов, у каждого свой адрес: /news/, /articles/. Все они рисуются одними и теми же шаблонами.

Счётчик прочтений записи ведёт сам магазин: на странице записи он подключает свой скрипт, а от темы нужен только атрибут data-blog-post="{$post.id}" на элементе статьи.

Корзина и оформление заказа#

Оформление заказа — одна страница. Контакты, доставка, оплата и подтверждение стоят на ней друг под другом, всё это рисует checkout/layout.html. Отдельных страниц-шагов у оформления нет.

Владелец магазина может включить настройку «оформление в один шаг» — тогда корзина и оформление показываются вместе, и значок корзины ведёт сразу на оформление. Отдельная страница корзины при этом никуда не девается, просто покупатель на неё не попадает. Куда вести значок, спрашивают у магазина: {$shop->cartPath()}.

В базовой теме рядом лежат файлы checkout/delivery.html, checkout/payment.html и checkout/confirm.html — заготовки, оставшиеся от ранней разработки. Их никто не подключает, менять их бессмысленно, а в своей теме их можно удалить.

Личный кабинет покупателя#

Куски, которые включаются в страницы#

Лежат в partials/ и подключаются тегом {include}.

Блоки главной#

Лежат в blocks/ и собираются на главной в нужном вам порядке.

Шаблоны дополнений#

Папка templates/plugins/ принадлежит не теме, а дополнениям. Когда владелец магазина ставит дополнение, оно кладёт туда свои шаблоны:

templates/plugins/
    promotions/     Акции
    web-chat/       Чат на сайте
    buy-one-click/  Купить в один клик
    …

Эти файлы правятся как любые другие — вид блока дополнения меняете вы. Но в пакет темы они не попадают: у клиента там будут его дополнения, а не ваши.

Файлы оформления#

assets/
    css/            стили темы
    js/             скрипты темы
    img/            картинки: логотип, заглушки, значки
    vendor/         сторонние библиотеки, если они нужны
    plugins/        стили дополнений — как и templates/plugins, не ваши

Всё, что лежит в assets/, магазин отдаёт браузеру по адресу /theme-assets/имя-темы/…. Внутри шаблона этот адрес всегда есть готовым:

<img src="{$theme.assets}/img/logo.svg" alt="">

Файлы за пределами assets/ браузеру не отдаются. Шаблоны, манифест и переводы прочитать снаружи нельзя — это защита, а не недоработка.

Тексты темы#

locale/
    ru.json
    uk.json
    en.json

Обычные файлы вида «ключ — надпись», по одному на язык. Подробности — на странице Тексты темы и языки.

Чего в теме нет#

Наследования между темами. Тема самостоятельна: копия базовой темы — это полная копия, а не ссылка на неё. Обновление базовой темы вашу тему не тронет. Единственное исключение — шаблон страницы, которого в вашей теме нет вовсе: его магазин берёт из стандартной темы, чтобы страница не падала (см. выше).

Своих таблиц в базе. Тема ничего не хранит, кроме собственных настроек, и те лежат у витрины, а не у темы. Поэтому смена темы ничего не ломает: вернули прежнюю — вернулись и её настройки.

Своего кода на сервере. Если нужно новое поведение — считать что-то по-своему, сходить во внешний сервис, добавить раздел витрины, — это делает дополнение, а не тема. Дополнение при этом кладёт свою разметку в вашу тему, и вы её оформляете.