Themaontwikkeling

Een TubePress-thema is een map met PHP-sjablonen, optionele bestanden en hulpfuncties. Gebruik een aangepast thema wanneer Weergave en de thema-editor niet voldoende zijn en je volledige controle wilt over de opmaak. Deze pagina is de bouwgids; houd de thema-API-referentie er naast voor de uitputtende lijst van variabelen en hulpfuncties.

De gulden regel: lees de instellingen die TubePress injecteert in plaats van hardcoderen. Als je de variabelen met het voorvoegsel $_ respecteert, blijft je thema volledig configureerbaar vanuit het beheerderspaneel, net als het meegeleverde Simply-thema.

Themastructuur

Thema's bevinden zich in themes/{slug}/. Alleen theme.json en templates/layout.php zijn strikt vereist — alles andere is optioneel en valt terug op 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

Dit manifest is verplicht. Het bevat de metadata van het thema, een optionele standaard kleurenset en willekeurige settings. De name, version en author verschijnen in /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

Dit bestand wordt automatisch geladen bij het opstarten. Gebruik het om je stijlblad en script in te laden en om de hulpfuncties te definiëren die je sjablonen aanroepen. Laad bestanden in met een filemtime()-querystring zodat browsers altijd je laatste bewerking ophalen; het tweede argument is de laadprioriteit (lager laadt eerder).

<?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 definieert exact dit soort hulpfunctie — simplyVideoCard() — naast simplyPagination() en simplySortTabs(). De aanroep ImpressionTracker::collect() voedt de CTR-rangschikking; de gebundelde schrijfactie wordt later in layout.php geleegd.

Sjablonen & de renderstroom

Een controller geeft gegevens door aan ThemeRenderer::render($template, $data), en de renderer neemt het van daar over. De volgorde begrijpen helpt je te weten wat er beschikbaar is waar.

1. De controller rendert. bijv. ThemeRenderer::render('home', ['videos' => $videos]).
2. Globale variabelen worden geïnjecteerd. De variabelen met het voorvoegsel $_ voor site, weergave, landinstelling en kaart/kijken worden toegevoegd.
3. Plugins passen de gegevens aan. Het filter theme.template_data wordt uitgevoerd en ontvangt ($data, $templateName).
4. Je sjabloon buffert. Het sjabloonbestand wordt vastgelegd in $content.
5. De lay-out wordt geladen. layout.php ontvangt $content plus alle variabelen en geeft de volledige HTML-shell weer.
6. Vertoningen worden geleegd. ImpressionTracker::flush() schrijft de gebundelde CTR-update vóór </body>.
7. Cron wordt uitgevoerd. CronManager::run() voert alle geplande taken uit.

Je layout.php is verantwoordelijk voor de shell: voeg ThemeRenderer::renderCSS() en $_colorOverrides toe in <head>, echo $content, roep daarna ThemeRenderer::renderJS() en ImpressionTracker::flush() aan vóór </body>. De thema-API vermeldt de volledige checklist van acht punten.

Globale variabelen & hulpfuncties

Elk sjabloon ontvangt de globale $_-variabelen plus zijn eigen gegevens. De thema-API-referentie documenteert ze allemaal; dit zijn de meest gebruikte.

Sjabloon-terugval

Als het actieve thema een sjabloon mist, rendert TubePress in plaats daarvan de kopie van Simply. Dat betekent dat je alleen overschrijft wat je wilt veranderen: begin met het kopiëren van één sjabloon — home.php, bijvoorbeeld — naar je thema en laat alles andere erven van Simply totdat je klaar bent om het over te nemen. Een thema kan uit één bestand of vijftig bestanden bestaan.

Thema-hooks

Naast sjablonen laat een kleine reeks hookpunten je (en plugins) de pagina uitbreiden zonder hem te forken. Acties worden eenmalig uitgevoerd; filters transformeren een waarde die je teruggeeft.

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

Nog twee filters zijn de moeite waard om te kennen: theme.template_data om de gegevensarray vóór het renderen aan te passen, en head.css om een <style>-tekenreeks toe te voegen — Simply gebruikt de laatste om zijn rasterafstand en radius als CSS-variabelen te publiceren. Zie voor de bredere actie/filter-catalogus hooks & plugins.

Volgende stappen