قوالب الموقع
تتيح قوالب الموقع للسمات القائمة على الكتل تعريف WordPress wp_template ومصادر wp_template_part باستخدام صياغة تضع الملفات أولًا، كما في صفحات Blockstudio والأنماط.
استخدم قوالب الموقع عندما تريد التحكم في تخطيط السمة الذي يحدده WordPress عبر التسلسل الهرمي لقوالب محرر الموقع: الصفحة الرئيسية، والمنشورات المفردة، والأرشيفات، والبحث، وصفحات 404، والترويسات، والتذييلات، وأجزاء القوالب الأخرى.
الصفحات أم الأنماط أم قوالب الموقع؟
| الميزة | ما الذي تنشئه | الأنسب لـ |
|---|---|---|
| الصفحات | منشورات أو إدخالات لأنواع محتوى مخصصة | صفحات المحتوى الفعلية، وصفحات المستندات، والصفحات المقصودة، والمحتوى الذي يمكن الوصول إليه عبر المسارات. |
| الأنماط | أنماط كتل | أقسام قابلة لإعادة الاستخدام يُدرجها المحررون. |
| قوالب الموقع | مصدرا ملفات wp_template وwp_template_part |
تخطيط السمة الذي يتحكم فيه محرر الموقع والتسلسل الهرمي لقوالب WordPress. |
لا تنشئ قوالب الموقع صفحات عادية. فهي توفر مصدر الملفات الذي يستخدمه WordPress عند تحديد قالب سمة الكتل. إذا خصّص المستخدم القالب في محرر الموقع، يحفظ WordPress هذا التخصيص في قاعدة البيانات، ويكون له الأولوية على مصدر الملف إلى أن يُعاد ضبطه.
بنية المجلدات
ضع القوالب الكاملة في templates/ وأجزاء القوالب في parts/:
theme/
templates/
front-page/
template.json
index.php
single/
template.json
index.twig
parts/
header/
part.json
index.php
footer/
part.json
index.php
يحتوي كل مجلد على ملف بيان وملف مصدر واحد.
| الملف | المحرك |
|---|---|
index.php |
ترميز كتل شبيه بـHTML، يُقرأ كما هو (لا يُنفّذ كود PHP) |
index.blade.php |
Blade |
index.twig |
Twig |
index.html |
ترميز كتل شبيه بـHTML |
إذا وُجدت عدة ملفات مصدر، يستخدم Blockstudio هذا الترتيب:
index.phpindex.blade.phpindex.twigindex.html
يكتشف WordPress أيضًا ملفات .html بشكل تكراري، ويعرض عادةً قالبًا متداخلًا index.html ضمن اسم مستعار مشتق من مساره، مثل header/index.
عندما ينتمي هذا الملف إلى بيان Blockstudio، يزيل Blockstudio النسخة المكررة المشتقة من المسار، ولا يعرض سوى slug المعلن في البيان.
تبقى قوالب .html الأصلية المتداخلة التي لا تتضمن بيان Blockstudio دون تغيير.
يُجمّع المصدر مرة واحدة إلى ترميز كتل أصلي لـWordPress. ينبغي ألا يعتمد على الطلب الحالي أو المنشور الحالي. ضع سلوك وقت التشغيل داخل الكتل الديناميكية.
template.json
يعرّف template.json قالبًا كاملًا لمحرر الموقع.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template",
"postTypes": ["page"]
}
الخصائص
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
slug / name |
string |
اسم المجلد | المعرّف اللطيف للقالب WordPress. استخدم معرّفات التسلسل الهرمي الدقيقة مثل front-page أو single أو archive-product أو 404. |
title |
string |
العنوان من المعرّف اللطيف | عنوان العرض في محرر الموقع. |
description |
string |
"" |
وصف العرض في محرر الموقع. |
postTypes |
string[] |
[] |
أنواع المقالات للقوالب المخصصة. يمكن لقوالب التسلسل الهرمي الأساسية حذف هذا. |
source / template / file |
string |
ملف الفهرس المكتشف تلقائيًا | مسار ملف المصدر اختياريًا، نسبةً إلى مجلد القالب. |
status |
string |
"publish" |
حالة القالب. |
sync |
boolean |
false |
محجوز لتجسيد بيانات قاعدة البيانات مستقبلًا. لا تُستبدل تخصيصات المستخدم أبدًا في v1. |
meta |
object |
{} |
بيانات وصفية مخصصة لواجهات API المساعدة. تُخزّن هنا أيضًا مفاتيح البيان غير المعروفة. |
لا تُضاف بادئة إلى أسماء القوالب المستعارة. يحتاج WordPress إلى الأسماء الدقيقة للتسلسل الهرمي للقوالب:
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat
part.json
يعرّف part.json جزءًا من قالب محرر الموقع.
{
"slug": "header",
"title": "Header",
"description": "Main site header",
"area": "header"
}
الخصائص
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
slug / name |
string |
اسم المجلد | اسم جزء القالب المستعار WordPress. |
title |
string |
العنوان من الاسم المستعار | عنوان العرض في محرر الموقع. |
description |
string |
"" |
وصف العرض في محرر الموقع. |
area |
string |
"uncategorized" |
منطقة جزء القالب. القيم الشائعة هي header وfooter وsidebar. |
source / template / file |
string |
ملف الفهرس المكتشف تلقائيًا | مسار اختياري لملف المصدر نسبةً إلى مجلد الجزء. |
status |
string |
"publish" |
حالة جزء القالب. |
meta |
object |
{} |
بيانات وصفية مخصصة لواجهات API المساعدة. تُخزّن هنا أيضًا مفاتيح البيان غير المعروفة. |
كتابة الترميز
تستخدم مصادر قوالب الموقع المحلّل نفسه المستخدم للصفحات والأنماط:
<div class="site-shell">
<block name="core/template-part" slug="header" />
<main>
<h1>Welcome</h1>
<p>This template is compiled from Blockstudio files.</p>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" />
</div>
يصبح العنصر <main> كتلة core/group تُعرض كـ<main>، وتصبح عناصره الفرعية، بما فيها وسم الكتلة core/post-content، كتلًا داخلية. يمكنك استخدام:
- عناصر HTML القياسية مثل
<h1>و<p>و<ul>و<div>، وعناصر تقسيم المحتوى<main>و<header>و<footer>و<article>و<aside> <block name="namespace/block"><bs:namespace-block>- بادئات وسوم الكتل المضبوطة
- كتل ومكونات Blockstudio
تتلقى كتل أجزاء القوالب سمة القالب النشط عندما يعرض WordPress القالب المجمّع.
تخصيصات محرر الموقع
يوفر Blockstudio مصدر الملف. ويتولى WordPress تخصيصات المستخدم.
ترتيب البحث هو:
- تخصيص قاعدة بيانات محرر الموقع
- ملف
.htmlالأصلي للسمة النشطة - المصدر المستند إلى ملفات Blockstudio
- العناصر الاحتياطية للسمة الأب أو الإضافة
عندما يحفظ المستخدم قالبًا مستندًا إلى ملفات Blockstudio في محرر الموقع، ينشئ WordPress إدخالًا عاديًا من نوع wp_template أو wp_template_part في قاعدة البيانات.
تكون لهذا الإدخال المحفوظ الأولوية على تغييرات الملفات اللاحقة. وتُظهر إعادة ضبط التخصيص أو حذفه مصدر الملفات المحدّث مجددًا.
لا يكتب Blockstudio تعديلات محرر الموقع مرة أخرى إلى الملفات في v1.
الأداء
يُخزّن اكتشاف القوالب مؤقتًا لكل طلب، ويستمر حفظه مع بيانات وصفية لمراقبة الملفات. يؤدي تغيير بيان أو ملف مصدر إلى إبطال المحتوى المجمّع المخزّن مؤقتًا. لا تُخزّن تخصيصات قاعدة البيانات مؤقتًا: إذ يظل WordPress يتحقق منها أولًا.
يمكن لتكاملات وقت التشغيل التي تجمع الملفات من عدة جذور توفير مصدر اكتشاف منطقي للقوالب وأجزاء القوالب. قد توجد البيانات والقوالب المصدرية المختارة في جذور مادية مختلفة مع الحفاظ على شجرة سمة منطقية واحدة.
PHP API
$templates = Blockstudio\Site_Templates::templates();
$parts = Blockstudio\Site_Templates::parts();
$template = Blockstudio\Site_Templates::get_template('front-page');
$header = Blockstudio\Site_Templates::get_part('header');
$paths = Blockstudio\Site_Templates::get_paths();
مرّر قائمة صريحة لقراءة وتجميع الأسماء المستعارة أو المسارات أو مسارات المصدر المحددة فقط:
$templates = Blockstudio\Site_Templates::templates([
'front-page',
]);
$parts = Blockstudio\Site_Templates::parts([
'header',
]);
$errors = Blockstudio\Site_Templates::selection_errors('templates');
يؤدي حذف الوسيط إلى الحفاظ على سلوك السجل الكامل. أما تمرير قائمة فارغة فيُرجع بلا عناصر. وتضيّق طلبات الأسماء المستعارة والمسارات المعتادة نطاق الاكتشاف ليقتصر على الأدلة المطابقة؛ وقد تتطلب الأسماء المستعارة المخصصة في البيان فحص البيانات الوصفية، لكن لن تُجمّع المصادر غير المرتبطة ولن تُعاد.
تتوفر أيضًا دوال مساعدة للقوالب:
blockstudio_site_templates();
blockstudio_site_template_parts();
blockstudio_site_template('front-page');
blockstudio_site_template_part('header');
الخطافات
فيما يلي جميع نقاط التوسعة لقوالب الموقع:
| Hook | النوع | الوصف |
|---|---|---|
blockstudio/site_templates/template_paths |
مرشح | اضبط جذور اكتشاف القوالب الكاملة. |
blockstudio/site_templates/part_paths |
مرشح | اضبط جذور اكتشاف أجزاء القوالب. |
blockstudio/site_templates/paths |
مرشح | اضبط قائمتي المسارات معًا كـtemplates وparts. |
blockstudio/site_templates/template_candidates |
مرشح | اضبط ملفات المصدر المرشحة لبيان. |
blockstudio/site_templates/templates |
مرشح | اضبط القوالب التي يعيدها السجل API. |
blockstudio/site_templates/parts |
مرشح | اضبط أجزاء القوالب التي يعيدها السجل API. |
blockstudio/site_templates/template_content |
مرشح | اضبط مصدر القالب الكامل المجمّع قبل التحليل. |
blockstudio/site_templates/part_content |
مرشح | اضبط مصدر جزء القالب المجمّع قبل التحليل. |
blockstudio/site_templates/parser |
مرشح | استبدل مثيل Html_Parser لعنصر واحد. |
blockstudio/site_templates/source_compiled |
إجراء | يُنفّذ مباشرة قبل تجميع مصدر محدد. |
blockstudio/site_templates/discovered |
إجراء | يُنفّذ بعد مرور بارد للاكتشاف والتجميع. |
blockstudio/site_templates/registered |
إجراء | يُنفّذ بعد حفظ السجل المعاد بناؤه. |
إضافة مسارات الاكتشاف أو استبدالها:
add_filter('blockstudio/site_templates/template_paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/site-templates';
return $paths;
});
add_filter('blockstudio/site_templates/part_paths', function ($paths) {
$paths[] = get_stylesheet_directory() . '/site-parts';
return $paths;
});
add_filter('blockstudio/site_templates/paths', function ($paths) {
return $paths;
});
تصفية البيانات المكتشفة:
add_filter('blockstudio/site_templates/templates', function ($templates) {
return $templates;
});
add_filter('blockstudio/site_templates/parts', function ($parts) {
return $parts;
});
تصفية المصدر قبل التحليل:
add_filter('blockstudio/site_templates/template_content', function ($content, $template) {
return $content;
}, 10, 2);
add_filter('blockstudio/site_templates/part_content', function ($content, $part) {
return $content;
}, 10, 2);
تغيير المصادر المرشحة أو المحلّل:
add_filter(
'blockstudio/site_templates/template_candidates',
function ($candidates, $directory, $manifest) {
$candidates[] = $directory . '/template.custom.php';
return $candidates;
},
10,
3
);
add_filter(
'blockstudio/site_templates/parser',
function ($parser, $item) {
return $parser;
},
10,
2
);
يُنفّذ discovered وregistered ضمن دورة حياة إعادة بناء ذاكرة التخزين المؤقت. ولا يُنفّذان عند إصابة ذاكرة التخزين المؤقت الدافئة للسجل.