Desenvolvimento de temas

Um tema do TubePress é uma pasta de templates PHP com assets e funções auxiliares opcionais. Use um tema personalizado quando as configurações de Aparência e o editor de temas não forem suficientes e você quiser controle total do markup. Esta página é o guia de construção; mantenha a referência da API de temas aberta ao lado para a lista completa de variáveis e helpers.

A regra de ouro: leia as configurações injetadas pelo TubePress em vez de usá-las fixas no código. Se você respeitar as variáveis com prefixo $_, seu tema permanecerá totalmente configurável pelo admin, exatamente como o tema bundled Simply.

Estrutura do tema

Os temas ficam em themes/{slug}/. Apenas theme.json e templates/layout.php são estritamente necessários — todo o restante é opcional e faz fallback para 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

Este manifesto é obrigatório. Ele contém os metadados do tema, um conjunto de cores padrão opcional e configurações arbitrárias em settings. O name, version e author aparecem em /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 arquivo é carregado automaticamente na inicialização. Use-o para enfileirar sua folha de estilos e script, e para definir as funções auxiliares chamadas pelos seus templates. Enfileire os assets com uma query string filemtime() para que os navegadores sempre obtenham sua última edição; o segundo argumento é a prioridade de carregamento (menor = carrega 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 exatamente esse tipo de helper — simplyVideoCard() — junto com simplyPagination() e simplySortTabs(). A chamada ImpressionTracker::collect() é o que alimenta o ranking CTR; a gravação em lote é liberada mais tarde em layout.php.

Templates & o fluxo de renderização

Um controlador passa os dados para ThemeRenderer::render($template, $data), e o renderizador faz o restante. Entender a ordem ajuda a saber o que está disponível em cada etapa.

1. O controlador renderiza. Ex.: ThemeRenderer::render('home', ['videos' => $videos]).
2. As variáveis globais são injetadas. As variáveis com prefixo $_ de site, aparência, localidade e card/watch são adicionadas.
3. Os plugins ajustam os dados. O filtro theme.template_data é executado, recebendo ($data, $templateName).
4. Seu template é capturado no buffer. O arquivo de template é armazenado em $content.
5. O layout é carregado. layout.php recebe $content mais todas as variáveis e gera o shell HTML completo.
6. As impressões são descarregadas. ImpressionTracker::flush() grava a atualização CTR em lote antes de </body>.
7. O Cron é executado. CronManager::run() executa as tarefas agendadas pendentes.

Seu layout.php é responsável pelo shell: inclua ThemeRenderer::renderCSS() e $_colorOverrides no <head>, faça echo de $content, depois chame ThemeRenderer::renderJS() e ImpressionTracker::flush() antes de </body>. A API de temas lista o checklist completo de oito pontos.

Variáveis globais & helpers

Todo template recebe as variáveis globais $_ mais seus próprios dados. A referência da API de temas documenta todas elas; estas são as mais usadas.

Fallback de template

Se o tema ativo não tiver um template, o TubePress renderiza a cópia do Simply no lugar. Isso significa que você substitui apenas o que deseja alterar: comece copiando um único template — home.php, por exemplo — para o seu tema, e deixe todo o resto herdar do Simply até estar pronto para assumir o controle. Um tema pode ter um arquivo ou cinquenta.

Hooks do tema

Além dos templates, um pequeno conjunto de pontos de hook permite que você (e os plugins) estendam a página sem fazer um fork. Actions são do tipo fire-and-forget; filters transformam um valor que você retorna.

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

Mais dois filtros valem a pena conhecer: theme.template_data para ajustar o array de dados antes da renderização, e head.css para acrescentar uma string <style> — Simply usa o segundo para publicar o gap e o raio da grade como variáveis CSS. Para o catálogo mais amplo de actions/filters, consulte hooks & plugins.

Próximos passos