Riferimento per sviluppatori

Riferimento Theme API

Riferimento Theme API di TubePress: ogni variabile globale di template, funzione helper e classe disponibile quando si crea o si personalizza un tema per tube site.

Questa pagina è il riferimento completo per tutto ciò che un tema può utilizzare: le variabili globali iniettate in ogni template, le variabili specifiche per ciascun template e le classi helper disponibili nel codice del tema. Se stai creando o personalizzando un tema, tieni questa pagina aperta insieme a Sviluppo del tema.

Ogni template è renderizzato da ThemeRenderer::render($template, $data). Il renderer inietta un insieme di variabili globali con prefisso $_, le unisce ai dati $data specifici del template, esegue il filtro theme.template_data, inserisce il tuo template in un buffer come $content, poi carica layout.php.

Variabili globali

Queste sono disponibili in ogni template e in layout.php.

Sito

Variabile	Tipo	Descrizione
`$_template`	string	Nome del template corrente (es. `'home'`, `'video'`)
`$_siteName`	string	Nome del sito dalle impostazioni
`$_siteDescription`	string	Descrizione del sito
`$_siteUrl`	string	URL del sito
`$_videosPerRow`	int	Colonne della griglia (4, 5 o 6)
`$_user`	array\\|null	Utente autenticato, o null
`$_footerPages`	array	Pagine statiche contrassegnate per il footer
`$_registrationEnabled`	bool	Interruttore registrazione
`$_ctrEnabled`	bool	Interruttore classifica CTR

Aspetto

Variabile	Tipo	Descrizione
`$_siteLogo`	string	Nome file del logo (in `/uploads/branding/`)
`$_siteFavicon`	string	Nome file della favicon
`$_siteBackground`	string	Nome file dell'immagine di sfondo
`$_siteBackgroundMode`	string	`'cover'`, `'contain'` o `'repeat'`
`$_colorOverrides`	string	Blocco `<style>` con proprietà CSS personalizzate
`$_menuSearch`	bool	Mostra la barra di ricerca
`$_menuItems`	array	Voci di navigazione (`key`, `label`, `url`, `enabled`, `templates`)

Locale

Variabile	Tipo	Descrizione
`$_locale`	string	Codice locale corrente (es. `'en'`)
`$_direction`	string	`'ltr'` o `'rtl'`
`$_isRtl`	bool	Lingua da destra a sinistra
`$_availableLangs`	array	Lingue disponibili
`$_langPrefix`	string	Prefisso URL (es. `'/fr'` o `''`)

Impostazioni scheda video

Variabile	Tipo	Descrizione
`$_cardShowDuration`	bool	Mostra il badge durata
`$_cardShowTitle`	bool	Mostra il titolo del video
`$_cardMetaLeft`	string	Meta sinistra: `'views'`, `'likes'`, `'time'`, `'none'`
`$_cardMetaRight`	string	Meta destra (stesse opzioni)
`$_cardGridGap`	int	Spaziatura della griglia in pixel
`$_cardBorderRadius`	int	Raggio del bordo della scheda in pixel
`$_cardThumbnailHover`	bool	Effetto hover sulla miniatura
`$_cardTitleLines`	int	Righe del titolo (1 o 2)

Impostazioni pagina di visualizzazione

Variabile	Tipo	Descrizione
`$_watchShowViews`	bool	Mostra il contatore visualizzazioni
`$_watchShowDuration`	bool	Mostra la durata
`$_watchShowDate`	bool	Mostra la data di pubblicazione
`$_watchShowLikes`	bool	Mostra mi piace / non mi piace
`$_watchShowFavorites`	bool	Mostra il pulsante preferiti
`$_watchShowPornstars`	bool	Mostra i performer
`$_watchShowChannels`	bool	Mostra i canali
`$_watchShowCategories`	bool	Mostra le categorie
`$_watchShowTags`	bool	Mostra i tag
`$_commentsEnabled`	bool	Commenti abilitati

Queste sono impostazioni, non magia. Ogni valore $_card* e $_watch* proviene direttamente dalla schermata Aspetto nell'amministrazione, così i proprietari del sito possono ridisegnare il tuo tema senza toccare il codice — purché tu legga queste variabili invece di inserire valori fissi.

Variabili specifiche per template

Oltre alle globali, ogni template riceve i propri dati.

home.php

Variabile	Tipo
`$videos`	array — righe video
`$pagination`	oggetto Pagination
`$sort`	string — chiave di ordinamento corrente

video.php

Variabile	Tipo
`$video`	array — video completo con categorie, tag, performer, canali
`$categories`, `$tags`, `$performers`	array
`$comments`	array
`$similar`	array — video simili
`$recommended`	array — video consigliati
`$userVote`	string\\|null — `'like'`, `'dislike'` o null
`$isFavorited`	bool

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

Variabile	Tipo
`$category` / `$tag` / `$performer` / `$channel`	array — l'entità
`$videos`	array — righe video
`$pagination`	oggetto Pagination
`$sort`	string

Template di elenco

Template	Variabili principali
`categories.php`	`$categories` — ciascuna ha `video_count`; con CTR attivo, `best_video_thumbnail`
`performers.php`	`$performers` — `video_count`; con CTR attivo, `best_video_thumbnail`, `total_ctr`, ordinati per CTR; `$pagination`
`channels.php`	Stessa struttura dei performer
`search.php`	`$query`, `$videos`, `$pagination`

Classi helper

Questi helper statici sono disponibili in ogni template.

Classe	Metodi principali
`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)`	Helper di traduzione
`url($path)`	Scorciatoia per `Router::url($path)`

Il flusso di rendering

Il controller chiama il renderer. ThemeRenderer::render('home', ['videos' => $videos, …]).
Le variabili globali vengono iniettate. Vengono aggiunte le variabili con prefisso $_ per sito, aspetto, locale e impostazioni scheda/visualizzazione.
I plugin possono modificare i dati. Viene eseguito HookSystem::applyFilter('theme.template_data', $data, $templateName).
Il template viene renderizzato. Il tuo file template viene inserito in un buffer come $content.
Il layout viene caricato. layout.php riceve $content più tutte le variabili.
Le impression vengono inviate. ImpressionTracker::flush() invia l'aggiornamento batch delle impression (CTR).
Il cron viene eseguito. CronManager::run() esegue eventuali attività pianificate in scadenza.

Requisiti di layout.php

Il file layout.php di un tema deve fare tutto quanto segue:

Produrre l'intera struttura HTML (<!DOCTYPE html> … </html>).
Includere <?= ThemeRenderer::renderCSS() ?> in <head>.
Includere <?= $_colorOverrides ?> in <head>.
Stampare $content all'interno di <main>.
Includere <?= ThemeRenderer::renderJS() ?> prima di </body>.
Chiamare <?php ImpressionTracker::flush(); ?> prima di </body> (per CTR).
Chiamare <?php HookSystem::doAction('head.meta'); ?> in <head>.
Chiamare <?php HookSystem::doAction('footer.scripts'); ?> prima di </body>.

Fallback del template

Se un template è assente dal tema attivo, TubePress ricorre al tema Simply incluso. Un tema personalizzato deve quindi sovrascrivere solo i template che vuole effettivamente modificare — inizia da un template e aggiungi man mano.

Passaggi successivi

Sviluppo del temaCostruisci un tema da zero, passo dopo passo. Hook & pluginAzioni e filtri a cui puoi collegarti. ArchitetturaCome si incastra l'intero CMS.

Ancora bloccato?

Apri un ticket dalla tua dashboard e il nostro team ti aiuterà.

Prova la demo live → Scarica TubePress →