قوالب محرر الموقع وأجزاؤه من الملفات
يصف قالب الكتل تخطيطه في templates/*.html وparts/*.html:
ملفات مليئة بتعليقات كتل متسلسلة مثل
<!-- wp:template-part {"slug":"header"} /-->. لا أحد يستمتع بكتابتها
يدويًا، لذا تُنشأ عادةً في محرر الموقع ثم تُصدّر. ينجح ذلك
إلى أن يعدّل شخصان القالب نفسه، أو يضطر مراجع إلى قراءة فرق يتضمن
JSON مهربًا داخل تعليقات HTML.
يتيح لك Blockstudio كتابة القوالب نفسها بالطريقة التي تكتب بها
الصفحات المعتمدة على الملفات: مجلد يتضمن بيان JSON صغيرًا وملفًا
مصدرًا بعلامات ترميز شبيهة بـ HTML، باستخدام عناصر عادية ووسوم <block> وكتل Blockstudio الخاصة بك.
يحوّل Blockstudio المصدر إلى ترميز كتل أصلي ويسلّمه إلى WordPress
كملف للقالب. يظل محرر الموقع يعمل كما كان تمامًا: يمكن للمستخدمين
تخصيص قالب، وتعيد إعادة ضبطه نسخة الملف.
يبني هذا الدليل جزءًا للرأس وآخر للتذييل، وقالبَي الصفحة الرئيسية والمفردة، وقالبًا مخصصًا يمكن للمحررين اختياره للصفحات، ثم يوضح كيف يحلّ WordPress القوالب.
بنية المجلدات
تُوضع القوالب في templates/، وأجزاء القوالب في parts/. كل منها مجلد
يتضمن بيانًا وملفًا مصدرًا واحدًا:
theme/
├── templates/
│ ├── front-page/
│ │ ├── template.json
│ │ └── index.php
│ ├── single/
│ │ ├── template.json
│ │ └── index.php
│ └── page-landing/
│ ├── template.json
│ └── index.php
└── parts/
├── header/
│ ├── part.json
│ └── index.php
└── footer/
├── part.json
└── index.html
هذه هي مجلدات templates/ وparts/ نفسها التي يقرأها WordPress لقالب
الكتل. يفحص Blockstudio القالب النشط أولًا ثم القالب الأب.
المجلدات التي تحتوي على template.json أو part.json هي مصادر Blockstudio؛ أما
ملفات .html العادية المجاورة لها فتبقى قوالب WordPress أصلية.
يمكن أن يكون الملف المصدر index.php أو index.blade.php أو index.twig أو
index.html، ويُتحقق منها بهذا الترتيب. يتطلب Twig إضافة Timber، وتتطلب Blade حزمة العارض الخاصة بها، كما هو موضح في
محركات القوالب.
الخطوة 1: جزء الرأس
يحتاج كل جزء إلى part.json. ويحدد area موضع الجزء في محرر الموقع:
{
"slug": "header",
"title": "Header",
"description": "Site header with logo and navigation",
"area": "header"
}
يستخدم المصدر الصياغة نفسها المستخدمة في صفحات وأنماط Blockstudio. يتحول <div>
إلى كتلة مجموعة، وتصبح السمات سمات كتل، وتنتج عناصر <block>
أي كتلة مسجلة:
<div layout='{"type":"flex","justifyContent":"space-between"}'>
<block name="core/site-title" />
<block name="core/navigation" overlayMenu="mobile" />
</div>
يحوّله Blockstudio إلى ترميز الكتل هذا:
<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} --><div class="wp-block-group is-layout-flex"><!-- wp:site-title /--><!-- wp:navigation {"overlayMenu":"mobile"} /--></div><!-- /wp:group -->
هذا هو الترميز الذي كنت ستكتبه يدويًا. تعمل كتلُك الخاصة بالطريقة نفسها: <block name="acme/announcement" /> أو وسم <bs:acme-announcement />، أو بادئة وسم مضبوطة، كلها تتحول إلى تعليق الكتلة الخاصة بتلك الكتلة.
الخطوة 2: جزء التذييل
قد يتألف الجزء من فقرة واحدة فقط. يستخدم هذا الجزء index.html لتوضيح أن المصدر علامات ترميز، وليس برنامجًا:
{
"slug": "footer",
"title": "Footer",
"area": "footer"
}
<p>Built with Acme.</p>
يتحول إلى <!-- wp:paragraph --><p>Built with Acme.</p><!-- /wp:paragraph -->.
الخطوة 3: قالبا الصفحة الرئيسية والمفردة
تستخدم القوالب template.json. يجب أن يكون slug اسمًا مطابقًا تمامًا ضمن تسلسل القوالب الهرمي مثل WordPress أو front-page أو single أو page أو archive أو 404 أو single-product. لا يسبقه Blockstudio أبدًا.
{
"slug": "front-page",
"title": "Front Page",
"description": "Homepage template"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
يتبع قالب المقالة المفردة البنية نفسها مع كتل المقالات:
{
"slug": "single",
"title": "Single Post"
}
<block name="core/template-part" slug="header" tagName="header" />
<main>
<block name="core/post-title" level="1" />
<block name="core/post-date" />
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
قالب المقالة المفردة بعد تحويله:
<!-- wp:template-part {"slug":"header","tagName":"header"} /--><!-- wp:group {"tagName":"main"} --><main class="wp-block-group"><!-- wp:post-title {"level":1} /--><!-- wp:post-date /--><!-- wp:post-content /--></main><!-- /wp:group --><!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->
تحول <main> إلى كتلة مجموعة مع tagName: "main"، وتشير كتل أجزاء القالب إلى الجزأين من الخطوتين 1 و2 باستخدام المعرّف المختصر. عندما يعرض WordPress القالب، تُحل هذه الإشارات إلى الأجزاء المعتمدة على الملفات، فيبدأ ناتج الصفحة الرئيسية بـ <header class="wp-block-template-part"> الذي يحتوي على عنوان الموقع والتنقل، وينتهي بـ <footer class="wp-block-template-part"> الذي يحتوي على فقرة التذييل.
الخطوة 4: قالب مخصص للصفحات
القوالب التي لا ينتمي معرّفها المختصر إلى التسلسل الهرمي هي قوالب مخصصة. أدرج أنواع المحتوى التي تنطبق عليها باستخدام postTypes، ويمكن للمحررين اختيارها من محدد القالب:
{
"slug": "page-landing",
"title": "Landing Page",
"description": "Full-width page without a header",
"postTypes": ["page"]
}
<main>
<block name="core/post-content" />
</main>
<block name="core/template-part" slug="footer" tagName="footer" />
يتضمن get_block_templates( array( 'post_type' => 'page' ), 'wp_template' ) الآن page-landing، ويحمل كائن القالب post_types: ["page"].
تُحوّل المصادر مرة واحدة
يُقرأ المصدر ويُحوّل إلى ترميز كتل مرة واحدة، لا مع كل طلب. لا تتوفر فيه المقالة الحالية أو سياق الطلب. يُقرأ index.php على أنه علامات ترميز: لا يُنفذ فيه كود PHP، لذا يتحول <?php echo get_bloginfo( 'name' ); ?> إلى لا شيء. كل ما يعتمد على الطلب يجب أن يكون في كتلة تُعرض وقت التشغيل: استخدم core/site-title بدلًا من اسم موقع مطبوع، وcore/post-title بدلًا من the_title()، أو كتلة Blockstudio ديناميكية خاصة بك.
تُخزّن النتائج المحوّلة مؤقتًا مع بيانات مراقبة الملفات. يؤدي تعديل بيان أو ملف مصدر إلى إبطال المحتوى المخزّن مؤقتًا لذلك العنصر، فيظهر التغيير عند الطلب التالي دون خطوة بناء منفصلة.
كيف يرى WordPress الملفات
يتصل Blockstudio بعمليات البحث نفسها التي يستخدمها WordPress لقوالب القالب. في get_block_templates()، تظهر القوالب المعتمدة على الملفات مع source: "theme" وorigin: "theme"، تمامًا مثل ملفات القالب الأصلية، ويعيد get_block_template( 'acme//header', 'wp_template_part' ) جزء الرأس مع area الخاص به.
ترتيب البحث هو:
- تخصيص في محرر الموقع مخزّن في قاعدة البيانات.
- ملف
.htmlأصلي في القالب النشط. - المصدر المعتمد على الملفات Blockstudio.
- بدائل القالب الأب أو الإضافات.
يحافظ هذا الترتيب على سير العمل في محرر الموقع. عندما يعدّل المستخدم التذييل ويحفظه، يخزّن WordPress منشور wp_template_part، ويعيد get_block_template() ذلك التخصيص مع source: "custom".
لا تظهر التغييرات اللاحقة على parts/footer/index.html ما دام التخصيص موجودًا. عند إعادة ضبط الجزء أو حذف المنشور، يعود البحث إلى الملف ويعيد أحدث مصدر محوّل.
لا يكتب Blockstudio تعديلات محرر الموقع إلى الملفات. إذا أردت أن يصبح التغيير هو الإعداد الافتراضي الجديد، فانقله إلى الملف المصدر وأعد ضبط التخصيص.
تداخل index.html والمعرّفات المختصرة
يكتشف WordPress ملفات .html في templates/ وparts/ بشكل متكرر. لذا سيظهر مجلد بيان يستخدم index.html، مثل parts/footer/index.html، أيضًا كجزء أصلي بمعرّف مختصر مستمد من المسار footer/index. منذ Blockstudio 7.6.6، لا يُعرض index.html المملوك لبيان إلا بمعرّفه المختصر المحدد، لذا يعرض محرر الموقع تذييلًا واحدًا لا اثنين. وتُترك ملفات .html المتداخلة بلا بيان كما هي.
فحص القوالب من PHP
تقرأ الفئة Blockstudio\Site_Templates المصادر وتحولها، ما يفيد في الاختبارات وفحوصات النشر:
$templates = Blockstudio\Site_Templates::templates();
$header = Blockstudio\Site_Templates::get_part( 'header' );
echo $header['area']; // header
echo $header['content']; // compiled block markup
$errors = Blockstudio\Site_Templates::errors();
يتضمن كل عنصر slug وtitle وdescription وtype (wp_template أو wp_template_part) وstatus وsource_type وpostTypes للقوالب أو area للأجزاء وmeta وcontent المحوّل. مرّر قائمة لحصر التحويل في عناصر محددة، واقرأ المشكلات الخاصة بهذا التحديد باستخدام selection_errors():
$selected = Blockstudio\Site_Templates::templates( array( 'front-page' ) );
$errors = Blockstudio\Site_Templates::selection_errors( 'templates' );
إضافة مجلدات أخرى
لإبقاء مصادر Blockstudio منفصلة عن القوالب الأصلية، أو لتضمينها في إضافة، أضف مسارات اكتشاف باستخدام المرشحات:
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;
} );
يعدّل المرشحان blockstudio/site_templates/template_content وpart_content المصدر قبل تحليله، ويستبدل blockstudio/site_templates/parser المحلل لعنصر واحد. تجد القائمة الكاملة في جدول خطافات قوالب الموقع.
متى تستخدم كل خيار
| ما تريده | استخدم |
|---|---|
| تخطيط القالب الذي يختاره WordPress لـURL: الرأس والتذييل والمفرد والأرشيف | قوالب الموقع وأجزاؤه |
| صفحة يمكن الوصول إليها عبر مسار ويكون محتواها في ملفات | الصفحات المعتمدة على الملفات |
| قسم قابل لإعادة الاستخدام يدرجه المحررون | الأنماط |
القوالب لا تنشئ منشورات؛ الصفحات هي التي تنشئها. فقسم التوثيق، مثلًا، مجموعة صفحات تُعرض منشوراتها عبر قالب يمكنك إنشاؤه هنا.
الخطوات التالية
- مرجع قوالب الموقع: كل خاصية في البيان، وPHP API، وجميع الخطافات.
- نظرة عامة على الصفحات والأنماط: المحلل HTML ووسوم الكتل وربط العناصر المستخدمة في مصادر القوالب.
- إنشاء موقع للتوثيق: مجموعات الصفحات مع Markdown والمحملات والتخطيطات.