Файл theme.json і налаштування теми

theme.json — єдиний обов'язковий файл теми. Він каже магазину, як тема називається, якої версії магазину потребує і які налаштування власник побачить у панелі.

Мінімальний файл#

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

Поля author, preview і locales записати можна, але магазин їх зараз ніде не показує — на роботу теми вони не впливають.

Якщо theme.json зіпсований і не читається як JSON, магазин усе одно вважає теку темою, але без імені та версії: у списку вона називається за іменем теки. Вітрина при цьому працює. А от без самого файлу тека темою не вважається, і вітрина, призначена на неї, падає.

Сумісність із версією магазину#

"requires": { "core": "2.0.0" }                            ця версія і новіші
"requires": { "core": ">=2.0.0" }                          те саме, зі знаком
"requires": { "core": { "min": "2.0.0", "max": "3.0" } }   з верхньою межею

Звичайний випадок — тільки нижня межа. Верхня потрібна, коли ви точно знаєте, що наступна велика версія магазину ламає вашу тему.

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

Перевірка йде до підміни теки, тому відмова безпечна: попередня тема залишається на місці, магазин продовжує працювати. Власник побачить зрозуміле повідомлення: «Це доповнення розраховане на CartiX 3.1.0 і новіші, а у вас встановлена версія 2.5.0. Спочатку оновіть магазин».

Що тема веде сама#

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

"runtime": {
    "sku": "theme",
    "catalog": "theme",
    "accessories_popup": "theme"
}

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

Налаштування теми#

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

"settings": {
    "groups": [
        {
            "id": "colors",
            "name": "Кольори",
            "fields": [
                { "key": "primary", "type": "color", "label": "Основний", "default": "#4f46e5" },
                { "key": "accent", "type": "color", "label": "Акцент",
                  "hint": "Колір зірок рейтингу і кнопки передзамовлення.", "default": "#f59e0b" }
            ]
        },
        {
            "id": "catalog",
            "name": "Каталог",
            "fields": [
                { "key": "per_page", "type": "number", "label": "Товарів на сторінці", "default": 24 },
                { "key": "products_per_row", "type": "select", "label": "Товарів у ряд",
                  "options": [2, 3, 4, 5], "default": 4 },
                { "key": "show_sku_on_card", "type": "boolean",
                  "label": "Показувати артикул на картці", "default": true }
            ]
        }
    ]
}

Поля групи#

Поля налаштування#

Види полів#

image поки малюється звичайним текстовим полем: власник вставляє туди адресу файлу, вибору картинки з галереї немає.

Як прочитати налаштування в шаблоні#

Два способи, обидва працюють завжди:

{$theme.primary}          плоско, за іменем налаштування
{$theme.colors.primary}   через групу

Плюс два набори є в темі завжди, навіть якщо ви їх не оголошували:

{$theme.assets}           /theme-assets/ім'я-теми — адреса теки статики
{$theme.colors.primary}   {$theme.colors.accent} {$theme.colors.bg} {$theme.colors.text}

Усі поля схеми присутні в $theme, навіть незаповнені — вони приходять порожніми. Шаблон на них не падає, перевірка виду {if $theme.logo} безпечна.

⚠️ Налаштування, не оголошеного в theme.json, для магазину не існує. Написати {$theme.my_setting} і чекати значення безглуздо: поки поля немає в схемі, значення в нього немає і бути не може. Схема — джерело правди.

Той самий підступ з іншого боку: налаштування card_variants, яке вмикає показ варіантів купівлі просто на картках товарів у списку, читає сам магазин. У базової теми його в схемі немає — тому базова тема варіанти на картках не показує, хоч скільки правте шаблон. Потрібні варіанти — оголосіть поле:

{ "key": "card_variants", "type": "boolean", "label": "Варіанти купівлі на картці", "default": true }

⚠️ Ім'я налаштування не повинно збігатися з іменем групи. Налаштування лежать у $theme і плоско, і за групами, в одному наборі: поле colors усередині групи catalog затре всю групу colors.

Де зберігаються значення#

Значення налаштувань лежать у вітрини, а не в теми. Звідси три наслідки, про які потрібно знати.

Налаштування переживають оновлення теми. Файли замінюються повністю, значення залишаються в базі — за збіжними ключами нова версія побачить усе, що власник налаштував.

Звідси правило автора теми: не перейменовуйте ключі між версіями. Перейменували primary_color на primary — власник отримає колір за замовчуванням замість свого і вирішить, що оновлення зламало магазин. Потрібна нова поведінка — заводьте новий ключ, а старий залишайте працювати.

Набір значень один на вітрину, а не окремий на кожну тему. Збіжні ключі (primary, per_page, container_width) переїжджають з теми в тему, а ключі, яких у нової теми немає, просто лежать далі. Але збереження налаштувань нової теми перезаписує весь набір своїми полями — тобто перемкнулися на іншу тему, натиснули «Зберегти» — значення попередньої теми втрачені. Власнику, який збирається повернутися, варто спочатку виписати їх або завантажити архів теми.

Коли вітрин кілька, кожна налаштовується окремо: одна й та сама тема може бути синьою на одній вітрині і зеленою на іншій.

Налаштування зобов'язане щось робити#

Поле, яке зберігається і ні на що не впливає, — обман власника магазину. Оголосили в схемі container_width — читайте його в розмітці:

<style>:root { --container: {$theme.container_width}px; }</style>

Хороша звичка: писати hint там, де назва поля не пояснює наслідок, і placeholder у кожному полі введення.