Referencia para desarrolladores

Referencia de la API de temas

Referencia de la API de temas de TubePress: todas las variables globales de plantilla, funciones auxiliares y clases disponibles al crear o personalizar el tema de un sitio tube.

Esta página es la referencia completa de todo lo que puede usar un tema: las variables globales inyectadas en cada plantilla, las variables específicas de cada plantilla y las clases auxiliares disponibles en el código del tema. Si estás creando o personalizando un tema, mantén esta página abierta junto a Desarrollo de temas.

Cada plantilla es renderizada por ThemeRenderer::render($template, $data). El renderizador inyecta un conjunto de variables globales con prefijo $_, fusiona los $data específicos de la plantilla, ejecuta el filtro theme.template_data, almacena en búfer tu plantilla en $content y luego carga layout.php.

Variables globales

Estas están disponibles en cada plantilla y en layout.php.

Sitio

Variable	Tipo	Descripción
`$_template`	string	Nombre de la plantilla actual (p. ej. `'home'`, `'video'`)
`$_siteName`	string	Nombre del sitio desde la configuración
`$_siteDescription`	string	Descripción del sitio
`$_siteUrl`	string	URL del sitio
`$_videosPerRow`	int	Columnas de la cuadrícula (4, 5 o 6)
`$_user`	array\\|null	Usuario con sesión iniciada, o null
`$_footerPages`	array	Páginas estáticas marcadas para el pie de página
`$_registrationEnabled`	bool	Interruptor de registro
`$_ctrEnabled`	bool	Interruptor de clasificación CTR

Apariencia

Variable	Tipo	Descripción
`$_siteLogo`	string	Nombre del archivo del logotipo (en `/uploads/branding/`)
`$_siteFavicon`	string	Nombre del archivo del favicon
`$_siteBackground`	string	Nombre del archivo de imagen de fondo
`$_siteBackgroundMode`	string	`'cover'`, `'contain'` o `'repeat'`
`$_colorOverrides`	string	Bloque `<style>` con propiedades CSS personalizadas
`$_menuSearch`	bool	Mostrar la barra de búsqueda
`$_menuItems`	array	Elementos de navegación (`key`, `label`, `url`, `enabled`, `templates`)

Configuración regional

Variable	Tipo	Descripción
`$_locale`	string	Código de configuración regional actual (p. ej. `'en'`)
`$_direction`	string	`'ltr'` o `'rtl'`
`$_isRtl`	bool	Idioma de derecha a izquierda
`$_availableLangs`	array	Idiomas disponibles
`$_langPrefix`	string	Prefijo de URL (p. ej. `'/fr'` o `''`)

Configuración de la tarjeta de vídeo

Variable	Tipo	Descripción
`$_cardShowDuration`	bool	Mostrar la insignia de duración
`$_cardShowTitle`	bool	Mostrar el título del vídeo
`$_cardMetaLeft`	string	Meta izquierda: `'views'`, `'likes'`, `'time'`, `'none'`
`$_cardMetaRight`	string	Meta derecha (mismas opciones)
`$_cardGridGap`	int	Espacio entre tarjetas en píxeles
`$_cardBorderRadius`	int	Radio del borde de la tarjeta en píxeles
`$_cardThumbnailHover`	bool	Efecto al pasar el cursor sobre la miniatura
`$_cardTitleLines`	int	Líneas del título (1 o 2)

Configuración de la página de reproducción

Variable	Tipo	Descripción
`$_watchShowViews`	bool	Mostrar el número de reproducciones
`$_watchShowDuration`	bool	Mostrar la duración
`$_watchShowDate`	bool	Mostrar la fecha de publicación
`$_watchShowLikes`	bool	Mostrar me gusta / no me gusta
`$_watchShowFavorites`	bool	Mostrar el botón de favoritos
`$_watchShowPornstars`	bool	Mostrar intérpretes
`$_watchShowChannels`	bool	Mostrar canales
`$_watchShowCategories`	bool	Mostrar categorías
`$_watchShowTags`	bool	Mostrar etiquetas
`$_commentsEnabled`	bool	Comentarios habilitados

