تطوير القوالب

سمة TubePress هي مجلد يحتوي على قوالب PHP إلى جانب ملفات الوسائط والدوال المساعدة الاختيارية. الجأ إلى سمة مخصصة عندما لا تكفي المظهر ومحرر السمات، وتريد التحكم الكامل في الوسم. هذه الصفحة دليل البناء؛ احتفظ بـ مرجع 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() تحديث CTR المجمَّع قبل </body>.
7. يعمل Cron. تُنفِّذ CronManager::run() أي مهام مجدولة مستحقة.

يتحمل layout.php الخاص بك مسؤولية الهيكل: أدرج ThemeRenderer::renderCSS() و$_colorOverrides في <head>، ثم اعرض $content، ثم استدعِ ThemeRenderer::renderJS() وImpressionTracker::flush() قبل </body>. تُدرج API السمة قائمة التحقق الكاملة المكوَّنة من ثماني نقاط.

المتغيرات العامة والدوال المساعدة

يستقبل كل قالب المتغيرات العامة $_ إضافةً إلى بياناته الخاصة. يوثِّق مرجع API السمة جميعها؛ هذه هي الأكثر استخدامًا.

احتياطي القالب

إذا كانت السمة النشطة تفتقر إلى قالب، يعرض TubePress نسخة Simply بدلًا منه. هذا يعني أنك تتجاوز فقط ما تريد تغييره: ابدأ بنسخ قالب واحد — مثل home.php — إلى سمتك، ودع كل شيء آخر يرث من Simply حتى تكون مستعدًا لتولِّيه. يمكن أن تكون السمة ملفًا واحدًا أو خمسين ملفًا.

خطافات السمة

بعيدًا عن القوالب، تتيح مجموعة صغيرة من نقاط الخطافات لك (وللإضافات) توسيع الصفحة دون تفريعها. الإجراءات (Actions) تُطلَق وتُنسى؛ الفلاتر (Filters) تحوِّل قيمة تُعيدها.

// 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. للاطلاع على كتالوج الإجراءات/الفلاتر الأوسع، راجع الخطافات والإضافات.

الخطوات التالية