Referência para desenvolvedores

Referência da API de temas

Referência da API de temas do TubePress: todas as variáveis globais de template, funções helper e classes disponíveis ao criar ou personalizar um tema de site de vídeos.

Esta página é a referência completa de tudo que um tema pode usar: as variáveis globais injetadas em cada template, as variáveis específicas de cada template e as classes auxiliares disponíveis no código do tema. Se você está criando ou personalizando um tema, mantenha esta página aberta ao lado de Desenvolvimento de temas.

Cada template é renderizado por ThemeRenderer::render($template, $data). O renderizador injeta um conjunto de variáveis globais com prefixo $_, mescla os dados específicos do template $data, executa o filtro theme.template_data, armazena em buffer seu template em $content e, em seguida, carrega layout.php.

Variáveis globais

Estas estão disponíveis em todos os templates e em layout.php.

Site

Variável	Tipo	Descrição
`$_template`	string	Nome do template atual (ex.: `'home'`, `'video'`)
`$_siteName`	string	Nome do site nas configurações
`$_siteDescription`	string	Descrição do site
`$_siteUrl`	string	URL do site
`$_videosPerRow`	int	Colunas da grade (4, 5 ou 6)
`$_user`	array\\|null	Usuário conectado ou null
`$_footerPages`	array	Páginas estáticas marcadas para o rodapé
`$_registrationEnabled`	bool	Alternância de registro
`$_ctrEnabled`	bool	Alternância de classificação CTR

Aparência

Variável	Tipo	Descrição
`$_siteLogo`	string	Nome do arquivo do logotipo (em `/uploads/branding/`)
`$_siteFavicon`	string	Nome do arquivo do favicon
`$_siteBackground`	string	Nome do arquivo da imagem de fundo
`$_siteBackgroundMode`	string	`'cover'`, `'contain'` ou `'repeat'`
`$_colorOverrides`	string	Bloco `<style>` com propriedades CSS personalizadas
`$_menuSearch`	bool	Exibir a barra de pesquisa
`$_menuItems`	array	Itens de navegação (`key`, `label`, `url`, `enabled`, `templates`)

Localidade

Variável	Tipo	Descrição
`$_locale`	string	Código da localidade atual (ex.: `'en'`)
`$_direction`	string	`'ltr'` ou `'rtl'`
`$_isRtl`	bool	Idioma da direita para a esquerda
`$_availableLangs`	array	Idiomas disponíveis
`$_langPrefix`	string	Prefixo da URL (ex.: `'/fr'` ou `''`)

Configurações do cartão de vídeo

Variável	Tipo	Descrição
`$_cardShowDuration`	bool	Exibir o emblema de duração
`$_cardShowTitle`	bool	Exibir o título do vídeo
`$_cardMetaLeft`	string	Meta à esquerda: `'views'`, `'likes'`, `'time'`, `'none'`
`$_cardMetaRight`	string	Meta à direita (mesmas opções)
`$_cardGridGap`	int	Espaçamento da grade em pixels
`$_cardBorderRadius`	int	Raio da borda do cartão em pixels
`$_cardThumbnailHover`	bool	Efeito de hover na miniatura
`$_cardTitleLines`	int	Linhas do título (1 ou 2)

Configurações da página de exibição

Variável	Tipo	Descrição
`$_watchShowViews`	bool	Exibir o contador de visualizações
`$_watchShowDuration`	bool	Exibir a duração
`$_watchShowDate`	bool	Exibir a data de publicação
`$_watchShowLikes`	bool	Exibir curtir / não curtir
`$_watchShowFavorites`	bool	Exibir o botão de favorito
`$_watchShowPornstars`	bool	Exibir performers
`$_watchShowChannels`	bool	Exibir canais
`$_watchShowCategories`	bool	Exibir categorias
`$_watchShowTags`	bool	Exibir tags
`$_commentsEnabled`	bool	Comentários ativados

São configurações, não mágica. Cada valor de $_card* e $_watch* vem diretamente da tela de Aparência do admin, portanto os proprietários do site podem reestilizar seu tema sem tocar no código — desde que você leia essas variáveis em vez de codificá-las.

Variáveis específicas do template

Além das variáveis globais, cada template recebe seus próprios dados.

home.php

Variável	Tipo
`$videos`	array — linhas de vídeo
`$pagination`	Objeto de paginação
`$sort`	string — chave de ordenação atual

