थीम डेवलपमेंट

TubePress थीम PHP टेम्पलेट्स का एक फ़ोल्डर है जिसमें वैकल्पिक एसेट और सहायक फ़ंक्शन होते हैं। कस्टम थीम का उपयोग तब करें जब Appearance और थीम एडिटर पर्याप्त न हों और आप मार्कअप पर पूर्ण नियंत्रण चाहते हों। यह पेज बिल्ड गाइड है; चरों और सहायकों की संपूर्ण सूची के लिए थीम API संदर्भ को साथ में खुला रखें।

पूरे विकास में सबसे महत्वपूर्ण नियम: TubePress द्वारा इंजेक्ट की गई सेटिंग्स को पढ़ें, न कि हार्ड-कोड करें। यदि आप $_-प्रीफ़िक्स्ड चरों का उपयोग करते हैं, तो आपकी थीम एडमिन से पूरी तरह कॉन्फ़िगर करने योग्य रहती है, ठीक बंडल की गई Simply थीम की तरह।

थीम संरचना

themes/{slug}/ के अंतर्गत थीम रखी जाती हैं। केवल theme.json और templates/layout.php अनिवार्य हैं — बाकी सब कुछ वैकल्पिक है और 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

यह मेनिफ़ेस्ट अनिवार्य है। इसमें थीम का मेटाडेटा, एक वैकल्पिक डिफ़ॉल्ट रंग सेट और मनमाने settings होते हैं। name, version और author /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

यह फ़ाइल बूट पर स्वचालित रूप से लोड होती है। इसका उपयोग अपनी स्टाइलशीट और स्क्रिप्ट को एनक्यू करने और अपने टेम्पलेट्स द्वारा कॉल किए जाने वाले सहायक फ़ंक्शन परिभाषित करने के लिए करें। filemtime() क्वेरी स्ट्रिंग के साथ एसेट एनक्यू करें ताकि ब्राउज़र हमेशा आपका नवीनतम संपादन उठाएं; दूसरा तर्क लोड प्राथमिकता है (कम संख्या = पहले लोड)।

<?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 ठीक इसी प्रकार का सहायक परिभाषित करता है — simplyVideoCard() — simplyPagination() और simplySortTabs() के साथ। ImpressionTracker::collect() कॉल ही CTR रैंकिंग को फ़ीड करती है; बैच्ड राइट बाद में layout.php में फ्लश किया जाता है।

टेम्पलेट और रेंडरिंग प्रवाह

एक कंट्रोलर डेटा को ThemeRenderer::render($template, $data) को सौंपता है, और रेंडरर वहाँ से आगे बढ़ता है। क्रम को समझने से आपको यह पता चलता है कि कहाँ क्या उपलब्ध है।

1. कंट्रोलर रेंडर करता है। जैसे ThemeRenderer::render('home', ['videos' => $videos])।
2. ग्लोबल्स इंजेक्ट होते हैं। $_-प्रीफ़िक्स्ड साइट, अपीयरेंस, लोकेल और कार्ड/वॉच चर जोड़े जाते हैं।
3. प्लगइन डेटा समायोजित करते हैं। theme.template_data फ़िल्टर चलता है, जो ($data, $templateName) प्राप्त करता है।
4. आपका टेम्पलेट बफ़र करता है। टेम्पलेट फ़ाइल $content में कैप्चर की जाती है।
5. लेआउट लोड होता है। layout.php $content और सभी चर प्राप्त करता है और पूरा HTML शेल आउटपुट करता है।
6. इम्प्रेशन फ्लश होते हैं। ImpressionTracker::flush() </body> से पहले बैच्ड CTR अपडेट लिखता है।
7. Cron चलता है। CronManager::run() किसी भी बकाया शेड्यूल किए गए कार्यों को निष्पादित करता है।

आपका layout.php शेल के लिए जिम्मेदार है: <head> में ThemeRenderer::renderCSS() और $_colorOverrides शामिल करें, $content इको करें, फिर </body> से पहले ThemeRenderer::renderJS() और ImpressionTracker::flush() कॉल करें। थीम API पूरी आठ-बिंदु चेकलिस्ट सूचीबद्ध करता है।

ग्लोबल चर और सहायक

प्रत्येक टेम्पलेट को ग्लोबल $_ चर प्लस अपना डेटा प्राप्त होता है। थीम API संदर्भ इन सभी को दस्तावेज़ करता है; ये वे हैं जिनका आप सबसे अधिक उपयोग करेंगे।

टेम्पलेट फ़ॉलबैक

यदि सक्रिय थीम में कोई टेम्पलेट अनुपस्थित है, तो TubePress Simply की प्रति रेंडर करता है। इसका अर्थ है कि आप केवल वही ओवरराइड करते हैं जो आप बदलना चाहते हैं: एक ही टेम्पलेट — जैसे home.php — को अपनी थीम में कॉपी करके शुरू करें, और बाकी सब कुछ Simply से इनहेरिट होने दें जब तक आप इसे संभालने के लिए तैयार न हों। एक थीम में एक फ़ाइल हो सकती है या पचास।

थीम हुक

टेम्पलेट्स से परे, हुक पॉइंट का एक छोटा सेट आपको (और प्लगइन को) पेज को फ़ोर्क किए बिना विस्तारित करने देता है। एक्शन fire-and-forget होते हैं; फ़िल्टर आपके द्वारा लौटाए गए मान को रूपांतरित करते हैं।

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

दो और फ़िल्टर जानने योग्य हैं: theme.template_data रेंडर से पहले डेटा ऐरे समायोजित करने के लिए, और head.css एक <style> स्ट्रिंग जोड़ने के लिए — Simply बाद वाले का उपयोग अपने ग्रिड गैप और रेडियस को CSS चरों के रूप में प्रकाशित करने के लिए करता है। व्यापक एक्शन/फ़िल्टर कैटालॉग के लिए, हुक और प्लगइन देखें।

अगले चरण