開発者リファレンス
テーマ API リファレンス
TubePress テーマ API リファレンス。チューブサイトのテーマを作成・カスタマイズする際に利用できる、すべてのグローバルテンプレート変数、ヘルパー関数、クラスを網羅します。
このページは、テーマが使用できるすべてのものの完全なリファレンスです：すべてのテンプレートに注入されるグローバル変数、各テンプレート固有の変数、そしてテーマコードで利用できるヘルパークラスを含みます。テーマを構築またはカスタマイズしている場合は、テーマ開発と並べてこのページを開いておいてください。
すべてのテンプレートは ThemeRenderer::render($template, $data) によってレンダリングされます。レンダラーはグローバルな $_ プレフィックス変数のセットを注入し、テンプレート固有の $data をマージし、theme.template_data フィルターを実行し、テンプレートを $content にバッファリングしてから layout.php を読み込みます。
グローバル変数
これらはすべてのテンプレートおよび layout.php で利用可能です。
サイト
| 変数 | 型 | 説明 |
|---|
$_template | string | 現在のテンプレート名（例：'home'、'video'） |
$_siteName | string | 設定のサイト名 |
$_siteDescription | string | サイトの説明 |
$_siteUrl | string | サイトURL |
$_videosPerRow | int | グリッド列数（4、5 または 6） |
$_user | array\|null | ログイン中のユーザー、または null |
$_footerPages | array | フッター用にフラグが立てられた静的ページ |
$_registrationEnabled | bool | 登録の切り替え |
$_ctrEnabled | bool | CTR ランキングの切り替え |
外観
| 変数 | 型 | 説明 |
|---|
$_siteLogo | string | ロゴファイル名（/uploads/branding/ 内） |
$_siteFavicon | string | ファビコンファイル名 |
$_siteBackground | string | 背景画像ファイル名 |
$_siteBackgroundMode | string | 'cover'、'contain' または 'repeat' |
$_colorOverrides | string | <style> ブロック（CSS カスタムプロパティ） |
$_menuSearch | bool | 検索バーを表示する |
$_menuItems | array | ナビゲーション項目（key、label、url、enabled、templates） |
ロケール
| 変数 | 型 | 説明 |
|---|
$_locale | string | 現在のロケールコード（例：'en'） |
$_direction | string | 'ltr' または 'rtl' |
$_isRtl | bool | 右から左の言語（RTL） |
$_availableLangs | array | 利用可能な言語 |
$_langPrefix | string | URL プレフィックス（例：'/fr' または ''） |
動画カード設定
| 変数 | 型 | 説明 |
|---|
$_cardShowDuration | bool | 再生時間バッジを表示する |
$_cardShowTitle | bool | 動画タイトルを表示する |
$_cardMetaLeft | string | 左メタ：'views'、'likes'、'time'、'none' |
$_cardMetaRight | string | 右メタ（同じオプション） |
$_cardGridGap | int | グリッドのギャップ（ピクセル） |
$_cardBorderRadius | int | カードの角丸半径（ピクセル） |
$_cardThumbnailHover | bool | サムネイルのホバー効果 |
$_cardTitleLines | int | タイトルの行数（1 または 2） |
視聴ページ設定
| 変数 | 型 | 説明 |
|---|
$_watchShowViews | bool | 再生回数を表示する |
$_watchShowDuration | bool | 再生時間を表示する |
$_watchShowDate | bool | 公開日を表示する |
$_watchShowLikes | bool | いいね / 嫌いを表示する |
$_watchShowFavorites | bool | お気に入りボタンを表示する |
$_watchShowPornstars | bool | 出演者を表示する |
$_watchShowChannels | bool | チャンネルを表示する |
$_watchShowCategories | bool | カテゴリを表示する |
$_watchShowTags | bool | タグを表示する |
$_commentsEnabled | bool | コメントが有効 |
これらは設定であり、魔法ではありません。 すべての
$_card* および
$_watch* の値は管理者の
外観設定画面から直接取得されます。そのため、ハードコーディングせずにこれらの変数を読み込む限り、サイトオーナーはコードに触れずにテーマのスタイルを変更できます。
テンプレート固有の変数
グローバル変数に加えて、各テンプレートは独自のデータを受け取ります。
home.php
| 変数 | 型 |
|---|
$videos | array — 動画行 |
$pagination | Pagination オブジェクト |
$sort | string — 現在のソートキー |
video.php
| 変数 | 型 |
|---|
$video | array — カテゴリ、タグ、出演者、チャンネルを含む完全な動画データ |
$categories、$tags、$performers | array |
$comments | array |
$similar | array — 類似動画 |
$recommended | array — おすすめ動画 |
$userVote | string\|null — 'like'、'dislike' または null |
$isFavorited | bool |
category.php / tag.php / performer.php / channel.php
| 変数 | 型 |
|---|
$category / $tag / $performer / $channel | array — エンティティ |
$videos | array — 動画行 |
$pagination | Pagination オブジェクト |
$sort | string |
一覧テンプレート
| テンプレート | 主な変数 |
|---|
categories.php | $categories — 各エントリに video_count があり、CTR が有効な場合は best_video_thumbnail も含む |
performers.php | $performers — video_count；CTR が有効な場合は best_video_thumbnail、total_ctr が含まれ、CTR 順にソートされる；$pagination |
channels.php | performers と同じ構造 |
search.php | $query、$videos、$pagination |
ヘルパークラス
これらの静的ヘルパーはすべてのテンプレートで利用できます。
| クラス | 主なメソッド |
|---|
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) | 翻訳ヘルパー |
url($path) | Router::url($path) のショートカット |
レンダリングフロー
- コントローラーがレンダラーを呼び出します。
ThemeRenderer::render('home', ['videos' => $videos, …])。
- グローバル変数が注入されます。
$_ プレフィックスのサイト、外観、ロケール、カード/ウォッチ変数が追加されます。
- プラグインはデータを変更できます。
HookSystem::applyFilter('theme.template_data', $data, $templateName) が実行されます。
- テンプレートがレンダリングされます。 テンプレートファイルが
$content にバッファリングされます。
- レイアウトが読み込まれます。
layout.php が $content とすべての変数を受け取ります。
- インプレッションがフラッシュされます。
ImpressionTracker::flush() がバッチ処理されたインプレッション更新（CTR）を送信します。
- Cron が実行されます。
CronManager::run() が期限となったスケジュールタスクを実行します。
layout.php の要件
テーマの layout.php は以下のすべてを実行する必要があります：
- 完全な HTML シェルを出力する（
<!DOCTYPE html> … </html>）。
<head> 内に <?= ThemeRenderer::renderCSS() ?> を含める。<head> 内に <?= $_colorOverrides ?> を含める。<main> 内で $content を出力する。</body> の前に <?= ThemeRenderer::renderJS() ?> を含める。</body> の前で <?php ImpressionTracker::flush(); ?> を呼び出す（CTR 用）。<head> 内で <?php HookSystem::doAction('head.meta'); ?> を呼び出す。</body> の前で <?php HookSystem::doAction('footer.scripts'); ?> を呼び出す。
テンプレートフォールバック
アクティブなテーマにテンプレートが存在しない場合、TubePress はバンドルされた Simply テーマにフォールバックします。したがって、カスタムテーマは実際に変更したいテンプレートのみを上書きすれば十分です — 1つのテンプレートから始めて徐々に拡張していきましょう。
次のステップ
