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

العرض البرمجي

مع تحوّل Gutenberg إلى أداة بارزة لإنشاء مواقع يسهل على العملاء تحريرها، من المنطقي إنشاء جميع أقسام الموقع اللازمة على هيئة كتل. يلائم هذا النهج معظم الحالات، لكن قد يحتاج المستخدمون المتقدمون وبعض حالات الاستخدام المحددة إلى استعمال هذه الكتل خارج المحرر.

يوفّر Blockstudio طريقتين لعرض الكتل برمجيًا:

  • دوال PHP: ‏bs_render_block وbs_block للعرض من كود PHP
  • وسوم HTML: وسوم <bs:block-name> تُستبدل بمخرجات الكتلة في أي موضع من الصفحة

تتوافق جميع الميزات الخاصة بـBlockstudio، مثل الأنماط المضمّنة والنصوص البرمجية والأنماط المحددة النطاق.

تعمل الجزر أيضًا عبر مسارات العرض هذه. فالجزيرة الديناميكية التي تُعرض باستخدام bs_render_block() أو bs_block() أو وسم كتلة تُرجع علامة العنصر النائب نفسها التي تُرجعها كتلة معروضة من محتوى المنشور، ويُحقن وقت تشغيل الواجهة الأمامية عند وجود تلك العلامة في الاستجابة.

التركيبات المنظّمة والمستندات الكاملة

بالنسبة إلى الأدوات والمعاينات والصادرات ومعارض المكوّنات طويلة الأمد، استخدم Blockstudio\Render API ذا الإصدار المحدد. فهو يقبل تعريفًا واحدًا أو قائمة مرتبة، ويعرض المحتوى دون طباعته:

PHP
use Blockstudio\Render;

$composition = [
  'root' => 'theme/card',
  'example' => [
    'data' => [
      'heading' => 'Example card',
    ],
    'layers' => [
      [
        'name' => 'theme/button',
        'data' => [
          'label' => 'Continue',
        ],
      ],
    ],
  ],
];

$normalized = Render::normalize($composition);
$html = Render::composition($composition);
$document = Render::document($composition, [
  'title' => 'Component preview',
  'contentElement' => 'main',
  'contentClasses' => ['component-preview'],
]);

يتضمن التعريف المعياري المطبع أربعة مفاتيح:

PHP
[
  'name' => 'theme/card',
  'attributes' => [],
  'content' => '',
  'children' => [],
]

تُعد data وinner وinnerBlocks وroot وlayers وexample خيارات ميسّرة للإدخال، وتُزال أثناء التطبيع. وتُعرض التعريفات المتداخلة تكراريًا عبر مسار Blockstudio نفسه.

يعيد Render::document() القيم schemaVersion وhtml وbody وblocks وassets وwarnings وerrors. وتفصل قيمة assets بين head وfooter وstyles وscripts وmodules وinteractivity وui وtailwind. وتتضمن قائمة الكتل والأصول التبعيات التي تشير إليها القوالب المحددة، وتستبعد الأصول غير المرتبطة والمخصصة للمحرر فقط.

يمكن للمستندات الكاملة تعيين bodyClasses/bodyAttributes، وإحاطة المتن المعروض اختياريًا بكل من contentElement وcontentClasses وcontentAttributes. ويُقيّد الغلاف باسم عنصر آمن؛ وتظل قيمة body المعادة هي المحتوى المعروض من دون غلاف. تضيف الخياران head وfooter ترميزًا موثوقًا للمستند في موضعيهما، ويُدرجان ضمن مجموعة الأصول المعادة.

لتجميع مستند حول HTML معروض مسبقًا، حدّد أسماء كتل الجذر المعروفة:

PHP
$document = Render::document_from_html(
  $rendered_html,
  ['theme/hero', 'theme/button'],
  ['title' => 'Homepage preview']
);

استخدم Render::content() لمحتوى كتل WordPress المتسلسل. وينبغي للمستهلكين الذين يعرضون عدة مستندات مستقلة في طلب واحد استدعاء Blockstudio\Batch_Render::reset() بينها؛ إذ ينفذ Canvas::documents() ذلك تلقائيًا.

العرض خارج الصفحة

يضع Blockstudio تعليق <!--blockstudio/namespace/slug--> قبل كل كتلة يعرضها. في صفحة الواجهة الأمامية، يقرأ المخزن المؤقت هذه التعليقات لمعرفة الكتل الموجودة، ويحمل ملفات الأصول الخاصة بها، ثم يزيل التعليقات قبل إرسال الاستجابة.

يحتفظ الإخراج الذي لا يمر عبر ذلك المخزن المؤقت بالتعليقات. ينطبق ذلك على استجابات REST والخلاصات ومعالجات AJAX وHTML التي تخزنها أو ترسلها إلى مكان آخر بعد do_blocks() أو Render::content() أو bs_render_block(). استخدم bs_strip_render_markers() لإزالتها:

PHP
$html = bs_strip_render_markers(do_blocks($post->post_content));

