Pengembangan tema

Tema TubePress adalah folder berisi template PHP beserta aset dan fungsi pembantu opsional. Gunakan tema kustom ketika Tampilan dan editor tema tidak mencukupi dan Anda ingin kendali penuh atas markup. Halaman ini adalah panduan pembangunan; buka referensi API tema di sampingnya untuk daftar lengkap variabel dan pembantu.

Aturan emas yang berlaku: baca pengaturan yang disuntikkan TubePress daripada melakukan hard-coding. Jika Anda mengikuti variabel berprefix $_, tema Anda tetap dapat dikonfigurasi sepenuhnya dari admin, persis seperti tema Simply bawaan.

Struktur tema

Tema berada di bawah themes/{slug}/. Hanya theme.json dan templates/layout.php yang benar-benar diperlukan — selebihnya opsional dan menggunakan fallback ke Simply.

themes/aurora/
├── theme.json            Required — metadata
├── functions.php         Enqueue assets, helper functions
├── assets/
│   ├── css/style.css
│   └── js/app.js
└── templates/
    ├── layout.php        Required — the HTML shell
    ├── home.php          Homepage
    ├── video.php         Watch page
    ├── category.php      …tag/performer/channel (+ plurals)
    ├── search.php        Search results
    ├── page.php          Static page
    ├── favorites.php     User favourites
    ├── history.php       Watch history
    ├── 404.php           Not found
    ├── auth/             login, register, profile
    └── partials/
        └── video-card.php  Reusable card partial

theme.json

Manifes ini wajib ada. Manifes ini memuat metadata tema, set warna default opsional, dan settings arbitrer. name, version, dan author ditampilkan di /admin/themes.

{
    "name": "Aurora",
    "description": "A custom theme for TubePress",
    "version": "1.0.0",
    "author": "Your Name",
    "screenshot": "screenshot.png",
    "colors": {
        "primary": "#2563eb",
        "secondary": "#7c3aed",
        "background": "#ffffff",
        "text": "#1e293b"
    },
    "settings": {
        "videos_per_row": 4
    }
}

functions.php

File ini dimuat secara otomatis saat startup. Gunakan untuk mengantrekan stylesheet dan skrip Anda, serta mendefinisikan fungsi pembantu yang dipanggil oleh template Anda. Antrekan aset dengan query string filemtime() agar browser selalu memuat perubahan terbaru Anda; argumen kedua adalah prioritas pemuatan (angka lebih kecil dimuat lebih awal).

<?php
declare(strict_types=1);

// filemtime() busts the cache on every edit.
$cssVer = @filemtime(ThemeManager::themePath()
    . '/assets/css/style.css') ?: time();
$jsVer  = @filemtime(ThemeManager::themePath()
    . '/assets/js/app.js') ?: time();

ThemeRenderer::enqueueCSS(
    ThemeManager::assetUrl('css/style.css') . '?v=' . $cssVer, 1);
ThemeRenderer::enqueueJS(
    ThemeManager::assetUrl('js/app.js') . '?v=' . $jsVer, 1);

// A reusable video-card helper, called from listing templates.
function auroraVideoCard(array $video): string
{
    // Record an impression so the CTR system can rank this card.
    ImpressionTracker::collect((int) $video['id']);

    // Let a plugin replace the card entirely if it wants to.
    $card = HookSystem::applyFilter('video.card.html', '', $video);
    if ($card !== '') {
        return $card;
    }

    ob_start();
    require ThemeManager::templatePath('partials/video-card');
    return ob_get_clean();
}

Simply mendefinisikan pembantu seperti ini — simplyVideoCard() — bersama simplyPagination() dan simplySortTabs(). Pemanggilan ImpressionTracker::collect() inilah yang mengumpan peringkat CTR; penulisan batch di-flush nanti di layout.php.

Template & alur rendering

Sebuah controller menyerahkan data ke ThemeRenderer::render($template, $data), dan renderer mengambil alih dari sana. Memahami urutannya membantu Anda mengetahui apa yang tersedia di mana.

1. Controller melakukan rendering. mis. ThemeRenderer::render('home', ['videos' => $videos]).
2. Globals disuntikkan. Variabel situs, tampilan, lokal, dan kartu/tonton berprefix $_ ditambahkan.
3. Plugin menyesuaikan data. Filter theme.template_data dijalankan, menerima ($data, $templateName).
4. Template Anda di-buffer. File template ditangkap ke dalam $content.
5. Layout dimuat. layout.php menerima $content beserta semua variabel dan menghasilkan shell HTML lengkap.
6. Impresi di-flush. ImpressionTracker::flush() menulis pembaruan CTR batch sebelum </body>.
7. Cron dijalankan. CronManager::run() menjalankan tugas terjadwal yang sudah jatuh tempo.

File layout.php Anda bertanggung jawab atas shell: sertakan ThemeRenderer::renderCSS() dan $_colorOverrides di <head>, echo $content, lalu panggil ThemeRenderer::renderJS() dan ImpressionTracker::flush() sebelum </body>. API tema mencantumkan daftar periksa delapan poin lengkap.

Variabel global & pembantu

Setiap template menerima variabel global $_ beserta datanya sendiri. Referensi API tema mendokumentasikan semuanya; berikut adalah yang paling sering Anda gunakan.

Fallback template

Jika tema aktif tidak memiliki template, TubePress akan merender salinan Simply sebagai gantinya. Artinya Anda hanya perlu menimpa apa yang ingin diubah: mulailah dengan menyalin satu template — misalnya home.php — ke dalam tema Anda, dan biarkan yang lain mewarisi dari Simply hingga Anda siap mengambil alihnya. Sebuah tema bisa terdiri dari satu file atau lima puluh.

Hook tema

Di luar template, sekumpulan kecil titik hook memungkinkan Anda (dan plugin) memperluas halaman tanpa melakukan fork. Action bersifat fire-and-forget; filter mengubah nilai yang Anda kembalikan.

// An action — fire and forget, inside <head>.
HookSystem::doAction('head.meta');

// A filter — return '' to keep the default card.
HookSystem::addFilter('video.card.html',
    function (string $html, array $video): string {
        return $html;
    });

Dua filter lagi yang perlu diketahui: theme.template_data untuk menyesuaikan array data sebelum render, dan head.css untuk menambahkan string <style> — Simply menggunakan yang terakhir untuk menerbitkan celah grid dan radius-nya sebagai variabel CSS. Untuk katalog action/filter yang lebih luas, lihat hook & plugin.

Langkah selanjutnya