Desarrollo de temas

Un tema de TubePress es una carpeta de plantillas PHP con activos opcionales y funciones auxiliares. Recurre a un tema personalizado cuando Apariencia y el editor de temas no son suficientes y deseas control total del marcado. Esta página es la guía de construcción; mantén la referencia de la API del tema abierta junto a ella para la lista exhaustiva de variables y helpers.

La regla de oro es: lee los ajustes que TubePress inyecta en lugar de escribirlos de forma fija. Si respetas las variables con prefijo $_, tu tema permanece completamente configurable desde el admin, exactamente como el tema incluido Simply.

Estructura del tema

Los temas viven bajo themes/{slug}/. Solo theme.json y templates/layout.php son estrictamente necesarios — todo lo demás es opcional y recae en Simply como respaldo.

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

Este manifiesto es obligatorio. Contiene los metadatos del tema, un conjunto de colores predeterminados opcional y settings arbitrarios. El name, version y author aparecen en /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

Este archivo se carga automáticamente al inicio. Úsalo para encolar tu hoja de estilos y script, y para definir las funciones auxiliares que llaman tus plantillas. Encola los activos con una cadena de consulta filemtime() para que los navegadores siempre obtengan tu última edición; el segundo argumento es la prioridad de carga (un valor menor carga antes).

<?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 define exactamente este tipo de helper — simplyVideoCard() — junto con simplyPagination() y simplySortTabs(). La llamada a ImpressionTracker::collect() es la que alimenta el ranking CTR; la escritura en lote se vacía más tarde en layout.php.

Plantillas y el flujo de renderizado

Un controlador pasa datos a ThemeRenderer::render($template, $data), y el renderizador toma el control desde ahí. Entender el orden te ayuda a saber qué está disponible en cada punto.

1. El controlador renderiza. p. ej. ThemeRenderer::render('home', ['videos' => $videos]).
2. Se inyectan las variables globales. Se añaden las variables de sitio, apariencia, configuración regional y tarjeta/reproducción con prefijo $_.
3. Los plugins ajustan los datos. Se ejecuta el filtro theme.template_data, recibiendo ($data, $templateName).
4. Tu plantilla se almacena en búfer. El archivo de plantilla se captura en $content.
5. Se carga el layout. layout.php recibe $content junto con todas las variables y genera el shell HTML completo.
6. Se vacían las impresiones. ImpressionTracker::flush() escribe la actualización de CTR en lote antes de </body>.
7. Se ejecuta el cron. CronManager::run() ejecuta las tareas programadas pendientes.

Tu layout.php es responsable del shell: incluye ThemeRenderer::renderCSS() y $_colorOverrides en <head>, escribe $content, luego llama a ThemeRenderer::renderJS() e ImpressionTracker::flush() antes de </body>. La API del tema incluye la lista de verificación completa de ocho puntos.

Variables globales y helpers

Cada plantilla recibe las variables globales $_ más sus propios datos. La referencia de la API del tema las documenta todas; estas son las que usarás con más frecuencia.

Plantilla de respaldo

Si al tema activo le falta una plantilla, TubePress renderiza en su lugar la copia de Simply. Eso significa que solo reemplazas lo que quieres cambiar: empieza copiando una sola plantilla — home.php, por ejemplo — en tu tema, y deja que todo lo demás herede de Simply hasta que estés listo para tomarlo. Un tema puede ser un archivo o cincuenta.

Hooks del tema

Más allá de las plantillas, un pequeño conjunto de puntos de enganche te permite (y a los plugins) extender la página sin hacer un fork. Las acciones son de disparar y olvidar; los filtros transforman un valor que devuelves.

// 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 conocer dos filtros más: theme.template_data para ajustar el arreglo de datos antes del renderizado, y head.css para agregar una cadena <style> — Simply usa el segundo para publicar su espacio de cuadrícula y radio como variables CSS. Para el catálogo más amplio de acciones y filtros, consulta hooks y plugins.

Pasos siguientes