تزيل الدالة تعليقات كتل Blockstudio المسجلة وتترك كل شيء آخر دون تغيير، بما في ذلك تعليقات HTML الأخرى. وهي تطابق العلامات نفسها التي يزيلها مخزن الصفحة المؤقت. استدعها بعد تسجيل الكتل (init أو إصدار أحدث).

لا تزل الترميز الذي لا يزال يُطبع في صفحة واجهة أمامية مخزنة مؤقتًا. تحتاج الصفحة إلى التعليقات لمعرفة ملفات أصول الكتل التي يجب تحميلها، وBlockstudio يزيلها بنفسه في النهاية.

لا تؤدي إزالة التعليقات إلى إضافة ملفات الأصول. لا تُدرج ملفات الكتل CSS وJavaScript إلا بواسطة مخزن الصفحة المؤقت. استخدم bs_block_assets() أو Render::document() عندما يحتاجها المستهلك أيضًا.

فحص الكتل

استخدم bs_block_fields() بعد تسجيل الكتل (على init أو إصدار أحدث) للحصول على تعريفات الحقول بعد حلّها، دون قراءة السجلات الداخلية:

PHP
$fields = bs_block_fields('theme/card');

if ($fields === null) {
  // Unknown block, or not a Blockstudio block.
}

القيمة المعادة هي مصفوفة تعريفات الحقول المسجلة، بما في ذلك مرشحات السمات والحقول المخصصة الموسعة والتجاوزات والمجموعات وعلامات التبويب والمكررات المتداخلة. تُعيد كتلة Blockstudio بلا حقول القيمة []. والنتيجة نسخة؛ لذا لا يغيّر تعديلها الكتلة المسجلة.

هذه تعريفات وليست قيمًا محفوظة. للتحقق من صحة الترميز المحفوظ، استخدم bs_validate_block() بدلًا من صيانة أداة منفصلة لاجتياز الحقول. لوصف القيم التي يقبلها المكوّن، استخدم bs_block_schema(). تظل السمات التي تديرها WordPress منفصلة.

الحقول التي تضيفها الإضافات ليست جزءًا من bs_block_fields(). استخدم bs_block_extension_fields() للحصول عليها. وهي تطابق الإضافات حسب اسم الكتلة، لذا تعمل أيضًا مع الكتل الأساسية وكتل الجهات الخارجية:

PHP
$fields = array_merge(
  bs_block_fields('core/paragraph') ?? [],
  bs_block_extension_fields('core/paragraph')
);

تسرد القيمة المعادة تعريفات الحقول لكل إضافة مطابقة، حسب ترتيب تسجيل الإضافات، وبالبنية نفسها التي لدى bs_block_fields(). وتُعيد الكتلة التي لا تطابقها أي إضافة القيمة []. تُحفظ قيم الإضافات في كائن attrs.blockstudio.attributes نفسه الذي تُحفظ فيه قيم حقول الكتلة، لذا تشترك جميع المعرّفات في مساحة أسماء واحدة. إذا عرّفت إضافتان المعرّف نفسه، فسيُعاد التعريفان ويحرران القيمة نفسها؛ وعند العرض، يُطبّق تعريف الإضافة المسجلة لاحقًا.

لقراءة قيم كتلة محفوظة كما يتلقاها قالبها، استخدم bs_block_values().

استخدم bs_block_assets() لفحص CSS وJavaScript المكتشفتين للكتلة. للحصول على مستند معاينة كامل يشمل الكتل المتداخلة وتبعيات وقت التشغيل المشتركة، استخدم Render::document() كما هو موضح أعلاه.

التحقق من القيم المخزنة

استخدم bs_validate_block() بعد تسجيل الكتل (init أو إصدار أحدث) للتحقق برمجيًا من سمات الكتل المُنشأة أو المستوردة قبل حفظها:

PHP
$block = parse_blocks($content)[0];
$findings = bs_validate_block($block['blockName'], $block['attrs']);

if ($findings === null) {
  // No Blockstudio fields or matching extensions apply.
} elseif ($findings === []) {
  // No stored-value problems were found.
} else {
  // Review the findings before saving.
}

مرّر مصفوفة attrs كاملة، لا blockstudio.attributes فقط. يقبل عرض Blockstudio الحقول المعلنة في المستوى الأعلى أيضًا، وتكون الأولوية للقيم المتداخلة عند توفير الاثنين. لا تقرأ إضافات الكتل الأساسية وكتل الجهات الخارجية إلا blockstudio.attributes. تُدار كتلة Blockstudio فارغة وتُعيد []، لا null.

التحقق صريح ومخصص للقراءة فقط. فهو لا يعرض القوالب أو يغيّر القيم أو يحفظ المنشورات أو يستعلم عن الوسائط أو يشغّل عمليات التعبئة. ولا يعمل تلقائيًا أثناء الحفظ أو مزامنة الصفحات أو العرض. وهو ليس أداة لتنقية البيانات، ولا فحصًا للصلاحيات، ولا تحققًا من وجود مرفق.

تحتوي كل نتيجة على هذه المفاتيح الثابتة:

