Документация
RU UK
Личный кабинет

Своя тема с нуля

Порядок работы от копии базовой темы до готового оформления: с чего начать, что делать в каком порядке.

На этой странице

Свою тему почти никогда не пишут с пустого места. Здесь — два пути и порядок работы для каждого.

Какой путь выбрать

Копия готовой темы. «Дизайн» → тема → «Сделать копию». Копия полностью независима: правки в ней не трогают исходную, но и обновления исходной в копию не приходят.

Берите этот путь, если делаете магазин под клиента и результат нужен сегодня: все страницы, корзина, оформление и кабинет уже собраны, вам остаётся оформление.

С нуля. Папка, theme.json, templates/home.html, дальше по списку страниц.

Берите, если тема пойдёт в маркетплейс или разметка задумана совсем иначе: копия базовой темы тянет за собой её структуру классов, и переделывать её дороже, чем написать своё.

Завести новую тему из панели нельзя — только копией существующей или папкой на диске.

Минимум, при котором магазин видит тему

themes/my-theme/
    theme.json
    templates/
        home.html

{
    "id": "my-theme",
    "name": "Моя тема",
    "version": "1.0.0",
    "requires": { "core": "2.0.0" }
}

<!doctype html>
<html lang="{$storefront.locale}">
<head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>{$storefront.name}</title>
    {assets_head}
</head>
<body>
    <h1>{$storefront.name}</h1>
    {assets_footer}
</body>
</html>

Отдельного списка тем нет — папка на диске и есть список. Скопировали папку — тема сразу появилась в выборе оформления.

Заведите заодно три файла, которые магазин просит на каждой странице, хотя бы пустыми: assets/css/theme.css, assets/js/theme.js, assets/vendor/fontawesome/all.min.css. Иначе в консоли будут три ошибки 404.

Как переключить витрину на свою тему

«Витрины и контент» → «Витрины», поле «Оформление», затем «Сохранить».

Раздел «Дизайн» тему витрины не меняет — там выбирают, какую тему вы правите. Это путает при первом знакомстве.

Тема принадлежит витрине: при нескольких витринах у каждой может быть своя.

Порядок работы

1. Каркас

templates/layout.html. Готовый образец со всем обязательным — на странице Каркас страницы. Обязательное там: мета-тег с ключом защиты, {assets_head} и {assets_footer}, блок page_assets до {assets_head}.

Тут же удобно вывести цвета из настроек темы переменными CSS — дальше всё оформление опирается на них.

2. Шапка

partials/header.html. Что в неё положить, чтобы работали возможности магазина:

  • счётчик корзины — [data-badge="cart"], сумма — [data-cart-total-header];
  • живой поиск — форма [data-live-search] с [data-search-input] и пустым местом [data-search-results];
  • меню категорий — {$shop->categories(null, 2)};
  • переключатель языка — {$shop->locales()};
  • вход и кабинет — по {if $customer};
  • контакты — $contacts с готовым phone_link.

3. Подвал

partials/footer.html. Меню информационных страниц — {$shop->pages()}. Обязательно точки {hook name="footer.start"} и {hook name="footer.end"}. Копирайт удобно вынести настройкой темы.

4. Главная

home.html. Данных ей не передают вовсе — всё берётся через $shop:

{extends file="layout.html"}
{block name="content"}
    {include file="blocks/product-list.html" products=$shop->products('new-arrivals', null, 12)}
    {include file="blocks/product-list.html" products=$shop->products(null, 'discount', 8)}
{/block}

5. Листинг — один раз на четыре страницы

Категория, поиск, бренд и метка получают одинаковый набор данных. Соберите список товаров, фильтры и постраничную навигацию отдельными кусками и включите во все четыре — иначе будете править одно и то же четырежды.

Фильтры рисуйте списком по данным: набор характеристик у каждого магазина свой, и хардкод «цвет, размер, бренд» на чужом магазине покажет пустоту.

