З чого складається тема

Тема — це тека з чотирма частинами: маніфест, шаблони, файли оформлення і тексти.

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

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

Чого в темі немає#

Успадкування між темами. Тема самостійна: копія базової теми — це повна копія, а не посилання на неї. Оновлення базової теми вашу тему не зачепить. Єдиний виняток — шаблон сторінки, якого у вашій темі немає зовсім: його магазин бере зі стандартної теми, щоб сторінка не падала (див. вище).

Своїх таблиць у базі. Тема нічого не зберігає, крім власних налаштувань, і ті лежать у вітрини, а не в теми. Тому зміна теми нічого не ламає: повернули попередню — повернулися і її налаштування.

Свого коду на сервері. Якщо потрібна нова поведінка — порахувати щось по-своєму, сходити у зовнішній сервіс, додати розділ вітрини, — це робить доповнення, а не тема. Доповнення при цьому кладе свою розмітку у вашу тему, і ви її оформлюєте.