Développement de thèmes

Un thème TubePress est un dossier de templates PHP accompagné d'assets optionnels et de fonctions utilitaires. Optez pour un thème personnalisé lorsque Apparence et l'éditeur de thème ne suffisent pas et que vous souhaitez un contrôle total sur le balisage. Cette page est le guide de création ; gardez la référence de l'API thème ouverte à côté pour la liste exhaustive des variables et des fonctions utilitaires.

La règle d'or à respecter : lisez les paramètres injectés par TubePress plutôt que de les coder en dur. Si vous respectez les variables préfixées par $_, votre thème reste entièrement configurable depuis l'administration, exactement comme le thème Simply inclus.

Structure du thème

Les thèmes se trouvent dans themes/{slug}/. Seuls theme.json et templates/layout.php sont strictement requis — tout le reste est optionnel et revient sur 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

Ce manifeste est obligatoire. Il contient les métadonnées du thème, un jeu de couleurs par défaut optionnel, et des settings arbitraires. Les champs name, version et author apparaissent dans /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

Ce fichier est chargé automatiquement au démarrage. Utilisez-le pour mettre en file d'attente votre feuille de style et vos scripts, et pour définir les fonctions utilitaires appelées par vos templates. Mettez les assets en file d'attente avec une chaîne de requête filemtime() afin que les navigateurs récupèrent toujours votre dernière modification ; le second argument est la priorité de chargement (une valeur plus faible charge en premier).

<?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 définit exactement ce type de fonction utilitaire — simplyVideoCard() — aux côtés de simplyPagination() et simplySortTabs(). L'appel ImpressionTracker::collect() alimente le classement CTR ; l'écriture groupée est vidée plus tard dans layout.php.

Templates & flux de rendu

Un contrôleur transmet les données à ThemeRenderer::render($template, $data), et le rendu prend le relais. Comprendre l'ordre vous aide à savoir ce qui est disponible à quel moment.

1. Le contrôleur effectue le rendu. p. ex. ThemeRenderer::render('home', ['videos' => $videos]).
2. Les variables globales sont injectées. Les variables $_ de site, d'apparence, de locale et de carte/lecture sont ajoutées.
3. Les plugins ajustent les données. Le filtre theme.template_data s'exécute en recevant ($data, $templateName).
4. Votre template effectue une mise en tampon. Le fichier template est capturé dans $content.
5. La mise en page se charge. layout.php reçoit $content ainsi que toutes les variables et produit le shell HTML complet.
6. Les impressions sont vidées. ImpressionTracker::flush() écrit la mise à jour CTR groupée avant </body>.
7. Le cron s'exécute. CronManager::run() exécute toutes les tâches planifiées arrivées à échéance.

Votre layout.php est responsable du shell : incluez ThemeRenderer::renderCSS() et $_colorOverrides dans <head>, affichez $content, puis appelez ThemeRenderer::renderJS() et ImpressionTracker::flush() avant </body>. L'API thème présente la liste de contrôle complète en huit points.

Variables globales & fonctions utilitaires

Chaque template reçoit les variables globales $_ ainsi que ses propres données. La référence de l'API thème les documente toutes ; voici celles que vous utiliserez le plus.

Repli de template

Si le thème actif ne dispose pas d'un template, TubePress affiche à la place la copie de Simply. Cela signifie que vous ne remplacez que ce que vous souhaitez modifier : commencez par copier un seul template — home.php, par exemple — dans votre thème, et laissez tout le reste hériter de Simply jusqu'à ce que vous soyez prêt à le prendre en charge. Un thème peut contenir un seul fichier ou une cinquantaine.

Hooks de thème

Au-delà des templates, un petit ensemble de points d'accrochage vous permet (ainsi qu'aux plugins) d'étendre la page sans la dupliquer. Les actions s'exécutent sans retour de valeur ; les filtres transforment une valeur que vous retournez.

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

Deux autres filtres méritent d'être connus : theme.template_data pour ajuster le tableau de données avant le rendu, et head.css pour ajouter une chaîne <style> — Simply utilise ce dernier pour publier son espacement de grille et son rayon en tant que variables CSS. Pour le catalogue complet des actions et filtres, consultez hooks & plugins.

Prochaines étapes