PHP
[
  'code' => 'unknown_option',
  'path' => 'steps/1/style',
  'source' => 'block',
  'message' => 'This value is not among the field options.',
  'value' => 'c',
  'expected' => ['a', 'b'],
]

استخدم code، وليس message المترجم، في أدوات التطوير. ‏source هو block أو extension. تستخدم المسارات مفاتيح التخزين وفهارس صفوف المكررات أو الاختيارات التي تبدأ من الصفر، من دون شرطة مائلة في البداية. تُهَرَّب ~ و/ الحرفيتان في المفتاح إلى ~0 و ~1. تضيف المجموعة ذات المستوى الأعلى بادئة إلى عناصرها الفرعية (cta_title)؛ أما المجموعات وعلامات التبويب المجهولة فلا تضيف مستوى. لا يدعم المنشئ المجموعات التي تحتوي على معرّف داخل مجموعة أخرى أو مكرر، لذا لا تُقبل مفاتيحها. لا تحتوي حقول الرسائل على قيمة مخزنة. يسمح حقل الملفات بالعنصر المصاحب <id>__size. في جذر كتلة Blockstudio، لا تُعد مفاتيح تسجيل العمليات والسمات العامة HTML المُمررة إلى العنصر المعروض حقولاً غير معروفة. ولا يسمح هذا بمفاتيح عشوائية في صفوف المكررات أو بتوسيع الكتل الأساسية.

الرمز المعنى expected
unknown_field لا يعرّف أي حقل محتفظ به مفتاح التخزين هذا. مفاتيح التخزين المعروفة.
unknown_option الاختيار ليس ضمن الخيارات المعروفة. قيم الخيارات المسموح بها.
wrong_type البنية المخزنة غير مدعومة لهذا الحقل. عائلة التخزين أو النوع المتوقع.
too_few_rows، too_many_rows المكرر الموجود خارج الحد الأدنى min أو الأقصى max. حد الصفوف.
definition_conflict تتطلب التعريفات المنطبقة على مفتاح واحد أشكال تخزين مختلفة. المصدر ونوع الحقل لكل تعريف.
shadowed_value تتجاوز قيمة متداخلة قيمة حقل مختلفة في المستوى الأعلى. القيمة المتداخلة الفائزة.
extension_top_level يستطيع القالب قراءة قيمة في المستوى الأعلى، لكن لا تستطيع روابط التوسعة ذلك. المسار المطلوب لها ضمن blockstudio/attributes.
unknown_attribute لا يقرأ مسار العرض مفتاحاً في المستوى الأعلى لكتلة Blockstudio، لذا يُسقط. أسماء السمات المسجلة وحقول التوسعة وblockstudio.
missing_container خُزِّن attributes أو disabled أو name أو editor في المستوى الأعلى، مع غياب blockstudio. المسار المطلوب له ضمن blockstudio.
invalid_container blockstudio أو blockstudio.attributes ليس كائناً. object.

تسمّي رسالة نتيجة العثور على unknown_field أقرب مفتاح تخزين على المستوى نفسه إذا كان الفرق بينهما لا يتجاوز ثلاث عمليات تحرير، وفقًا لقاعدة الإعدادات غير المعروفة: This storage key is not declared by the block or its extensions. Did you mean "title"? ولا يزال expected يسرد كل مفتاح معروف. تتجاهل المطابقة حالة الأحرف ولا تنظر إلا في مفاتيح التخزين داخل ذلك الحاوي. تُترجم الرسائل؛ لذا ينبغي للتكاملات استخدام code وpath وexpected بدلًا من تحليل نص الرسالة.

يُسقط المفتاح في المستوى الأعلى لكتلة Blockstudio إذا لم يكن سمة مسجلة (حقولها، والسمات التي تضيفها WordPress لـsupports وlock وmetadata)، أو حقلاً في توسعة مطابقة، أو blockstudio، أو مفتاحاً لتسجيل العمليات أو سمة HTML مُمررة، وذلك قبل تشغيل القالب. يؤدي هذا المفتاح، مثلاً، إذا كان معرّف حقل مكتوباً بطريقة خاطئة أو كائن قيم مخزناً من دون غلاف blockstudio الخاص به، إلى ظهور نتيجة؛ لأن الكتلة تُعرض من دون تلك القيمة. لا تُفحص الكتل التي لا تحمل سوى حقول التوسعة بحثاً عن مفاتيح في المستوى الأعلى.

تتبع الأشكال المقبولة طريقة العرض: يمكن أن تحتوي الاختيارات المتعددة ومربعات الاختيار على قائمة أو كائن خيار واحد أو قيمة عددية مستوردة، بما في ذلك الصفر. تُقبل السلاسل الرقمية للأعداد. يمكن أن تحتوي الملفات على معرّفات مرفقات أو كائنات معرّفات أو قوائم أو مراجع نصية. يجب أن تكون قيم الروابط والأيقونات كائنات؛ وتستخدم أنواع الحقول المخصصة نوع السمات المسجل لها. يحتوي حقل attributes على قائمة من الأزواج، لكل منها اسم attribute غير فارغ وقيمة قياسية value؛ وتُحفظ البيانات الوصفية الاختيارية مثل data.media.