video.php

Variável	Tipo
`$video`	array — vídeo completo com categorias, tags, performers e canais
`$categories`, `$tags`, `$performers`	array
`$comments`	array
`$similar`	array — vídeos semelhantes
`$recommended`	array — vídeos recomendados
`$userVote`	string\\|null — `'like'`, `'dislike'` ou null
`$isFavorited`	bool

category.php / tag.php / performer.php / channel.php

Variável	Tipo
`$category` / `$tag` / `$performer` / `$channel`	array — a entidade
`$videos`	array — linhas de vídeo
`$pagination`	Objeto de paginação
`$sort`	string

Templates de listagem

Template	Variáveis notáveis
`categories.php`	`$categories` — cada uma tem `video_count`; com CTR ativado, `best_video_thumbnail`
`performers.php`	`$performers` — `video_count`; com CTR ativado, `best_video_thumbnail`, `total_ctr`, ordenado por CTR; `$pagination`
`channels.php`	Mesma estrutura que performers
`search.php`	`$query`, `$videos`, `$pagination`

Classes auxiliares

Estes auxiliares estáticos estão disponíveis em todos os templates.

Classe	Métodos principais
`ThemeRenderer`	`::enqueueCSS($url, $priority)`, `::enqueueJS($url, $priority)`, `::partial($name, $data)`, `::bodyClass()`, `::renderCSS()`, `::renderJS()`
`ThemeManager`	`::assetUrl($path)`, `::themePath()`, `::templatePath($t)`, `::active()`, `::info($key)`
`ImpressionTracker`	`::collect($videoId)`, `::flush()`, `::isBot()`
`Format`	`::number($n)`, `::duration($seconds)`, `::timeAgo($datetime)`, `::fileSize($bytes)`
`Pagination`	`->total`, `->page`, `->totalPages`, `->offset`, `->hasPrev()`, `->hasNext()`, `->pages()`, `->prevUrl()`, `->nextUrl()`
`Router`	`::url($path)`, `::csrfField()`, `::csrfToken()`, `::langPrefix()`
`HookSystem`	`::doAction($event, ...$args)`, `::applyFilter($filter, $value, ...$args)`
`Auth`	`::check()`, `::user()`, `::id()`
`Setting`	`::get($key, $default)`
`__($key, $replacements)`	Auxiliar de tradução
`url($path)`	Atalho para `Router::url($path)`

O fluxo de renderização

O controlador chama o renderizador. ThemeRenderer::render('home', ['videos' => $videos, …]).
As variáveis globais são injetadas. As variáveis de site, aparência, localidade e cartão/exibição com prefixo $_ são adicionadas.
Plugins podem modificar os dados. HookSystem::applyFilter('theme.template_data', $data, $templateName) é executado.
O template é renderizado. Seu arquivo de template é armazenado em buffer em $content.
O layout é carregado. layout.php recebe $content mais todas as variáveis.
As impressões são enviadas. ImpressionTracker::flush() envia a atualização em lote de impressões (CTR).
O cron é executado. CronManager::run() executa quaisquer tarefas agendadas pendentes.

Requisitos do layout.php

O layout.php de um tema deve fazer o seguinte:

Emitir o shell HTML completo (<!DOCTYPE html> … </html>).
Incluir <?= ThemeRenderer::renderCSS() ?> em <head>.
Incluir <?= $_colorOverrides ?> em <head>.
Ecoar $content dentro de <main>.
Incluir <?= ThemeRenderer::renderJS() ?> antes de </body>.
Chamar <?php ImpressionTracker::flush(); ?> antes de </body> (para CTR).
Chamar <?php HookSystem::doAction('head.meta'); ?> em <head>.
Chamar <?php HookSystem::doAction('footer.scripts'); ?> antes de </body>.

Fallback de template

Se um template estiver ausente no tema ativo, o TubePress usa como fallback o tema Simply integrado. Um tema personalizado, portanto, só precisa substituir os templates que realmente deseja alterar — comece com um template e expanda a partir daí.

Próximos passos

Desenvolvimento de temasConstrua um tema do zero, passo a passo. Hooks & pluginsAções e filtros aos quais você pode se conectar. ArquiteturaComo todo o CMS se encaixa.

Ainda com dúvidas?

Abra um ticket pelo painel e nossa equipe vai ajudá-lo.

Experimente o demo ao vivo → Baixar TubePress →