Tworzenie motywów

Motyw TubePress to folder szablonów PHP oraz opcjonalnych zasobów i funkcji pomocniczych. Sięgnij po własny motyw, gdy Wygląd i edytor motywów nie wystarczają i chcesz mieć pełną kontrolę nad znacznikami. Ta strona jest przewodnikiem budowania motywu; trzymaj obok dokumentację API motywu z wyczerpującą listą zmiennych i funkcji pomocniczych.

Złota zasada: odczytuj ustawienia wstrzykiwane przez TubePress zamiast wpisywać je na stałe. Jeśli respektujesz zmienne z prefiksem $_, Twój motyw pozostaje w pełni konfigurowalny z panelu administracyjnego — dokładnie jak dołączony motyw Simply.

Struktura motywu

Motywy znajdują się w katalogu themes/{slug}/. Wymagane są jedynie theme.json i templates/layout.php — wszystko pozostałe jest opcjonalne i domyślnie korzysta z motywu 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

Ten manifest jest wymagany. Zawiera metadane motywu, opcjonalny domyślny zestaw kolorów oraz dowolne settings. name, version i author są wyświetlane w /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

Ten plik jest ładowany automatycznie przy uruchamianiu. Służy do kolejkowania arkusza stylów i skryptu oraz do definiowania funkcji pomocniczych wywoływanych przez szablony. Kolejkuj zasoby z ciągiem zapytania filemtime(), aby przeglądarki zawsze pobierały najnowszą wersję; drugi argument to priorytet ładowania (niższa wartość = wcześniejsze ładowanie).

<?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 definiuje dokładnie taki rodzaj funkcji pomocniczej — simplyVideoCard() — obok simplyPagination() i simplySortTabs(). Wywołanie ImpressionTracker::collect() zasila ranking CTR; zgromadzone zapisy są opróżniane później w layout.php.

Szablony i przepływ renderowania

Kontroler przekazuje dane do ThemeRenderer::render($template, $data), a renderer przejmuje dalsze działanie. Zrozumienie kolejności pomaga wiedzieć, co jest dostępne i gdzie.

1. Kontroler renderuje. np. ThemeRenderer::render('home', ['videos' => $videos]).
2. Wstrzykiwane są zmienne globalne. Dodawane są zmienne witryny, wyglądu, lokalizacji i karty/odtwarzania z prefiksem $_.
3. Wtyczki dostosowują dane. Uruchamiany jest filtr theme.template_data, otrzymujący ($data, $templateName).
4. Twój szablon jest buforowany. Plik szablonu jest przechwytywany do $content.
5. Ładowany jest layout. layout.php otrzymuje $content oraz wszystkie zmienne i generuje pełną powłokę HTML.
6. Wyświetlenia są zapisywane. ImpressionTracker::flush() zapisuje zgromadzone aktualizacje CTR przed </body>.
7. Cron uruchamia się. CronManager::run() wykonuje zaplanowane zadania, których termin nadszedł.

Twój layout.php jest odpowiedzialny za powłokę: dołącz ThemeRenderer::renderCSS() i $_colorOverrides w <head>, wyświetl $content, a następnie wywołaj ThemeRenderer::renderJS() i ImpressionTracker::flush() przed </body>. API motywu zawiera pełną ośmiopunktową listę kontrolną.

Zmienne globalne i funkcje pomocnicze

Każdy szablon otrzymuje globalne zmienne $_ oraz własne dane. Dokumentacja API motywu opisuje je wszystkie; poniżej te, których będziesz używać najczęściej.

Zastępczy szablon

Jeśli w aktywnym motywie brakuje szablonu, TubePress renderuje zamiast niego kopię z motywu Simply. Oznacza to, że nadpisujesz tylko to, co chcesz zmienić: zacznij od skopiowania jednego szablonu — na przykład home.php — do swojego motywu i pozwól, aby wszystko inne dziedziczyło z Simply, dopóki nie będziesz gotowy przejąć kontrolę. Motyw może składać się z jednego pliku lub pięćdziesięciu.

Hooki motywu

Poza szablonami, niewielki zestaw punktów zaczepienia pozwala Tobie (i wtyczkom) rozszerzać stronę bez jej rozwidlania. Akcje działają na zasadzie „wystrzel i zapomnij"; filtry przekształcają wartość, którą zwracasz.

// 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;
    });

Warto znać jeszcze dwa filtry: theme.template_data do dostosowania tablicy danych przed renderowaniem oraz head.css do dołączania ciągu <style> — Simply używa tego ostatniego do publikowania odstępu siatki i promienia jako zmiennych CSS. Aby zapoznać się z szerszym katalogiem akcji i filtrów, zobacz hooki i wtyczki.

Następne kroki