Dokumentacja dla deweloperów

Dokumentacja API motywów

Dokumentacja API motywów TubePress: każda globalna zmienna szablonu, funkcja pomocnicza i klasa dostępna podczas budowania lub dostosowywania motywu strony tube.

Ta strona stanowi pełną dokumentację wszystkiego, czego motyw może używać: zmiennych globalnych wstrzykiwanych do każdego szablonu, zmiennych specyficznych dla poszczególnych szablonów oraz klas pomocniczych dostępnych w kodzie motywu. Jeśli tworzysz lub dostosowujesz motyw, trzymaj tę stronę otwartą obok Tworzenia motywów.

Każdy szablon jest renderowany przez ThemeRenderer::render($template, $data). Renderer wstrzykuje zestaw globalnych zmiennych z prefiksem $_, scala dane specyficzne dla szablonu $data, uruchamia filtr theme.template_data, buforuje szablon do zmiennej $content, a następnie ładuje layout.php.

Zmienne globalne

Są dostępne w każdym szablonie oraz w layout.php.

Witryna

Zmienna	Typ	Opis
`$_template`	string	Nazwa bieżącego szablonu (np. `'home'`, `'video'`)
`$_siteName`	string	Nazwa witryny z ustawień
`$_siteDescription`	string	Opis witryny
`$_siteUrl`	string	URL witryny
`$_videosPerRow`	int	Kolumny siatki (4, 5 lub 6)
`$_user`	array\\|null	Zalogowany użytkownik lub null
`$_footerPages`	array	Strony statyczne oznaczone dla stopki
`$_registrationEnabled`	bool	Przełącznik rejestracji
`$_ctrEnabled`	bool	Przełącznik rankingu CTR

Wygląd

Zmienna	Typ	Opis
`$_siteLogo`	string	Nazwa pliku logo (w `/uploads/branding/`)
`$_siteFavicon`	string	Nazwa pliku favicon
`$_siteBackground`	string	Nazwa pliku obrazu tła
`$_siteBackgroundMode`	string	`'cover'`, `'contain'` lub `'repeat'`
`$_colorOverrides`	string	Blok `<style>` z niestandardowymi właściwościami CSS
`$_menuSearch`	bool	Pokaż pasek wyszukiwania
`$_menuItems`	array	Elementy nawigacji (`key`, `label`, `url`, `enabled`, `templates`)

Ustawienia lokalne

Zmienna	Typ	Opis
`$_locale`	string	Kod bieżących ustawień lokalnych (np. `'en'`)
`$_direction`	string	`'ltr'` lub `'rtl'`
`$_isRtl`	bool	Język pisany od prawej do lewej
`$_availableLangs`	array	Dostępne języki
`$_langPrefix`	string	Prefiks URL (np. `'/fr'` lub `''`)

Ustawienia karty wideo

Zmienna	Typ	Opis
`$_cardShowDuration`	bool	Pokaż znacznik czasu trwania
`$_cardShowTitle`	bool	Pokaż tytuł wideo
`$_cardMetaLeft`	string	Lewe meta: `'views'`, `'likes'`, `'time'`, `'none'`
`$_cardMetaRight`	string	Prawe meta (te same opcje)
`$_cardGridGap`	int	Odstęp siatki w pikselach
`$_cardBorderRadius`	int	Zaokrąglenie narożników karty w pikselach
`$_cardThumbnailHover`	bool	Efekt najechania kursorem na miniaturę
`$_cardTitleLines`	int	Linie tytułu (1 lub 2)

Ustawienia strony odtwarzania

Zmienna	Typ	Opis
`$_watchShowViews`	bool	Pokaż liczbę wyświetleń
`$_watchShowDuration`	bool	Pokaż czas trwania
`$_watchShowDate`	bool	Pokaż datę publikacji
`$_watchShowLikes`	bool	Pokaż polubienie / niepolubienie
`$_watchShowFavorites`	bool	Pokaż przycisk ulubionych
`$_watchShowPornstars`	bool	Pokaż wykonawców
`$_watchShowChannels`	bool	Pokaż kanały
`$_watchShowCategories`	bool	Pokaż kategorie
`$_watchShowTags`	bool	Pokaż tagi
`$_commentsEnabled`	bool	Komentarze włączone