Estos son ajustes, no magia. Cada valor de $_card* y $_watch* proviene directamente de la pantalla de administración de Apariencia, por lo que los propietarios del sitio pueden rediseñar tu tema sin tocar el código, siempre que leas estas variables en lugar de codificarlas de forma fija.

Variables específicas de plantilla

Además de las globales, cada plantilla recibe sus propios datos.

home.php

Variable	Tipo
`$videos`	array — filas de vídeos
`$pagination`	Objeto Pagination
`$sort`	string — clave de orden actual

video.php

Variable	Tipo
`$video`	array — vídeo completo con categorías, etiquetas, intérpretes y canales
`$categories`, `$tags`, `$performers`	array
`$comments`	array
`$similar`	array — vídeos similares
`$recommended`	array — vídeos recomendados
`$userVote`	string\\|null — `'like'`, `'dislike'` o null
`$isFavorited`	bool

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

Variable	Tipo
`$category` / `$tag` / `$performer` / `$channel`	array — la entidad
`$videos`	array — filas de vídeos
`$pagination`	Objeto Pagination
`$sort`	string

Plantillas de listado

Plantilla	Variables destacadas
`categories.php`	`$categories` — cada una tiene `video_count`; con CTR activado, `best_video_thumbnail`
`performers.php`	`$performers` — `video_count`; con CTR activado, `best_video_thumbnail`, `total_ctr`, ordenado por CTR; `$pagination`
`channels.php`	Misma estructura que performers
`search.php`	`$query`, `$videos`, `$pagination`

Clases auxiliares

Estos auxiliares estáticos están disponibles en cada plantilla.

Clase	Métodos principales
`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 traducción
`url($path)`	Atajo para `Router::url($path)`

El flujo de renderizado

El controlador llama al renderizador. ThemeRenderer::render('home', ['videos' => $videos, …]).
Se inyectan las globales. Se añaden las variables de sitio, apariencia, configuración regional y tarjeta/reproducción con prefijo $_.
Los plugins pueden modificar los datos. Se ejecuta HookSystem::applyFilter('theme.template_data', $data, $templateName).
La plantilla se renderiza. Tu archivo de plantilla se almacena en búfer en $content.
Se carga el diseño. layout.php recibe $content más todas las variables.
Se vacían las impresiones. ImpressionTracker::flush() envía la actualización acumulada de impresiones (CTR).
Cron se ejecuta. CronManager::run() ejecuta las tareas programadas pendientes.

Requisitos de layout.php

El layout.php de un tema debe hacer todo lo siguiente:

Mostrar la estructura HTML completa (<!DOCTYPE html> … </html>).
Incluir <?= ThemeRenderer::renderCSS() ?> en <head>.
Incluir <?= $_colorOverrides ?> en <head>.
Mostrar $content dentro de <main>.
Incluir <?= ThemeRenderer::renderJS() ?> antes de </body>.
Llamar a <?php ImpressionTracker::flush(); ?> antes de </body> (para CTR).
Llamar a <?php HookSystem::doAction('head.meta'); ?> en <head>.
Llamar a <?php HookSystem::doAction('footer.scripts'); ?> antes de </body>.

Plantilla de respaldo

Si falta una plantilla en el tema activo, TubePress recurre al tema Simply incluido. Por tanto, un tema personalizado solo necesita reemplazar las plantillas que realmente quiere cambiar: empieza con una plantilla y ve ampliando desde ahí.

Próximos pasos

Desarrollo de temasCrea un tema desde cero, paso a paso. Hooks y pluginsAcciones y filtros a los que puedes conectarte. ArquitecturaCómo encaja todo el CMS.

¿Todavía con dudas?

Abre un ticket desde tu panel y nuestro equipo te ayudará.

Prueba la demo en vivo → Descargar TubePress →