يتحقق WordPress من السمات المسجلة في المستوى الأعلى قبل العرض، وقد يرفض شكلاً مقبولاً داخل blockstudio.attributes. مثلاً، تعمل قيمة الراديو "a" في الكائن المتداخل، لكنها تُسقط في المستوى الأعلى، حيث نوعها المسجل هو object. وتؤدي هذه القيمة إلى wrong_type. استخدم الكائن المتداخل لشكل التخزين نفسه الذي يكتبه المحرر.

الحقول المفقودة غير مطلوبة. لا تؤدي القيم المتداخلة الفارغة (null وfalse و'' و[]) والحقول المعطلة إلى أخطاء في القيم. يظل المكرر الفارغ صراحةً خاضعاً للتحقق من min؛ أما المكرر الغائب أو المعطل فلا يخضع له. تُبلّغ قيمة المستوى الأعلى الفارغة إذا أسقطها WordPress وأعاد قيمة افتراضية غير فارغة بدلاً منها. ويمكن للقيمة نفسها في الكائن المتداخل مسحها. يُبلّغ عن تعارضات التعريف حتى عندما لا تكون للمفتاح قيمة محفوظة.

يُتحقق من الخيارات الثابتة وخيارات التعبئة التي حُلّت مسبقاً عند التسجيل من دون استدعاء التعبئة مجدداً. تُتخطى خيارات fetch البعيدة ووسيطات التعبئة التي تحتوي على {attributes.*}. قد تكون قيم الألوان والتدرجات مخصصة ما لم يُضبط disableCustomColors أو disableCustomGradients. يتحقق هذا من القيم المخزنة، وليس من default أو fallback أو قواعد التحقق في المحرر.

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

تتحقق الدالة من كتلة واحدة. مرّر عبر innerBlocks عند التحقق من مستند؛ إذ لا تُوسّع الأنماط المتزامنة والمراجع الأخرى تلقائياً. يمرّ الأمر wp bs blocks validate على كتل منشور واحد أو أكثر ويعرض مساراتها.

يمكن للمواقع التي تستخدم محللاً مخصصاً وقت العرض تكييف النتائج من دون تغيير البيانات المخزنة:

PHP
add_filter('blockstudio/blocks/attributes/validate', function($findings, $name, $attrs) {
  if ($name !== 'my-theme/card') {
    return $findings;
  }

  return array_values(array_filter($findings, function($finding) {
    return !($finding['path'] === 'customReference' && $finding['code'] === 'wrong_type');
  }));
}, 10, 3);

أعِد دائماً قائمة بالنتائج؛ فإرجاع [] يعني قبول الكتلة. لا يعمل هذا المرشح إلا مع الكتل المُدارة، ولا يعمل أبداً مع نتيجة null.

وصف القيم المخزنة

استخدم bs_block_schema() بعد تسجيل المكوّن (init أو إصدار أحدث) لوصف القيم التي يخزنها المكوّن، مثلًا لإنشاء ترميز المكوّن في أداة أو تكامل ذكاء اصطناعي، أو للتحقق من المدخلات في مسار REST:

PHP
$schema = bs_block_schema('theme/card');

if ($schema === null) {
  // No Blockstudio fields or matching extensions apply.
}

النتيجة مخطط JSON للكائن المحفوظ في attrs.blockstudio.attributes. ويشمل حقول المكوّن وحقول الامتدادات المطابقة، مع مفاتيح التخزين التي يستخدمها التحقق من الصحة: تضيف المجموعة على المستوى الأعلى بادئة إلى عناصرها الفرعية، ولا تضيف المجموعات المجهولة وعلامات التبويب مستوى، ويضيف حقل الملفات العنصر المرافق <id>__size. المكررات قوائم من كائنات الصفوف تتضمن minItems وmaxItems من min وmax. تكون additionalProperties هي false عند جذر تخزين الحقول وفي صفوف المكررات. ويمكن للحقول ذات القيم الكائنية، مثل الروابط والكائنات المخصصة، أن تتضمن بياناتها الوصفية الخاصة. لا يتضمن المكوّن الذي بلا حقول أي properties، لذا لا يطابقه سوى كائن فارغ.

يوصف كل حقل بصيغة معيارية تقبلها bs_validate_block():

الحقل المخطط
text، textarea، richtext، wysiwyg، code، date، datetime، unit، classes، html-tag، block سلسلة نصية.
number، range رقم، مع minimum وmaximum من min وmax.
toggle قيمة منطقية.
select، radio، checkbox قيمة خيار، أو قائمة بقيم الخيارات لكل من checkbox وmultiple، مع enum.
color، gradient سلسلة نصية، مع enum عند ضبط disableCustomColors أو disableCustomGradients.
token قائمة من السلاسل النصية.
files معرّف مرفق عدد صحيح غير سالب، أو قائمة معرّفات مع multiple.
link كائن يتضمن url وtitle وopensInNewTab؛ ويُعد url مطلوبًا.
icon كائن يتضمن set وsubSet وicon؛ ويُعد set وicon مطلوبين.
attributes قائمة من الكائنات تتضمن attribute غير فارغ وvalue قياسيًا.
repeater قائمة من كائنات الصفوف.
أنواع الحقول المخصصة نوع السمة المسجّل لها.

