Developer reference

Theme API reference

TubePress Theme API reference: every global template variable, helper function and class available when building or customising a tube site theme.

This page is the complete reference for everything a theme can use: the global variables injected into every template, the variables specific to each template, and the helper classes available in theme code. If you are building or customising a theme, keep this page open alongside Theme development.

Every template is rendered by ThemeRenderer::render($template, $data). The renderer injects a set of global $_-prefixed variables, merges in the template-specific $data, runs the theme.template_data filter, buffers your template into $content, then loads layout.php.

Global variables

These are available in every template and in layout.php.

Site

Variable	Type	Description
`$_template`	string	Current template name (e.g. `'home'`, `'video'`)
`$_siteName`	string	Site name from settings
`$_siteDescription`	string	Site description
`$_siteUrl`	string	Site URL
`$_videosPerRow`	int	Grid columns (4, 5 or 6)
`$_user`	array\\|null	Logged-in user, or null
`$_footerPages`	array	Static pages flagged for the footer
`$_registrationEnabled`	bool	Registration toggle
`$_ctrEnabled`	bool	CTR ranking toggle

Appearance

Variable	Type	Description
`$_siteLogo`	string	Logo filename (in `/uploads/branding/`)
`$_siteFavicon`	string	Favicon filename
`$_siteBackground`	string	Background image filename
`$_siteBackgroundMode`	string	`'cover'`, `'contain'` or `'repeat'`
`$_colorOverrides`	string	`<style>` block with CSS custom properties
`$_menuSearch`	bool	Show the search bar
`$_menuItems`	array	Navigation items (`key`, `label`, `url`, `enabled`, `templates`)

Locale

Variable	Type	Description
`$_locale`	string	Current locale code (e.g. `'en'`)
`$_direction`	string	`'ltr'` or `'rtl'`
`$_isRtl`	bool	Right-to-left language
`$_availableLangs`	array	Available languages
`$_langPrefix`	string	URL prefix (e.g. `'/fr'` or `''`)

Video card settings

Variable	Type	Description
`$_cardShowDuration`	bool	Show the duration badge
`$_cardShowTitle`	bool	Show the video title
`$_cardMetaLeft`	string	Left meta: `'views'`, `'likes'`, `'time'`, `'none'`
`$_cardMetaRight`	string	Right meta (same options)
`$_cardGridGap`	int	Grid gap in pixels
`$_cardBorderRadius`	int	Card border radius in pixels
`$_cardThumbnailHover`	bool	Thumbnail hover effect
`$_cardTitleLines`	int	Title lines (1 or 2)

Watch page settings

Variable	Type	Description
`$_watchShowViews`	bool	Show the view count
`$_watchShowDuration`	bool	Show the duration
`$_watchShowDate`	bool	Show the publish date
`$_watchShowLikes`	bool	Show like / dislike
`$_watchShowFavorites`	bool	Show the favorite button
`$_watchShowPornstars`	bool	Show performers
`$_watchShowChannels`	bool	Show channels
`$_watchShowCategories`	bool	Show categories
`$_watchShowTags`	bool	Show tags
`$_commentsEnabled`	bool	Comments enabled

These are settings, not magic. Every $_card* and $_watch* value comes straight from the admin Appearance screen, so site owners can re-style your theme without touching code — as long as you read these variables instead of hard-coding.

Template-specific variables

In addition to the globals, each template receives its own data.

home.php

Variable	Type
`$videos`	array — video rows
`$pagination`	Pagination object
`$sort`	string — current sort key

video.php

Variable	Type
`$video`	array — full video with categories, tags, performers, channels
`$categories`, `$tags`, `$performers`	array
`$comments`	array
`$similar`	array — similar videos
`$recommended`	array — recommended videos
`$userVote`	string\\|null — `'like'`, `'dislike'` or null
`$isFavorited`	bool

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

Variable	Type
`$category` / `$tag` / `$performer` / `$channel`	array — the entity
`$videos`	array — video rows
`$pagination`	Pagination object
`$sort`	string

Listing templates

Template	Notable variables
`categories.php`	`$categories` — each has `video_count`; with CTR on, `best_video_thumbnail`
`performers.php`	`$performers` — `video_count`; with CTR on, `best_video_thumbnail`, `total_ctr`, sorted by CTR; `$pagination`
`channels.php`	Same shape as performers
`search.php`	`$query`, `$videos`, `$pagination`

Helper classes

These static helpers are available in every template.

Class	Key methods
`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)`	Translation helper
`url($path)`	Shortcut for `Router::url($path)`

The rendering flow

Controller calls the renderer. ThemeRenderer::render('home', ['videos' => $videos, …]).
Globals are injected. The $_-prefixed site, appearance, locale and card/watch variables are added.
Plugins can modify the data. HookSystem::applyFilter('theme.template_data', $data, $templateName) runs.
The template renders. Your template file is buffered into $content.
The layout loads. layout.php receives $content plus all variables.
Impressions flush. ImpressionTracker::flush() sends the batched impression update (CTR).
Cron runs. CronManager::run() executes any due scheduled tasks.

layout.php requirements

A theme's layout.php must do all of the following:

Output the full HTML shell (<!DOCTYPE html> … </html>).
Include <?= ThemeRenderer::renderCSS() ?> in <head>.
Include <?= $_colorOverrides ?> in <head>.
Echo $content inside <main>.
Include <?= ThemeRenderer::renderJS() ?> before </body>.
Call <?php ImpressionTracker::flush(); ?> before </body> (for CTR).
Call <?php HookSystem::doAction('head.meta'); ?> in <head>.
Call <?php HookSystem::doAction('footer.scripts'); ?> before </body>.

Template fallback

If a template is missing from the active theme, TubePress falls back to the bundled Simply theme. A custom theme therefore only needs to override the templates it actually wants to change — start from one template and grow from there.

Next steps

Theme developmentBuild a theme from scratch, step by step. Hooks & pluginsActions and filters you can hook into. ArchitectureHow the whole CMS fits together.

Still stuck?

Open a ticket from your dashboard and our team will help you out.

Try the live demo → Download TubePress →