To są ustawienia, nie magia. Każda wartość $_card* i $_watch* pochodzi bezpośrednio z ekranu Wygląd w panelu administracyjnym, dzięki czemu właściciele witryn mogą zmieniać styl motywu bez dotykania kodu — o ile odczytujesz te zmienne zamiast wpisywać wartości na stałe.

Zmienne specyficzne dla szablonu

Oprócz zmiennych globalnych każdy szablon otrzymuje własne dane.

home.php

Zmienna	Typ
`$videos`	array — wiersze wideo
`$pagination`	obiekt Pagination
`$sort`	string — bieżący klucz sortowania

video.php

Zmienna	Typ
`$video`	array — pełne wideo z kategoriami, tagami, wykonawcami i kanałami
`$categories`, `$tags`, `$performers`	array
`$comments`	array
`$similar`	array — podobne wideo
`$recommended`	array — polecane wideo
`$userVote`	string\\|null — `'like'`, `'dislike'` lub null
`$isFavorited`	bool

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

Zmienna	Typ
`$category` / `$tag` / `$performer` / `$channel`	array — encja
`$videos`	array — wiersze wideo
`$pagination`	obiekt Pagination
`$sort`	string

Szablony listowania

Szablon	Istotne zmienne
`categories.php`	`$categories` — każda ma `video_count`; przy włączonym CTR, `best_video_thumbnail`
`performers.php`	`$performers` — `video_count`; przy włączonym CTR, `best_video_thumbnail`, `total_ctr`, posortowane wg CTR; `$pagination`
`channels.php`	Ta sama struktura co wykonawcy
`search.php`	`$query`, `$videos`, `$pagination`

Klasy pomocnicze

Te statyczne klasy pomocnicze są dostępne w każdym szablonie.

Klasa	Kluczowe metody
`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)`	Pomocnik tłumaczeń
`url($path)`	Skrót dla `Router::url($path)`

Przebieg renderowania

Kontroler wywołuje renderer. ThemeRenderer::render('home', ['videos' => $videos, …]).
Zmienne globalne są wstrzykiwane. Dodawane są zmienne witryny, wyglądu, ustawień lokalnych oraz kart/odtwarzania z prefiksem $_.
Wtyczki mogą modyfikować dane. Uruchamia się HookSystem::applyFilter('theme.template_data', $data, $templateName).
Szablon jest renderowany. Plik szablonu jest buforowany do $content.
Układ jest ładowany. layout.php otrzymuje $content oraz wszystkie zmienne.
Wyświetlenia są opróżniane. ImpressionTracker::flush() wysyła zbiorcze aktualizacje wyświetleń (CTR).
Cron jest uruchamiany. CronManager::run() wykonuje wszystkie zaplanowane zadania.

Wymagania layout.php

Plik layout.php motywu musi wykonać wszystkie poniższe czynności:

Wyprowadzić pełną powłokę HTML (<!DOCTYPE html> … </html>).
Dołączyć <?= ThemeRenderer::renderCSS() ?> w <head>.
Dołączyć <?= $_colorOverrides ?> w <head>.
Wyświetlić $content wewnątrz <main>.
Dołączyć <?= ThemeRenderer::renderJS() ?> przed </body>.
Wywołać <?php ImpressionTracker::flush(); ?> przed </body> (dla CTR).
Wywołać <?php HookSystem::doAction('head.meta'); ?> w <head>.
Wywołać <?php HookSystem::doAction('footer.scripts'); ?> przed </body>.

Zasoby zastępcze szablonu

Jeśli szablon nie istnieje w aktywnym motywie, TubePress używa jako zastępczego wbudowanego motywu Simply. Niestandardowy motyw musi zatem nadpisywać jedynie te szablony, które faktycznie chce zmienić — zacznij od jednego szablonu i rozwijaj go stopniowo.

Następne kroki

Tworzenie motywówZbuduj motyw od podstaw, krok po kroku. Hooki i wtyczkiAkcje i filtry, do których możesz się podpiąć. ArchitekturaJak cały CMS jest ze sobą powiązany.

Nadal masz problem?

Otwórz zgłoszenie z poziomu panelu, a nasz zespół Ci pomoże.

Wypróbuj demo na żywo → Pobierz TubePress →