يسرد enum الخيارات التي يتحقق النظام من صحتها: الخيارات الثابتة وخيارات الملء التي حُلّت مسبقًا عند التسجيل. لا تتوفر قيمة enum لخيارات fetch البعيدة ولوسائط الملء التي تحتوي على {attributes.*}. يُستبعد المفتاح الذي تتضمن تعريفاته أشكال تخزين مختلفة، لأن التحقق يعرض كل قيمة مخزنة تحته. عندما يشترك حقل في المكوّن وحقل في أحد امتداداته في المفتاح نفسه، يسرد enum القيم التي يقبلها كلاهما. تدمج المكررات المشتركة حقولها الفرعية وتطبّق الحدود الأكثر تقييدًا للصفوف من كلا التعريفين. داخل صفوف المكررات، يُطبّق أول حقل ذي معرّف مطابق في كل مصدر، كما يحدث عند العرض. وتكون الأولوية لحقل صريح اسمه <id>__size على العنصر المرافق لحجم الملف المضاف تلقائيًا.

عندما لا تتوفر خيارات لحقل مغلق، أو لا يوجد تداخل بين مجموعتي خيارات منطبقتين، تكون قيمته المعيارية null للاختيار المفرد أو قائمة فارغة للاختيارات المتعددة. ولا تتحول قائمة الخيارات الفارغة إلى حقل غير مقيّد. تظل الخيارات البعيدة والخيارات المعتمدة على السمات مفتوحة.

تصبح label للحقل title، وتصبح help له description، بينما تُحتفظ بـdefault كتعليق توضيحي. ويكون title الخاص بالمخطط هو عنوان المكوّن. لا تكون الحقول مطلوبة أبدًا، والمنطق الشرطي ليس جزءًا من المخطط.

تستخدم القيود الكلمات المفتاحية التي يتحقق منها rest_validate_value_from_schema() فقط، لذا يعمل المخطط كما هو كمخطط إدخال لمسار REST أو كقدرة:

PHP
$values = $block['attrs']['blockstudio']['attributes'] ?? [];
$schema = bs_block_schema($block['blockName']);
if ($schema !== null) {
  $result = rest_validate_value_from_schema($values, $schema);
}

يصف المخطط نموذجًا واحدًا لكل حقل؛ كما يقبل التحقق الأشكال المستوردة مثل كائنات الخيارات والسلاسل الرقمية وكائنات المعرّفات. ولا يحل محل bs_validate_block(): فتعارضات التعريف مشكلات في الإعدادات، وقد تؤدي إلى نتائج حتى عند حذف المفتاح المتعارض. ويمكن لمرشحات التحقق أيضًا فرض قواعد خاصة بالموقع. استخدم bs_validate_block() للتحقق من المحتوى المخزّن. ويمكن للمواقع التي تستخدم محللًا مخصصًا وقت العرض تكييف المخطط باستخدام المرشح blockstudio/blocks/attributes/schema.

دوال PHP

دون بيانات

بأبسط صورة، تقبل الدالة قيمة واحدة هي معرّف الكتلة المطلوب عرضها على الصفحة.

PHP
bs_render_block('blockstudio/cta');

مع بيانات

لعرض الكتلة ببيانات مخصصة، استخدم مصفوفة بدلًا من قيمة مفردة للمعامل الأول. وستُمرر القيمة في مفتاح البيانات إلى متغير $a و$attributes داخل قالب الكتلة.

PHP
bs_render_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
]);

التداخل

يمكن تداخل الكتل بعضها داخل بعض باستخدام الدالة bs_block مع المتغير القوي $content داخل قوالب الكتل.

PHP
<div>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => bs_block([
    'id' => 'blockstudio/button',
    'data' => [
      'text' => 'Button Text',
    ]
  ])
]);

سيُعرض زر الكتلة مكان المتغير $content داخل قالب الكتلة.

تُخرج الكتل المضمّنة المعروضة باستخدام bs_render_block() أو bs_block() دائمًا HTML محلولًا للواجهة الأمامية، حتى عندما تعرض الكتلة الأصلية معاينة للمحرر. وتُحلّ مكوّنات القوالب الوهمية مثل <RichText /> و<InnerBlocks /> قبل إرجاع الكتلة المضمّنة.

فتحات متعددة

يمكن أيضًا إنشاء فتحات محتوى متعددة بجعل المتغير $content مصفوفة ترابطية، ثم استدعاء مفاتيحها المناسبة في الدالة bs_block.

PHP
<div>
  <?php echo $content['beforeContent']; ?>
  <h1><?php echo $a['title']; ?></h1>
  <p><?php echo $a['subtitle']; ?></p>
  <?php echo $content['afterContent']; ?>
