Tema geliştirme

Bir TubePress teması, isteğe bağlı varlıklar ve yardımcı işlevler içeren PHP şablonlarından oluşan bir klasördür. Görünüm ve tema düzenleyicisi yeterli olmadığında ve işaretleme üzerinde tam kontrol istediğinizde özel bir tema kullanın. Bu sayfa yapım kılavuzudur; değişkenlerin ve yardımcıların kapsamlı listesi için tema API referansını yanınızda açık tutun.

Temel kural şudur: Sabit kodlama yerine TubePress'in eklediği ayarları okuyun. Eğer $_ önekli değişkenlere uyarsanız, temanız tıpkı dahili Simply teması gibi yönetim panelinden tam olarak yapılandırılabilir kalır.

Tema yapısı

Temalar themes/{slug}/ altında bulunur. Yalnızca theme.json ve templates/layout.php zorunludur — diğer her şey isteğe bağlıdır ve Simply'e geri döner.

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

Bu manifest gereklidir. Temanın meta verilerini, isteğe bağlı bir varsayılan renk setini ve keyfi settings değerlerini taşır. name, version ve author değerleri /admin/themes bölümünde görünür.

{
    "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

Bu dosya başlangıçta otomatik olarak yüklenir. Stil sayfanızı ve komut dosyanızı sıraya eklemek ve şablonlarınızın çağırdığı yardımcı işlevleri tanımlamak için kullanın. Tarayıcıların her zaman en son düzenlemenizi alması için varlıkları filemtime() sorgu dizesiyle sıraya ekleyin; ikinci argüman yükleme önceliğidir (düşük değer daha erken yüklenir).

<?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, tam olarak bu tür yardımcıyı — simplyVideoCard() — simplyPagination() ve simplySortTabs() ile birlikte tanımlar. ImpressionTracker::collect() çağrısı, CTR sıralamasını besleyen şeydir; toplu yazma işlemi daha sonra layout.php içinde temizlenir.

Şablonlar & render akışı

Bir kontrolör veriyi ThemeRenderer::render($template, $data)'ya aktarır ve renderer oradan devralır. Sırayı anlamak, neyin nerede kullanılabilir olduğunu bilmenize yardımcı olur.

1. Kontrolör render eder. Örn. ThemeRenderer::render('home', ['videos' => $videos]).
2. Globaller eklenir. $_ önekli site, görünüm, yerel ayar ve kart/izleme değişkenleri eklenir.
3. Eklentiler veriyi ayarlar. theme.template_data filtresi çalışır ve ($data, $templateName) parametrelerini alır.
4. Şablonunuz tamponlanır. Şablon dosyası $content'e kaydedilir.
5. Layout yüklenir. layout.php, $content ve tüm değişkenleri alır ve tam HTML kabuğunu çıktılar.
6. İzlenimler temizlenir. ImpressionTracker::flush(), </body>'den önce toplu CTR güncellemesini yazar.
7. Cron çalışır. CronManager::run(), zamanı gelen planlanmış görevleri yürütür.

layout.php dosyanız kabuktan sorumludur: ThemeRenderer::renderCSS() ve $_colorOverrides'ı <head> içine ekleyin, $content'i echo edin, ardından </body>'den önce ThemeRenderer::renderJS() ve ImpressionTracker::flush() çağırın. Tema API'si, sekiz maddelik tam kontrol listesini içerir.

Global değişkenler & yardımcılar

Her şablon, global $_ değişkenlerini ve kendi verilerini alır. Tema API referansı bunların tümünü belgeler; bunlar en çok başvuracağınız olanlardır.

Şablon geri dönüşü

Etkin tema bir şablondan yoksunsa, TubePress bunun yerine Simply'nin kopyasını render eder. Bu, yalnızca değiştirmek istediğiniz şeyi geçersiz kıldığınız anlamına gelir: Tek bir şablonu — örneğin home.php — temanıza kopyalamaya başlayın ve üzerine almaya hazır olana kadar diğer her şeyin Simply'den miras almasına izin verin. Bir tema bir dosyadan oluşabilir veya elli dosyadan oluşabilir.

Tema kancaları

Şablonların ötesinde, küçük bir kanca noktaları seti, sayfayı çatallamadan genişletmenize (ve eklentilere) olanak tanır. Eylemler gönder-ve-unut mantığıyla çalışır; filtreler döndürdüğünüz bir değeri dönüştürür.

// 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;
    });

Bilmeye değer iki filtre daha vardır: render'dan önce veri dizisini ayarlamak için theme.template_data ve bir <style> dizesi eklemek için head.css — Simply, ızgara boşluğunu ve yarıçapını CSS değişkenleri olarak yayınlamak için sonuncuyu kullanır. Daha geniş eylem/filtre kataloğu için hooks & plugins bölümüne bakın.

Sonraki adımlar