6. Карточка товара

product.html — самая большая страница. Три блока обслуживает магазин, тема даёт только место: комплекты ([data-accessories]), упаковки ([data-pack]), пометка «уже в корзине» ([data-in-cart]).

Свой счётчик количества над блоком упаковок не заводите — он будет драться с магазинным.

Ветку «товар без фото» пишите сразу: магазин без фотографий — обычное дело.

7. Корзина

checkout/cart.html. Количества дробные — выводите через {qty}. Позиции с признаком locked (подарки, призы) показывайте без счётчика и без кнопки удаления. Пустая корзина — отдельный блок, а не пустая таблица.

Итоги оборачивайте в {if $items}: у пустой корзины часть ключей не приходит.

8. Оформление

checkout/layout.html. Своего скрипта тут писать не надо. Пересчёт, способы доставки и оплаты, карта отделений, промокод, баллы — всё это магазин подключает сам на любую тему.

Ваша часть — разметка с оговорёнными атрибутами и свой checkout.css. Полный список атрибутов — на странице Атрибуты data-*.

Не забудьте checkout/success.html, checkout/error.html, checkout/pay.html, checkout/pay-error.html — на две последние покупатель попадает по ссылке из письма.

9. Кабинет

Десять шаблонов в account/. Свой account/layout.html с боковым меню экономит время. Капчу вставляйте тегом {captcha form="…"} — он сам разберётся, нужна ли она. Формы обычного POST обязаны нести {csrf_field}.

10. Мелкие, но обязательные

404.html — иначе покупатель увидит стандартную страницу без вашей шапки. maintenance.html — заглушка закрытого магазина.

Правлю — вижу: как работать без сюрпризов

Шаблоны обновляются сразу

Правку .html видно немедленно — магазин сам замечает, что файл изменился.

Страницы витрины кэшируются на сутки

Это главная причина «я поправил, а ничего не изменилось».

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

Не кэшируются никогда: корзина, оформление, заказ, кабинет, избранное, сравнение, подсказки поиска, а также любая страница для вошедшего покупателя.

⚠️ Сохранение файла темы в редакторе кэш не сбрасывает — файл пишется мимо базы. Сохранение настроек темы сбрасывает.

Кнопки сброса

«Система» → «Обслуживание», группа «Кеш и страницы»:

Кнопка Когда жать
Сбросить страницы витрины «показывает старую вёрстку или старые цены»
Пересобрать шаблоны темы «правка темы не видна»
Сбросить весь кеш когда не помогло ни то, ни другое

Шаблоны пересобираются сами при включении и выключении дополнения, при установке или обновлении темы, при восстановлении из копии и при обновлении магазина.

Файлы стилей и скриптов

Подключённые через {asset_css} и {asset_js} получают метку версии — браузер берёт свежий файл. Написанные вручную через {$theme.assets} метки не получают и залипают у покупателя на месяц. Стили и скрипты подключайте только тегами.

Посмотреть, что пришло

{dump}                 что вообще доступно этому шаблону
{dump var=$product}    одно значение
{dumpc var=$product}   то же в консоль браузера

Видит только сотрудник магазина. Это самый быстрый способ понять, что приходит на страницу, — и он всегда актуальнее любой таблицы в справочнике.

Правила, которые нельзя нарушать

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

Своим скриптом тема делает то, что относится к её разметке: выезжающее меню, галерею, вкладки, добавление в корзину и в избранное.

Тема не ходит в базу данных. Всё спрашивается у $shop. Обращение к классам магазина из шаблона запрещено и даёт ошибку, а не данные.

Тема ничего не считает в деньгах. Числа приходят готовыми, {money} только форматирует.

Библиотеки кладутся файлами, а не подключаются с чужого сайта.

Настройка обязана что-то делать. Поле, которое сохраняется и ни на что не влияет, — обман владельца магазина.

Обновлено 25 августа 2026