</div>
PHP
echo bs_block([
  'id' => 'blockstudio/cta',
  'data' => [
    'title' => 'My title',
    'subtitle' => 'My subtitle',
  ],
  'content' => [
    'beforeContent' => bs_block([
      'id' => 'blockstudio/badge',
      'data' => ['text' => 'Before Content']
    ]),
    'afterContent' => bs_block([
      'id' => 'blockstudio/button',
      'data' => ['text' => 'Button Text']
    ])
  ]
]);

وسوم الكتل

ضمّن أي كتلة باستخدام صياغة وسم HTML. يتوفر تنسيقان:

HTML
<bs:acme-hero title="Welcome" />
<block name="acme/hero" title="Welcome" />

يعرض التنسيقان الكتلة نفسها. وتحول صياغة <bs:> الشرطة إلى فاصل مساحة أسماء (فتصبح acme-hero acme/hero). وتُجرّب الشرطات من اليسار إلى اليمين، ويُعتمد أول مرشح مسجل؛ لذا تُحلّ أيضًا المساحات التي تحتوي أسماؤها على شرطات: يحاول <bs:acme-ui-button> acme/ui-button ثم acme-ui/button. أما صياغة <block> فتأخذ اسم الكتلة الكامل بوصفه سمة name.

تعمل كتل Blockstudio وكتل WordPress الأساسية. وتُعرض كتل Blockstudio عبر مسار المعالجة الكامل (القوالب وTailwind والأصول). أما الكتل الأساسية فتُعرض عبر نظام عرض الكتل في WordPress باستخدام معالجات عرض الكتل المضمنة.

آلية العمل

تختلف طريقة عمل وسوم الكتل بحسب موضع ظهورها:

في قوالب الكتل ومحتوى المنشور، تُستبدل الوسوم بكتل HTML معروضة وقت التشغيل. ويكون الناتج هو الترميز النهائي للكتلة المشار إليها، مضمّنًا مباشرةً في الصفحة. ولا توجد كتلة WordPress في المحرر لهذه الوسوم؛ فهي آلية للعرض فقط.

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

هذا التمييز مهم: تنتج وسوم الكتل في القوالب مخرجات، بينما تنتج الوسوم في الصفحات والأنماط وقوالب الموقع كتلًا أصلية.

في قوالب الكتل

تُعرض وسوم الكتل تلقائيًا داخل قوالب Twig وPHP. لا يلزم إعداد. ويشمل ذلك صيغتي <bs:> و<block>، بالإضافة إلى وسوم البادئة والاسم المستعار المسجلة، بحيث يمكن للقالب إصدارها مباشرةً بدلًا من استدعاء bs_render_block(). ويُعرض الناتج HTML مضمّنًا مباشرةً في مخرجات قالب الكتلة:

Twig
<div class="my-page">
  <bs:mytheme-card title="Featured" />
  <block name="core/separator" />
  <bs:core-paragraph>Rendered by WordPress</bs:core-paragraph>
  <block name="core/heading" level="2">Also WordPress</block>
  <theme-card title="Prefix shorthand" />
</div>

في محتوى المنشور

العرض على مستوى الصفحة (محتوى المنشور ومناطق الأدوات) اختياري:

JSON
{
  "blockTags": {
    "enabled": true
  }
}

أو عبر مرشح:

PHP
add_filter('blockstudio/settings/block_tags/enabled', '__return_true');

الصياغة

وسوم ذاتية الإغلاق:

HTML
<bs:mytheme-cta title="Get started" variant="primary" />
<block name="core/separator" />

وسوم مزدوجة مع محتوى داخلي:

HTML
<bs:mytheme-section layout="wide">
  <p>Content inside the block.</p>
</bs:mytheme-section>

<block name="core/group">
  <block name="core/paragraph">Inside a group.</block>
</block>

يمكنك المزج بين الصيغتين بحرية، كما يمكن تداخل إحداهما داخل الأخرى:

HTML
<bs:mytheme-section>
  <block name="core/heading" level="2">Title</block>
  <bs:mytheme-card title="Features" />
  <block name="core/paragraph">Description text.</block>
</bs:mytheme-section>

اختصارات البادئات

يمكن لوسوم الكتل أيضًا استخدام اختصارات بادئات خاصة بالمشروع. سجّل بادئة مع مساحة أسماء واحدة أو أكثر، وسيحلّ Blockstudio القيمة <prefix-slug> إلى أول كتلة مسجلة وفق ترتيب مساحات الأسماء:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components', 'bsui'];

  return $prefixes;
});
HTML
<theme-card title="Homepage" />
<theme-button label="Get started" />
<theme-ui-feature-matrix />

باستخدام المثال أعلاه، يُحلّ <theme-card> إلى theme-components/card، ويُحلّ <theme-button> بالرجوع إلى bsui/button عندما لا يكون theme-components/button مسجلًا، ويُحلّ <theme-ui-feature-matrix> إلى theme-components/ui-feature-matrix.

يمكن أيضًا تركيب البادئات. عندما لا تُحلّ علامة ذات بادئة مباشرةً، ويكون الجزء المتبقي من المعرّف نفسه علامة بادئة مسجلة، تتكرر عملية الحل، ما يتيح وضع بادئة العلامة التجارية فوق بادئة مساحة الاسم:

