مرجع المطوّرين

مرجع واجهة برمجة القوالب

مرجع واجهة برمجة قوالب TubePress: كل متغير قالب عام، ودالة مساعدة، وفئة متاحة عند بناء أو تخصيص قالب موقع تيوب.

هذه الصفحة هي المرجع الشامل لكل ما يمكن للثيم استخدامه: المتغيرات العامة المُحقنة في كل قالب، والمتغيرات الخاصة بكل قالب، والفئات المساعدة المتاحة في كود الثيم. إذا كنت تبني ثيمًا أو تخصصه، احتفظ بهذه الصفحة مفتوحة إلى جانب تطوير الثيم.

يُعرض كل قالب بواسطة ThemeRenderer::render($template, $data). يقوم المُعرض بحقن مجموعة من المتغيرات العامة ذات البادئة $_، ودمج البيانات $data الخاصة بالقالب، وتشغيل فلتر theme.template_data، وتخزين قالبك مؤقتًا في $content، ثم تحميل layout.php.

المتغيرات العامة

هذه المتغيرات متاحة في كل قالب وفي layout.php.

الموقع

المتغير	النوع	الوصف
`$_template`	string	اسم القالب الحالي (مثلاً: `'home'`، `'video'`)
`$_siteName`	string	اسم الموقع من الإعدادات
`$_siteDescription`	string	وصف الموقع
`$_siteUrl`	string	رابط الموقع
`$_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	لغة من اليمين إلى اليسار
`$_availableLangs`	array	اللغات المتاحة
`$_langPrefix`	string	بادئة الرابط (مثلاً: `'/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* مباشرةً من شاشة Appearance في لوحة الإدارة، مما يتيح لأصحاب المواقع تغيير مظهر ثيمك دون المساس بالكود — بشرط أن تقرأ هذه المتغيرات عوضًا عن ترميز القيم بشكل مباشر.

متغيرات خاصة بكل قالب

بالإضافة إلى المتغيرات العامة، يستقبل كل قالب بياناته الخاصة.

home.php

المتغير	النوع
`$videos`	مصفوفة — صفوف الفيديو
`$pagination`	كائن Pagination
`$sort`	سلسلة نصية — مفتاح الترتيب الحالي

video.php

المتغير	النوع
`$video`	مصفوفة — الفيديو الكامل مع الفئات، الوسوم، المؤدين، القنوات
`$categories`, `$tags`, `$performers`	مصفوفة
`$comments`	مصفوفة
`$similar`	مصفوفة — مقاطع فيديو مشابهة
`$recommended`	مصفوفة — مقاطع فيديو موصى بها
`$userVote`	string\\|null — `'like'`، `'dislike'` أو null
`$isFavorited`	bool

category.php / tag.php / performer.php / channel.php

المتغير	النوع
`$category` / `$tag` / `$performer` / `$channel`	مصفوفة — الكيان
`$videos`	مصفوفة — صفوف الفيديو
`$pagination`	كائن Pagination
`$sort`	سلسلة نصية

قوالب القوائم

القالب	المتغيرات الرئيسية
`categories.php`	`$categories` — كل منها يحتوي على `video_count`؛ عند تفعيل CTR، يوجد `best_video_thumbnail`
`performers.php`	`$performers` — `video_count`؛ عند تفعيل CTR، يوجد `best_video_thumbnail`، `total_ctr`، مرتبة حسب CTR؛ `$pagination`
`channels.php`	نفس هيكل المؤدين
`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>).
تضمين <?= ThemeRenderer::renderCSS() ?> داخل <head>.
تضمين <?= $_colorOverrides ?> داخل <head>.
إخراج $content داخل <main>.
تضمين <?= ThemeRenderer::renderJS() ?> قبل </body>.
استدعاء <?php ImpressionTracker::flush(); ?> قبل </body> (لـ CTR).
استدعاء <?php HookSystem::doAction('head.meta'); ?> داخل <head>.
استدعاء <?php HookSystem::doAction('footer.scripts'); ?> قبل </body>.

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

إذا كان قالب ما غير موجود في الثيم النشط، يعود TubePress إلى ثيم Simply المُضمَّن. لذلك، يحتاج الثيم المخصص فقط إلى تجاوز القوالب التي يريد تغييرها فعلاً — ابدأ بقالب واحد وتوسع من هناك.

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

تطوير الثيمبناء ثيم من الصفر، خطوة بخطوة. الخطافات والإضافاتالإجراءات والفلاتر التي يمكنك الارتباط بها. البنية المعماريةكيف يتكامل نظام CMS بأكمله.

لا تزال عالقاً؟

افتح تذكرة من لوحة التحكم وسيساعدك فريقنا.

جرّب العرض التجريبي المباشر → تحميل TubePress →