Sviluppo di temi

Un tema TubePress è una cartella di template PHP con risorse opzionali e funzioni di supporto. Ricorri a un tema personalizzato quando Aspetto e l'editor di tema non sono sufficienti e desideri il pieno controllo del markup. Questa pagina è la guida alla creazione; tieni aperto il riferimento API del tema accanto ad essa per l'elenco esaustivo di variabili e helper.

La regola d'oro: leggi le impostazioni che TubePress inietta invece di codificarle a mano. Se rispetti le variabili con prefisso $_, il tuo tema rimane completamente configurabile dall'admin, esattamente come il tema Simply incluso.

Struttura del tema

I temi risiedono in themes/{slug}/. Solo theme.json e templates/layout.php sono strettamente necessari — tutto il resto è facoltativo e ricade su 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

Questo manifest è obbligatorio. Contiene i metadati del tema, un insieme di colori predefiniti opzionale e impostazioni arbitrarie. name, version e author appaiono 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

Questo file viene caricato automaticamente all'avvio. Usalo per accodare il foglio di stile e lo script e per definire le funzioni di supporto chiamate dai tuoi template. Accoda le risorse con una query string filemtime() in modo che i browser rilevino sempre l'ultima modifica; il secondo argomento è la priorità di caricamento (valori più bassi caricano prima).

<?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 definisce esattamente questo tipo di helper — simplyVideoCard() — insieme a simplyPagination() e simplySortTabs(). La chiamata a ImpressionTracker::collect() alimenta il ranking CTR; la scrittura in batch viene scaricata in seguito in layout.php.

Template & flusso di rendering

Un controller passa i dati a ThemeRenderer::render($template, $data), e il renderer si occupa del resto. Capire l'ordine aiuta a sapere cosa è disponibile e dove.

1. Il controller effettua il rendering. Es. ThemeRenderer::render('home', ['videos' => $videos]).
2. Le variabili globali vengono iniettate. Le variabili con prefisso $_ di sito, aspetto, lingua e card/watch vengono aggiunte.
3. I plugin modificano i dati. Il filtro theme.template_data viene eseguito, ricevendo ($data, $templateName).
4. Il tuo template viene bufferizzato. Il file template viene catturato in $content.
5. Il layout viene caricato. layout.php riceve $content più tutte le variabili e genera il guscio HTML completo.
6. Le impressioni vengono scaricate. ImpressionTracker::flush() scrive l'aggiornamento CTR in batch prima di </body>.
7. Il cron viene eseguito. CronManager::run() esegue le attività pianificate in scadenza.

Il tuo layout.php è responsabile del guscio: includi ThemeRenderer::renderCSS() e $_colorOverrides in <head>, usa echo su $content, poi chiama ThemeRenderer::renderJS() e ImpressionTracker::flush() prima di </body>. L'API del tema elenca la lista di controllo completa in otto punti.

Variabili globali e helper

Ogni template riceve le variabili globali $_ più i propri dati. Il riferimento API del tema le documenta tutte; queste sono quelle che utilizzerai più spesso.

Fallback dei template

Se il tema attivo manca di un template, TubePress utilizza la copia di Simply al suo posto. Ciò significa che devi sovrascrivere solo ciò che vuoi cambiare: inizia copiando un singolo template — ad esempio home.php — nel tuo tema, e lascia che tutto il resto erediti da Simply finché non sei pronto a prenderne il controllo. Un tema può essere composto da un file o da cinquanta.

Hook del tema

Oltre ai template, un piccolo insieme di punti di hook permette a te (e ai plugin) di estendere la pagina senza doverla forkare. Le action sono fire-and-forget; i filter trasformano un valore che restituisci.

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

Vale la pena conoscere altri due filtri: theme.template_data per modificare l'array di dati prima del rendering, e head.css per aggiungere una stringa <style> — Simply usa quest'ultimo per pubblicare il gap della griglia e il raggio come variabili CSS. Per il catalogo più ampio di action/filter, vedi hook e plugin.

Passi successivi