Своя тема: папка, 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, если вы обновляете уже поставленную тему.