انتقل إلى المحتوى

قوالب الموقع

تتيح قوالب الموقع للسمات القائمة على الكتل تعريف WordPress wp_template ومصادر wp_template_part باستخدام صياغة تضع الملفات أولًا، كما في صفحات Blockstudio والأنماط.

استخدم قوالب الموقع عندما تريد التحكم في تخطيط السمة الذي يحدده WordPress عبر التسلسل الهرمي لقوالب محرر الموقع: الصفحة الرئيسية، والمنشورات المفردة، والأرشيفات، والبحث، وصفحات 404، والترويسات، والتذييلات، وأجزاء القوالب الأخرى.

الصفحات أم الأنماط أم قوالب الموقع؟

الميزة ما الذي تنشئه الأنسب لـ
الصفحات منشورات أو إدخالات لأنواع محتوى مخصصة صفحات المحتوى الفعلية، وصفحات المستندات، والصفحات المقصودة، والمحتوى الذي يمكن الوصول إليه عبر المسارات.
الأنماط أنماط كتل أقسام قابلة لإعادة الاستخدام يُدرجها المحررون.
قوالب الموقع مصدرا ملفات wp_template وwp_template_part تخطيط السمة الذي يتحكم فيه محرر الموقع والتسلسل الهرمي لقوالب WordPress.

لا تنشئ قوالب الموقع صفحات عادية. فهي توفر مصدر الملفات الذي يستخدمه WordPress عند تحديد قالب سمة الكتل. إذا خصّص المستخدم القالب في محرر الموقع، يحفظ WordPress هذا التخصيص في قاعدة البيانات، ويكون له الأولوية على مصدر الملف إلى أن يُعاد ضبطه.

بنية المجلدات

ضع القوالب الكاملة في templates/ وأجزاء القوالب في parts/:

Text
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 هذا الترتيب:

  1. index.php
  2. index.blade.php
  3. index.twig
  4. index.html

يكتشف WordPress أيضًا ملفات .html بشكل تكراري، ويعرض عادةً قالبًا متداخلًا index.html ضمن اسم مستعار مشتق من مساره، مثل header/index. عندما ينتمي هذا الملف إلى بيان Blockstudio، يزيل Blockstudio النسخة المكررة المشتقة من المسار، ولا يعرض سوى slug المعلن في البيان. تبقى قوالب .html الأصلية المتداخلة التي لا تتضمن بيان Blockstudio دون تغيير.

يُجمّع المصدر مرة واحدة إلى ترميز كتل أصلي لـWordPress. ينبغي ألا يعتمد على الطلب الحالي أو المنشور الحالي. ضع سلوك وقت التشغيل داخل الكتل الديناميكية.

template.json

يعرّف template.json قالبًا كاملًا لمحرر الموقع.

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 إلى الأسماء الدقيقة للتسلسل الهرمي للقوالب:

Text
index
home
front-page
single
single-post
single-product
archive
archive-product
page
page-about
404
search
taxonomy-product_cat

part.json

يعرّف part.json جزءًا من قالب محرر الموقع.

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 المساعدة. تُخزّن هنا أيضًا مفاتيح البيان غير المعروفة.

كتابة الترميز

تستخدم مصادر قوالب الموقع المحلّل نفسه المستخدم للصفحات والأنماط:

PHP
<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 تخصيصات المستخدم.

ترتيب البحث هو:

  1. تخصيص قاعدة بيانات محرر الموقع
  2. ملف .html الأصلي للسمة النشطة
  3. المصدر المستند إلى ملفات Blockstudio
  4. العناصر الاحتياطية للسمة الأب أو الإضافة

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

لا يكتب Blockstudio تعديلات محرر الموقع مرة أخرى إلى الملفات في v1.

الأداء

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

يمكن لتكاملات وقت التشغيل التي تجمع الملفات من عدة جذور توفير مصدر اكتشاف منطقي للقوالب وأجزاء القوالب. قد توجد البيانات والقوالب المصدرية المختارة في جذور مادية مختلفة مع الحفاظ على شجرة سمة منطقية واحدة.

PHP API

PHP
$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();

مرّر قائمة صريحة لقراءة وتجميع الأسماء المستعارة أو المسارات أو مسارات المصدر المحددة فقط:

PHP
$templates = Blockstudio\Site_Templates::templates([
    'front-page',
]);

$parts = Blockstudio\Site_Templates::parts([
    'header',
]);

$errors = Blockstudio\Site_Templates::selection_errors('templates');

يؤدي حذف الوسيط إلى الحفاظ على سلوك السجل الكامل. أما تمرير قائمة فارغة فيُرجع بلا عناصر. وتضيّق طلبات الأسماء المستعارة والمسارات المعتادة نطاق الاكتشاف ليقتصر على الأدلة المطابقة؛ وقد تتطلب الأسماء المستعارة المخصصة في البيان فحص البيانات الوصفية، لكن لن تُجمّع المصادر غير المرتبطة ولن تُعاد.

تتوفر أيضًا دوال مساعدة للقوالب:

PHP
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 إجراء يُنفّذ بعد حفظ السجل المعاد بناؤه.

إضافة مسارات الاكتشاف أو استبدالها:

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

تصفية البيانات المكتشفة:

PHP
add_filter('blockstudio/site_templates/templates', function ($templates) {
    return $templates;
});

add_filter('blockstudio/site_templates/parts', function ($parts) {
    return $parts;
});

تصفية المصدر قبل التحليل:

PHP
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);

تغيير المصادر المرشحة أو المحلّل:

PHP
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 ضمن دورة حياة إعادة بناء ذاكرة التخزين المؤقت. ولا يُنفّذان عند إصابة ذاكرة التخزين المؤقت الدافئة للسجل.