Theme-Entwicklung

Ein TubePress-Theme ist ein Ordner mit PHP-Templates sowie optionalen Assets und Hilfsfunktionen. Greife auf ein benutzerdefiniertes Theme zurück, wenn Appearance und der Theme-Editor nicht ausreichen und du die volle Kontrolle über das Markup benötigst. Diese Seite ist der Entwicklungsleitfaden; halte die Theme-API-Referenz daneben geöffnet, um die vollständige Liste der Variablen und Hilfsfunktionen einzusehen.

Die goldene Regel gilt durchgehend: Lies die Einstellungen, die TubePress injiziert, anstatt sie fest zu kodieren. Wenn du die Variablen mit dem Präfix $_ verwendest, bleibt dein Theme vollständig über das Admin-Panel konfigurierbar – genau wie das mitgelieferte Simply-Theme.

Theme-Struktur

Themes befinden sich unter themes/{slug}/. Nur theme.json und templates/layout.php sind zwingend erforderlich — alles andere ist optional und fällt auf Simply zurück.

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

Diese Manifestdatei ist erforderlich. Sie enthält die Metadaten des Themes, einen optionalen Standard-Farbsatz und beliebige settings. Die Felder name, version und author werden in /admin/themes angezeigt.

{
    "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

Diese Datei wird beim Start automatisch geladen. Verwende sie, um dein Stylesheet und dein Skript einzubinden und die Hilfsfunktionen zu definieren, die deine Templates aufrufen. Binde Assets mit einem filemtime()-Query-String ein, damit Browser stets die neueste Version laden; das zweite Argument ist die Ladepriorität (kleiner = früher).

<?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 definiert genau diese Art von Hilfsfunktion — simplyVideoCard() — gemeinsam mit simplyPagination() und simplySortTabs(). Der Aufruf ImpressionTracker::collect() speist das CTR-Ranking; der gebündelte Schreibvorgang wird später in layout.php geleert.

Templates & der Rendering-Ablauf

Ein Controller übergibt Daten an ThemeRenderer::render($template, $data), und der Renderer übernimmt von dort. Das Verstehen der Reihenfolge hilft zu wissen, was wo verfügbar ist.

1. Der Controller rendert. Z. B. ThemeRenderer::render('home', ['videos' => $videos]).
2. Globale Variablen werden injiziert. Die mit $_ präfixierten Site-, Appearance-, Locale- und Card/Watch-Variablen werden hinzugefügt.
3. Plugins passen die Daten an. Der Filter theme.template_data wird ausgeführt und erhält ($data, $templateName).
4. Dein Template puffert. Die Template-Datei wird in $content erfasst.
5. Das Layout wird geladen. layout.php erhält $content sowie alle Variablen und gibt die vollständige HTML-Hülle aus.
6. Impressionen werden geleert. ImpressionTracker::flush() schreibt das gebündelte CTR-Update vor </body>.
7. Cron läuft. CronManager::run() führt alle fälligen geplanten Aufgaben aus.

Dein layout.php ist für die HTML-Hülle verantwortlich: Binde ThemeRenderer::renderCSS() und $_colorOverrides in <head> ein, gib $content aus und rufe dann ThemeRenderer::renderJS() und ImpressionTracker::flush() vor </body> auf. Die Theme-API listet die vollständige Acht-Punkte-Checkliste auf.

Globale Variablen & Hilfsfunktionen

Jedes Template erhält die globalen $_-Variablen plus seine eigenen Daten. Die Theme-API-Referenz dokumentiert alle; dies sind die am häufigsten verwendeten.

Template-Fallback

Wenn dem aktiven Theme ein Template fehlt, rendert TubePress stattdessen Simply's Version. Das bedeutet, du überschreibst nur, was du ändern möchtest: Beginne damit, ein einzelnes Template — z. B. home.php — in dein Theme zu kopieren, und lass alles andere von Simply erben, bis du bereit bist, es zu übernehmen. Ein Theme kann aus einer oder fünfzig Dateien bestehen.

Theme-Hooks

Über Templates hinaus ermöglicht eine kleine Menge an Hook-Punkten dir (und Plugins), die Seite zu erweitern, ohne sie zu forken. Actions sind Fire-and-Forget; Filter transformieren einen Wert, den du zurückgibst.

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

Zwei weitere Filter sind es wert zu kennen: theme.template_data, um das Daten-Array vor dem Rendern anzupassen, und head.css, um einen <style>-String anzuhängen — Simply nutzt Letzteren, um seinen Grid-Abstand und Radius als CSS-Variablen zu veröffentlichen. Den vollständigen Katalog an Actions und Filtern findest du unter Hooks & Plugins.

Nächste Schritte