Власна тема: тека, theme.json, шаблони й пакування

Тема — це тека в themes/: опис, стилі та, якщо потрібно, власні шаблони сторінок. Писати PHP для теми не потрібно: шаблони пишуться на готових тегах рушія, а все інше береться зі спільної розмітки. Тема, в якій немає жодного шаблона, теж повноцінна: вона лише перефарбовує та перебудовує стилі.

Що лежить у теці

themes/my-theme/
├── theme.json
├── assets/
│   ├── css/theme.css
│   └── screenshot.png
├── views/
│   ├── layouts/main.tpl.html
│   ├── errors/404.tpl.html
│   └── news/index.tpl.html
└── locales/

• theme.json — опис і налаштовувані значення (обов'язково).
• assets/css/theme.css — стилі теми, підключаються на кожній сторінці.
• assets/screenshot.png — зображення для картки теми (за бажанням).
• views/ — власні шаблони сторінок (за бажанням): рамка сайту layouts/main.tpl.html, сторінка «не знайдено» errors/404.tpl.html, список новин news/index.tpl.html та інші.
• locales/ — слова самої теми (за бажанням): en.json, ru.json і так далі.

Назва теки — малі латинські літери, цифри, дефіс і підкреслення, починається з літери.

Мінімальний приклад

Тема з трьох файлів: опис, стилі та власна сторінка «не знайдено». Решту сайт малює спільною розміткою рушія.

{
    "name": "my-theme",
    "version": "1.0.0",
    "title": {"en": "My theme", "ru": "Моя тема", "uk": "Моя тема", "no": "Mitt tema", "pl": "Mój motyw", "sv": "Mitt tema", "lt": "Mano tema"},
    "description": {
        "en": "A light theme with one green accent.",
        "ru": "Светлая тема с одним зелёным акцентом.",
        "uk": "Світла тема з одним зеленим акцентом.",
        "no": "Et lyst tema med én grønn aksent.",
        "pl": "Jasny motyw z jednym zielonym akcentem.",
        "sv": "Ett ljust tema med en grön accent.",
        "lt": "Šviesi tema su vienu žaliu akcentu."
    },
    "author": "Ваше ім’я",
    "engine": ">=0.9.9",
    "variables": {
        "color_accent": {
            "type": "color",
            "default": "#1a7f5a",
            "label": {"en": "Accent colour", "ru": "Основной цвет", "uk": "Основний колір", "no": "Hovedfarge", "pl": "Kolor główny", "sv": "Huvudfärg", "lt": "Pagrindinė spalva"}
        }
    }
}

:root {
    --color-accent: #1a7f5a;
}

body {
    border-top: 4px solid var(--color-accent);
}

h1,
h2 {
    color: var(--color-accent);
}

<section class="error error--404">
  <p class="error__code">{status}</p>
  <h1>{message}</h1>
  <div class="error__find">{search}</div>
  <p><a href="{home}">← {site_name}</a></p>
</section>

Третій файл не треба писати з нуля. Створіть тему й попросіть у рушія заготовку шаблона:

php nex1on theme:files my-theme
php nex1on theme:file my-theme errors/404

Перша команда друкує список усіх сторінок, які тема може замінити, і показує, які з них уже ваші. Друга створює файл views/errors/404.tpl.html із заготовки: правте його, сторінка підхопить файл одразу.

Далі тему можна ввімкнути: «Оформлення → Теми», у картки «Моя тема» кнопка «Зробити активною» (або php nex1on theme:use my-theme). Відкрийте будь-яку неіснуючу адресу: зверху зелена смуга, а заголовок зелений.

theme.json: поля

Кожна змінна — це type (color, size, text, choice), значення default, назва label мовами й за бажанням підказка hint. Для choice додається options. Ім’я color_accent у CSS стає змінною --color-accent (підкреслення — дефіс).

Важливо. Значення, яке власник не змінював, рушій на сторінку не виводить: вважається, що тема сказала його сама. Тому в кожної своєї змінної значення за замовчуванням треба записати в theme.css у блоці :root, як у прикладі. Інакше, поки нічого не змінювали, var(--color-accent) буде порожнім, і браузер відкине правило цілком.

Шаблони сторінок

Кожен шаблон — файл views/<папка>/<ім'я>.tpl.html: звичайний HTML з тегами у фігурних дужках ({site_name}, {menu}, {content}) і блоками ([each:menu]…[/each], [if:user.logged]…[/if]). Який шаблон за яку сторінку відповідає, показує theme:files:

Немає файла у вашій темі — рушій використовує свою готову сторінку, тому замінювати можна по одному шаблону. Немає файла тегів або він зламаний (не закрито блок) — працює звичайний вигляд, і сайт лишається робочим. Теги й приклади сторінок — у статтях Тема на тегах і Головний шаблон на тегах; для сторінок модулів — «Вигляди на тегах».

Правка в панелі

Шаблони можна правити і без файлів: «Оформлення → Код теми» (редактор тем). За замовчуванням він вимкнений: вмикає його лише власник сайту, з повторним паролем. Поки він вимкнений, жоден файл теми з панелі не змінюється. У редакторі власна тема — це готова тема плюс лише ті файли, які ви змінили: оновлення готової теми продовжують до вас доходити. Редактор перевіряє шаблон до збереження, показує попередній перегляд, а попередню версію файла можна повернути. Файли, створені в панелі, лежать у теці теми, тому таку тему потім можна запакувати.

Слова теми

Якщо в шаблонах потрібні підписи, не пишіть їх прямо в HTML: покладіть у locales/<код>.json теми й беріть ключем. Файли за мовами, як у модуля; немає потрібної мови — береться англійська. Підписи всередині готових тегів рушія (меню учасника, вхід, пошук, вибір мови) уже перекладені всіма сімома мовами, тому тема, яка користується лише ними, працює будь-якою мовою без власних перекладів.

Чого в темі не можна

• PHP-файли: у темі без підпису Nex1on встановлювач їх відхиляє, а шаблони на тегах PHP не потребують.
• Теги form, script і style та обробники подій у розмітці: форми, скрипти й захисні ключі малює лише рушій.
• Файли типів, крім php, json, md, txt, html, xml, csv, css, js, png, jpg, gif, webp, ico, woff, woff2. Картинки svg приймаються лише в архіві з підписом Nex1on; у власній темі беріть png або webp.

Пакування

php nex1on theme:pack my-theme

Команда збирає архів my-theme-1.0.0.zip (назва — версія з theme.json) і друкує шлях до нього: за замовчуванням тека nex1on-moduli/zip на два рівні вище за теку сайту, змінити можна ключем app.release_directory у config/local.php. Архів без підпису: так ставлять власні теми. Як поставити його на сайт — у статті «Як встановити власне доповнення». Перед пакуванням підніміть version, якщо ви оновлюєте вже встановлену тему.