PHP
add_filter('blockstudio/block_tags/prefixes', function($prefixes) {
  $prefixes['theme'] = ['theme-components'];
  $prefixes['ui'] = ['bsui'];

  return $prefixes;
});
HTML
<theme-ui-input />

لا يحتوي <theme-ui-input> على كتلة theme-components/ui-input، لذا ينتقل الحل إلى بادئة ui ويُحلّ bsui/input. تكون المطابقات المباشرة لها الأولوية دائمًا على الحل المتداخل، وتُطبّق قواعد السماح والمنع على الكتلة التي يُحلّ إليها أخيرًا.

يمكنك أيضًا ضبط البادئات في blockstudio.json:

JSON
{
  "blockTags": {
    "prefixes": {
      "theme": ["theme-components", "bsui"]
    }
  }
}

يجب أن تتكون البادئات من أحرف إنجليزية صغيرة أو أرقام، وأن تبدأ بحرف، وألا تحتوي على شرطات. تكون للأسماء البديلة الصريحة من blockstudio/block_tags/tag_aliases الأولوية على حل البادئات. تُترك العلامات ذات البادئات غير المعروفة كما هي.

تظل علامات البادئات والأسماء البديلة وسائل مساعدة معتمدة للتأليف. أما الصيغة المعتمدة والقابلة للنقل فهي دائمًا <bs:namespace-slug>، لأنها تسجل اسم الكتلة الفعلي دون الاعتماد على عوامل تصفية المشروع:

HTML
<bs:theme-components-card />
<bs:bsui-input />

تستخدم أمثلة Blockstudio والتشخيصات المُنشأة والمخرجات البرمجية هذه الصيغة المعتمدة. ويمكن للمشاريع التي تريد إزالة صيغة مختصرة قديمة استخدام أداة ترحيل العلامات إلى الصيغة المعتمدة المستقلة، التي تبدأ بتشغيل تجريبي، دون تشغيل WordPress.

الكتل الأساسية

يمكن استخدام أي كتلة لها عارض مسجل:

HTML
<bs:core-paragraph>A paragraph</bs:core-paragraph>
<bs:core-heading level="2">A heading</bs:core-heading>
<bs:core-separator />
<bs:core-image url="photo.jpg" alt="Photo" />
<bs:core-buttons>
  <bs:core-button url="/about">About</bs:core-button>
</bs:core-buttons>

أو باستخدام صياغة <block>:

HTML
<block name="core/group">
  <block name="core/columns">
    <block name="core/column">
      <block name="core/paragraph">Left column</block>
    </block>
    <block name="core/column">
      <block name="core/paragraph">Right column</block>
    </block>
  </block>
</block>

قوائم السماح والمنع

تحكّم في الكتل التي يمكن عرضها عبر العلامات:

JSON
{
  "blockTags": {
    "enabled": true,
    "allow": ["mytheme/*", "core/*"],
    "deny": ["mytheme/internal-*"]
  }
}

يقصر allow النتائج على الأنماط المطابقة فقط. ويستبعد deny الأنماط المطابقة وله الأولوية. يدعم كلاهما أحرف البدل * عبر fnmatch(). وينطبق ذلك على الصياغتين وعلى العرض على مستوى القالب والصفحة.

عوامل التصفية: blockstudio/block_tags/allow وblockstudio/block_tags/deny.

تمرير HTML

تُمرر السمات التي تبدأ بـ data- إلى العنصر الجذر للكتلة المعروضة. وتُمرر أيضًا السمات التي تبدأ بـ html- بعد إزالة البادئة. يعمل ذلك مع الصياغتين. تستبدل سمة التمرير القيمة الحالية للعنصر الجذر بدلًا من دمجها معها، لذا تستبدل html-class أصناف الكتلة نفسها.

تضع كتلة Blockstudio أيضًا السمات العامة التي لم تُعرّف كحقول على عنصرها الجذر: id وstyle وrole وtitle وlang وdir وhidden وtabindex وكل سمة aria-*. تكون الأولوية دائمًا للحقل المُعرّف، لذا تتلقى الكتلة التي تحتوي على حقل title القيمة الموجودة في $a['title'] بدلًا من ذلك. تمر الأنماط المُمررة عبر safecss_filter_attr()، وينطبق عامل التصفية WordPress على سمات الأنماط في محتوى المنشور، وتُضاف هذه الأنماط إلى أي نمط يحدده القالب مسبقًا.

قيم السمات هي HTML، لذا تُفك ترميز الكيانات مرة واحدة عند تحليل العلامة: تصل title="Tom &amp; Jerry" إلى القالب بصيغة Tom & Jerry ثم تُرمّز مجددًا عند الإخراج. قد تحتوي القيم الموضوعة بين علامتي اقتباس على >، كما في متغيرات Tailwind ومحددات الحركة، سواء في العلامات ذاتية الإغلاق أو المزدوجة.

