# Створення теми

Тема відповідає за оформлення фронту. Це тека `templates/<slug>/` з маніфестом `theme.json` і набором `.tpl`-файлів. PHP у шаблонах заборонено — лише [теги шаблонізатора](/docs/code/templating).

## Швидкий старт: порожня тема

Не пишіть з нуля — завантажте готовий скелет:

**[Завантажити порожню тему (zip)](/public/assets/plugins/handbook/celena-starter-theme.zip)**

Усередині: `theme.json`, `_partials/head.tpl` і `foot.tpl`, базові `home.tpl`, `page.tpl`, `news_list.tpl`, `news_full.tpl`, `search.tpl`, `404.tpl` та `assets/theme.css`. Розпакуйте так, щоб тека `starter-theme/` опинилася в `templates/`, активуйте тему в **Налаштування → Шаблони** і перейменуйте під себе (теку і `slug` у `theme.json`).

## theme.json

```json
{
  "name": "My Theme",
  "slug": "mytheme",
  "version": "1.0.0",
  "author": "Імʼя автора",
  "description": "Короткий опис",
  "regions": ["header", "main", "footer"]
}
```

`slug` збігається з імʼям теки і використовується в опції `theme`.

## Мінімальний комплект шаблонів

| Файл | Коли викликається |
|------|-------------------|
| `home.tpl` | головна сторінка |
| `page.tpl` | статична сторінка `/p/{slug}` |
| `news_list.tpl` | список новин/категорії/пошуку |
| `news_full.tpl` | сторінка однієї новини |
| `search.tpl` | результати пошуку |
| `404.tpl` | сторінка «не знайдено» |

Плюс переглядні частини в `_partials/` (наприклад `head.tpl`, `header.tpl`, `footer.tpl`) і асети в `assets/`.

## Швидкий старт «своя тема за годину»

1. Скопіюйте `templates/default/` → `templates/mytheme/`.
2. Виправте `theme.json`.
3. Замініть стилі в `assets/theme.css`.
4. Перепишіть `_partials/head.tpl` і підвал під свою верстку.
5. За потреби перевизначте `home.tpl`, `news_list.tpl`, `news_full.tpl`, `page.tpl`.
6. Активуйте тему в **Налаштування → Шаблони**.
7. Перевірте адаптивність і темну тему.

## Підключення асетів і версіонування

Усі css/js кладіть у `templates/<slug>/assets/` (зовнішні CDN заборонені політикою CSP). Підключення — у `_partials/head.tpl`:

```html
<link rel="stylesheet" href="/templates/mytheme/assets/theme.css?v=1">
<script src="/templates/mytheme/assets/theme.js?v=1" defer></script>
```

> На проді `nginx` кешує статику надовго. Після правки `.css`/`.js` **збільшуйте версію** (`?v=1` → `?v=2`), інакше відвідувачі, що повернулися, отримають старий файл із кешу.

## Темна тема

Теми успадковують CSS-змінні ядра (`--bg`, `--surface`, `--text`, `--accent` тощо). Темний режим вмикається атрибутом `data-theme="dark"` на `<html>`. Кнопки перемикання:

```html
<button data-celena-theme="light">☀</button>
<button data-celena-theme="dark">☾</button>
<button data-celena-theme="auto">A</button>
```

## Перевизначення шаблонів плагіна

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

```
templates/<mytheme>/plugins/<slug>/<шлях>.tpl
```

Рушій шукає шаблон плагіна в порядку: оверайд активної теми → оверайд default-теми → оригінал плагіна. Видаліть файл теми — повернеться оригінал. Докладніше — [Створення плагіна](/docs/code/plugin-create).

## Кеш шаблонів

Після правки `.tpl` на проді очистіть кеш скомпільованих шаблонів (`storage/cache/tpl/*`) — інакше віддасться стара версія. Локально кеш сам інвалідується за mtime; в адмінці є **Налаштування → Продуктивність → Очистити кеш**.
