Разработка тем

Тема TubePress — это папка PHP-шаблонов плюс дополнительные ресурсы и вспомогательные функции. Создавайте пользовательскую тему, когда Appearance и редактор тем недостаточны и вам нужен полный контроль над разметкой. Эта страница — руководство по сборке; держите рядом справочник по API тем для исчерпывающего списка переменных и вспомогательных функций.

Главное правило: читайте настройки, внедряемые TubePress, а не задавайте их жёстко. Если вы используете переменные с префиксом $_, ваша тема останется полностью настраиваемой из административной панели, как и встроенная тема Simply.

Структура темы

Темы находятся в папке themes/{slug}/. Строго обязательны только theme.json и templates/layout.php — всё остальное необязательно и берётся из Simply.

themes/aurora/
├── theme.json            Required — metadata
├── functions.php         Enqueue assets, helper functions
├── assets/
│   ├── css/style.css
│   └── js/app.js
└── templates/
    ├── layout.php        Required — the HTML shell
    ├── home.php          Homepage
    ├── video.php         Watch page
    ├── category.php      …tag/performer/channel (+ plurals)
    ├── search.php        Search results
    ├── page.php          Static page
    ├── favorites.php     User favourites
    ├── history.php       Watch history
    ├── 404.php           Not found
    ├── auth/             login, register, profile
    └── partials/
        └── video-card.php  Reusable card partial

theme.json

Этот манифест обязателен. Он содержит метаданные темы, необязательный набор цветов по умолчанию и произвольные settings. Поля name, version и author отображаются в /admin/themes.

{
    "name": "Aurora",
    "description": "A custom theme for TubePress",
    "version": "1.0.0",
    "author": "Your Name",
    "screenshot": "screenshot.png",
    "colors": {
        "primary": "#2563eb",
        "secondary": "#7c3aed",
        "background": "#ffffff",
        "text": "#1e293b"
    },
    "settings": {
        "videos_per_row": 4
    }
}

functions.php

Этот файл загружается автоматически при запуске. Используйте его для подключения стилей и скриптов, а также для определения вспомогательных функций, вызываемых шаблонами. Добавляйте к ресурсам строку запроса filemtime(), чтобы браузеры всегда получали последнюю версию; второй аргумент — приоритет загрузки (меньшее значение — раньше).

<?php
declare(strict_types=1);

// filemtime() busts the cache on every edit.
$cssVer = @filemtime(ThemeManager::themePath()
    . '/assets/css/style.css') ?: time();
$jsVer  = @filemtime(ThemeManager::themePath()
    . '/assets/js/app.js') ?: time();

ThemeRenderer::enqueueCSS(
    ThemeManager::assetUrl('css/style.css') . '?v=' . $cssVer, 1);
ThemeRenderer::enqueueJS(
    ThemeManager::assetUrl('js/app.js') . '?v=' . $jsVer, 1);

// A reusable video-card helper, called from listing templates.
function auroraVideoCard(array $video): string
{
    // Record an impression so the CTR system can rank this card.
    ImpressionTracker::collect((int) $video['id']);

    // Let a plugin replace the card entirely if it wants to.
    $card = HookSystem::applyFilter('video.card.html', '', $video);
    if ($card !== '') {
        return $card;
    }

    ob_start();
    require ThemeManager::templatePath('partials/video-card');
    return ob_get_clean();
}

Simply определяет именно такой вспомогательный метод — simplyVideoCard() — наряду с simplyPagination() и simplySortTabs(). Вызов ImpressionTracker::collect() питает CTR-ранжирование; пакетная запись сбрасывается позже в layout.php.

Шаблоны и процесс рендеринга

Контроллер передаёт данные в ThemeRenderer::render($template, $data), и далее рендерер выполняет всё остальное. Понимание порядка поможет вам знать, что доступно на каждом этапе.

1. Контроллер выполняет рендеринг. Например, ThemeRenderer::render('home', ['videos' => $videos]).
2. Внедряются глобальные переменные. Добавляются переменные с префиксом $_ для сайта, внешнего вида, локали, карточек и страницы просмотра.
3. Плагины корректируют данные. Запускается фильтр theme.template_data, принимающий ($data, $templateName).
4. Шаблон буферизуется. Файл шаблона захватывается в $content.
5. Загружается макет. layout.php получает $content плюс все переменные и выводит полную HTML-оболочку.
6. Счётчики показов сбрасываются. ImpressionTracker::flush() записывает пакетное обновление CTR перед </body>.
7. Запускается cron. CronManager::run() выполняет все запланированные задачи с наступившим сроком.

Ваш layout.php отвечает за HTML-оболочку: включите ThemeRenderer::renderCSS() и $_colorOverrides в <head>, выведите $content, затем вызовите ThemeRenderer::renderJS() и ImpressionTracker::flush() перед </body>. API тем содержит полный контрольный список из восьми пунктов.

Глобальные переменные и вспомогательные функции

Каждый шаблон получает глобальные переменные $_ плюс собственные данные. Справочник по API тем документирует все из них; вот те, которые вы будете использовать чаще всего.

Резервный шаблон

Если в активной теме отсутствует шаблон, TubePress рендерит копию из Simply. Это означает, что вы переопределяете только то, что хотите изменить: начните с копирования одного шаблона — например, home.php — в вашу тему и позвольте всему остальному наследоваться от Simply, пока вы не будете готовы взять его под контроль. Тема может состоять из одного файла или пятидесяти.

Хуки темы

Помимо шаблонов, небольшой набор точек подключения позволяет вам (и плагинам) расширять страницу, не разветвляя её. Actions запускаются по принципу «выстрелил и забыл»; фильтры преобразуют возвращаемое значение.

// An action — fire and forget, inside <head>.
HookSystem::doAction('head.meta');

// A filter — return '' to keep the default card.
HookSystem::addFilter('video.card.html',
    function (string $html, array $video): string {
        return $html;
    });

Стоит знать ещё два фильтра: theme.template_data для корректировки массива данных перед рендерингом, и head.css для добавления строки <style> — Simply использует последний для публикации отступов сетки и радиуса скругления как CSS-переменных. Полный каталог действий и фильтров см. в разделе hooks & plugins.

Следующие шаги