لا تصل أي سمة أخرى لم تُعرّفها الكتلة، بما فيها class، إلى HTML. عند تفعيل WP_DEBUG، يعرض Blockstudio تقريرًا بكل سمة من هذا النوع مرة واحدة لكل طلب عبر _doing_it_wrong(). عرّف لها حقلًا، أو اكتبها كسمة data- أو aria- أو html-.

HTML
<bs:mytheme-card
  title="My Card"
  html-class="featured-card"
  html-id="main-card"
  data-analytics="card-click"
/>

<block name="core/paragraph" html-class="highlight" data-section="intro">
  Highlighted paragraph.
</block>

العوارض المخصصة

سجّل عوارض كتل مخصصة لإضافة أنواع أخرى من الكتل. تتلقى العوارض مصفوفة السمات وسلسلة المحتوى الداخلي، وتعيد مصفوفة كتل WordPress:

PHP
add_filter('blockstudio/block_tags/builders', function ($builders, $parser) {
    $builders['myplugin/custom-block'] = function (array $attrs, string $inner_content) {
        $html = '<div class="my-block">' . $inner_content . '</div>';
        return [
            'blockName'    => 'myplugin/custom-block',
            'attrs'        => $attrs,
            'innerBlocks'  => [],
            'innerHTML'    => $html,
            'innerContent' => [$html],
        ];
    };
    return $builders;
}, 10, 2);

بالنسبة إلى كتل الحاويات التي تحتاج إلى تحليل المحتوى الداخلي إلى كتل فرعية، أضف إدخالًا ثانيًا ضمن عامل التصفية نفسه:

PHP
$builders['myplugin/wrapper'] = function (array $attrs, string $inner_content) {
    $inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks($inner_content);
    $content = ['<div class="my-wrapper">'];
    foreach ($inner_blocks as $block) {
        $content[] = null;
    }
    $content[] = '</div>';
    return [
        'blockName'    => 'myplugin/wrapper',
        'attrs'        => $attrs,
        'innerBlocks'  => $inner_blocks,
        'innerHTML'    => '<div class="my-wrapper"></div>',
        'innerContent' => $content,
    ];
};

ينطبق blockstudio/block_tags/builders على علامات الكتل والكتل المخصصة المحددة عبر blockstudio/parser/element_mapping. وهذا هو الخطّاف المناسب لمشروع يستخدم تعيين العناصر إلى الكتل عندما يحتاج إلى نقل النص الداخلي إلى حقل Blockstudio أو إنشاء مصفوفة كتل مخصصة.

يتلقى blockstudio/block_tags/renderers وblockstudio/parser/renderers السجل نفسه وبنية الاستدعاء نفسها. ويظلان متاحين للتوافق ولتجاوزات المحلل النهائية. تعمل عوامل التصفية بهذا الترتيب:

  1. blockstudio/block_tags/builders
  2. blockstudio/block_tags/renderers
  3. blockstudio/parser/renderers

يمكن لعامل تصفية لاحق استبدال عارض سجّله عامل تصفية سابق.

الاستخدام البرمجي

طبّق عرض العلامات على أي سلسلة من PHP:

PHP
$html = apply_filters('blockstudio/block_tags/render', $content);

المكونات

تتكامل علامات الكتل جيدًا مع المكونات. المكونات كتل لا تُعرض إلا برمجيًا ولا تظهر مطلقًا في المحرر.

HTML
<bs:mytheme-card title="My Card" description="Card content." />

المحلل

تُعالج علامات الكتل بواسطة ماسح سلاسل خفيف يحل محل DOMDocument. يتعامل المحلل مع صياغتي <bs:> و<block>، والعلامات المتداخلة ذات الاسم نفسه مع تتبع العمق، وقيم السمات الموضوعة بين علامتي اقتباس، وكتل الحاويات المتداخلة. صُمم خصيصًا لهذه الحالة، وتُظهر القياسات أنه أسرع من كل من DOMDocument وWP_HTML_Tag_Processor في WordPress، كما يتجنب المشكلات المعروفة في DOMDocument عند إزالة بادئات مساحة الاسم وتحويل السمات إلى أحرف صغيرة.

في الصفحات والأنماط وقوالب المواقع، يتعامل المحلل نفسه أيضًا مع عناصر HTML الخام (مثل <p> و<div> و<h1> وغيرها)، ويعيّنها إلى كتل WordPress الأساسية المقابلة.

عندما يعيّن ربط عنصر <p> إلى كتلة Blockstudio غير أساسية ومسجلة تعرّف سمة نص منسق content، يُمرر HTML الداخلي تلقائيًا إلى تلك السمة content، بما في ذلك العلامات المضمنة مثل code وimg المعيّنة إلى كتل على مستوى العنصر. يصبح الفقرة التي لا تحتوي إلا على صورة هي الكتلة التي يعيّن إليها <img>. أما علامات الكتل المتداخلة أو HTML على مستوى الكتلة فتعود إلى تحليل الكتل الداخلية المعتاد. يحتفظ <block name="core/shortcode"> بنص الرمز القصير الخاص به كمحتوى للكتلة.