الصفحات
الصفحات قوالب قائمة على الملفات، وتتم مزامنتها مع قاعدة بيانات WordPress كمنشورات.
المزامنة صريحة: شغّل wp bs pages sync أو استدعِ API للصفحات عندما تريد تطبيق تغييرات المصدر. لا يؤدي تحميل الواجهة الأمامية أو لوحة إدارة WordPress مطلقًا إلى اكتشاف الصفحات بالكامل أو تعديل منشوراتها.
يمكن تعريف الصفحات كمجلد page.json واحد، أو كملفات Markdown مستقلة، أو كمجموعة لها بيان pages.json. تفيد المجموعات في التوثيق وقواعد المعرفة ومكتبات الصفحات المقصودة أو أي مجموعة من الصفحات المتداخلة التي ينبغي إنشاؤها من الملفات.
page.json
لصفحة معرّفة عبر JSON، أضف ملف إعداد page.json:
{
"name": "about",
"title": "About Us",
"slug": "about-us",
"postType": "page",
"postStatus": "publish",
"templateLock": "all"
}
الخصائص
| الخاصية | النوع | الافتراضي | الوصف |
|---|---|---|---|
name |
string |
مطلوب | معرّف فريد للصفحة |
title |
string |
تلقائي من الاسم | عنوان الصفحة |
slug |
string |
مطابق للاسم | رابط URL للصفحة |
path |
string |
"." |
المسار المنطقي داخل مجموعة |
order |
integer |
0 |
ترتيب القائمة للمنشور المتزامن |
postType |
string |
"page" |
نوع المنشور WordPress |
postStatus |
string |
"draft" |
حالة المنشورات الجديدة (publish، draft، pending، private) |
postId |
integer |
– | تثبيت الصفحة بمنشور محدد ذي معرّف WordPress |
blockEditingMode |
string |
– | وضع تحرير الكتل: "default" أو "contentOnly" أو "disabled" |
templateLock |
string|false |
"all" |
وضع القفل: "all" أو "insert" أو "contentOnly" أو false |
templateFor |
string|null |
null |
تعيينه قالبًا افتراضيًا لنوع منشور |
sync |
boolean |
true |
ما إذا كان بإمكان التسوية الصريحة العادية إنشاء المنشور أو تحديثه |
render |
string|object|false |
– | عرض الصفحة باستخدام عارض صفحات مسجل (راجع صفحات المكونات) |
تشمل المفاتيح المعروفة عبر page.json والبيانات الوصفية في مقدمة الملف وإدخالات المُحمّل: blockEditingMode وcollection وcontent وcontentType وdefaults وfile وhtml وmarkdown وmeta وname وorder وpath وpostId وpostStatus وpostType وpostTypeArgs وrender وslug وtemplate وtemplateFor وtemplateLock وtitle. ويُخزَّن أي مفتاح غير وارد أعلاه ضمن مصفوفة meta الخاصة بالصفحة.
مصادر المحتوى
يحدد تعريف الصفحة أي منشور WordPress ينبغي أن يوجد. ويحدد مصدر المحتوى ترميز الكتل الذي يُكتب في ذلك المنشور.
عندما يحتوي مجلد الصفحة على page.json، يبحث Blockstudio عن ملف مصدر مجاور بهذا الترتيب:
| الملف | الاستخدام |
|---|---|
index.php |
ترميز كتل شبيه بـHTML، يُقرأ كما هو (لا يُنفَّذ كود PHP) |
index.blade.php |
محتوى قالب Blade |
index.twig |
محتوى قالب Twig |
index.md |
محتوى Markdown |
يمكن أن يوفّر page.json أيضًا محتوى markdown أو html مضمنًا بدلًا من ملف مجاور:
{
"name": "intro",
"title": "Intro",
"markdown": "# Intro\n\nThis page is generated from inline markdown."
}
{
"name": "notice",
"title": "Notice",
"html": "<h1>Notice</h1><p>This page is generated from inline HTML.</p>"
}
تضيف المجموعات وضعين آخرين للمصدر:
- ملفات Markdown التي يُكتشف وجودها مباشرةً من شجرة المجموعة.
- إدخالات أداة التحميل المعادة من
loader.php.
يمكن لإدخالات أداة التحميل استخدام markdown أو html أو content مع contentType. كما يمكنها الإشارة إلى file محلي أو template محلي. وتُستنتج أنواع مصادر الملفات والقوالب من الامتداد ما لم يُحدَّد contentType صراحةً.
قيم contentType المدعومة هي php وblade وtwig وmarkdown وhtml. ويُحوَّل Markdown أولًا إلى HTML، ثم يُحلَّل إلى كتل WordPress أصلية. أما مصادر PHP وBlade وTwig وHTML فتمر عبر محلل صفحات Blockstudio المعتاد.
الفئات في الكتل الأساسية
تصبح class الموجودة على عنصر HTML معيّن إلى كتلة أساسية هي className.
يمكن لوسم كتلة أساسية صريح استخدام className مباشرةً. ويحافظ الشكلان على الفئات في الغلاف المحفوظ للكتلة، إلى جانب الفئات التي ينشئها WordPress:
<p class="intro">Introduction</p>
<block name="core/group" className="feature">
<h2 class="title">Feature</h2>
</block>
إذا كانت الخاصيتان موجودتين، تكون className هي المعتمدة. ينطبق هذا التحويل على الكتل الأساسية فقط؛ أما تعيين الكتلة المخصصة فيُبقي حقل class دون تغيير. وتنتمي فئات أنماط الأزرار، مثل is-style-outline، إلى غلاف الزر لا إلى رابطه.
شغّل wp bs pages sync لتطبيق تصحيحات المحلل على الصفحات التي تمت مزامنتها سابقًا. تُكتشف ترقيات المحلل عند المزامنة الصريحة التالية دون الحاجة إلى تعديل ملف المصدر. وتحتفظ الصفحات المقفلة والصفحات التي تتضمن sync: false بحماياتها المعتادة؛ ولا تُجري طلبات الواجهة الأمامية هذه المزامنة أبدًا.
كتل WordPress المتسلسلة
يمكن أن تتضمن مصادر الصفحات والأنماط أيضًا كتلًا متسلسلة منسوخة من محرر الأكواد WordPress:
<!-- wp:paragraph {"className":"intro"} -->
<p class="intro">Introduction</p>
<!-- /wp:paragraph -->
عندما يحتوي المصدر على محدِّد كتلة <!-- wp:... -->، يستخدم Blockstudio محلل الكتل الأصلي لـ WordPress لمعالجة المصدر كله. وتحتفظ السمات والكتل المتداخلة والكتل الديناميكية مثل Query Loop وكتل Blockstudio ببنيتها المتسلسلة. أما HTML خارج تعليقات الكتل فيظل محتوى حرًا أصليًا من HTML؛ ولا يُحوَّل إلى كتل إضافية. لا تخلط وسوم كتل HTML الخاصة بـ Blockstudio بهذا التنسيق وتتوقع تحويلها. تعليقات HTML العادية لا تحدد وضع الكتل المتسلسلة.
صفحات Markdown
استخدم Markdown عندما تريد أن يكون النص في ملفات، مع بقائه محتوى كتل WordPress قابلًا للتحرير بعد المزامنة. يُحوَّل مصدر Markdown إلى ترميز كتل أثناء المزامنة. ويخزّن المنشور المتزامن الكتل، لا محتوى Markdown الخام.
يمكن استخدام Markdown بثلاث طرق:
| المصدر | هل البيانات الوصفية الأولية مطلوبة؟ | ملاحظات |
|---|---|---|
pages/example/index.md مستقل |
نعم | توفّر البيانات الوصفية الأولية هوية الصفحة. |
page.json مع index.md |
لا | يعرّف page.json الصفحة ويوفّر Markdown المحتوى. |
| Markdown داخل مجموعة | لا | تستنتج المجموعة name وpath من موقع الملف. |
يُتخطى ملف index.md مستقل بلا بيانات وصفية أولية لأن Blockstudio لا يملك هوية صفحة لمزامنتها. أما Markdown في المجموعة فلا يحتاج إلى بيانات وصفية أولية، لأن بيان المجموعة ومسار الملف يوفّران تلك الهوية.
---
name: about
title: About
slug: about
postStatus: publish
---
# About
This Markdown content is synced as native WordPress blocks.
يمكنك أيضًا إقران page.json مع index.md. في هذه الحالة، يعرّف page.json الصفحة ويوفّر index.md المحتوى. وتتجاوز البيانات الوصفية الأولية في index.md قيم page.json المطابقة لها.
{
"name": "docs-reference",
"title": "Reference",
"path": "reference",
"sync": true
}
---
title: API Reference
order: 20
---
# Reference
This page uses `page.json` with Markdown content.
بالنسبة إلى Markdown المجموعة، يصبح مسار الملف هو مسار الصفحة المنطقي ما لم تتجاوز البيانات الوصفية الأولية ذلك:
| الملف | المسار الافتراضي |
|---|---|
pages/docs/index.md |
. |
pages/docs/getting-started.md |
getting-started |
pages/docs/guide/install/index.md |
guide/install |
pages/docs/guide/install.md |
guide/install |
تُحفَظ مفاتيح البيانات الوصفية الأولية غير المعروفة في مصفوفة meta الخاصة بالصفحة. يتيح لك ذلك إرفاق بيانات مثل section أو description وقراءتها من PHP API.
يُحلَّل Markdown بصفته GitHub ذي نكهة Markdown. يُسمح بـHTML الخام، وتُزال الروابط غير الآمنة، وتُمنح العناوين التي لا تحتوي على معرّف صريح معرّفًا ثابتًا. وتتطلب البيانات الوصفية الأولية المتداخلة YAML محلل YAML المضمّن.
Markdown خام
يمكن لمصادر ملفات Markdown إتاحة مصدرها الأصلي Markdown للأدوات الخارجية ومستهلكي الوثائق. لا يملك Markdown المضمن ملف مصدر، لذا تتم مزامنته إلى كتل لكنه لا ينتج استجابة .md خام.
اطلب الصفحة بلاحقة .md، مثل https://example.com/docs/reference.md. أو أرسل ترويسة Accept: text/markdown إلى الصفحة URL العادية:
curl -H "Accept: text/markdown" https://example.com/docs/reference/
تُحذف البيانات الوصفية الأولية من الاستجابة. وترسل استجابات Markdown الخام الناجحة Content-Type: text/markdown وX-Robots-Tag: noindex وترويسة Link أساسية إلى صفحة HTML. وتُرجع المسارات .md غير الموجودة استجابة 404 فعلية.
يعمل التفاوض مع العرض المسبق الثابت: فالطلب الذي تحتوي ترويسة Accept فيه على text/markdown لا تُجاب عنه مطلقًا من مخزن العرض المسبق أو من إضافة التقديم المبكر، بل يصل إلى WordPress والمعالج Markdown. وترسل استجابات HTML المعروضة مسبقًا، وHTML لصفحة تفاوض أيضًا على Markdown، وMarkdown الذي تتم الإجابة عنه عبر Accept، قيمة Vary: Accept، لذا تُبقي ذاكرات التخزين المؤقت التي تراعي Vary الاستجابتين منفصلتين. ويحتاج CDN الذي يعتمد في مفتاح ذاكرته المؤقتة على URL وحده إلى قاعدة خاصة به لتجاوز التخزين المؤقت لهذه الطلبات. ويُبلغ Pages::negotiates_markdown( $post_id ) عما إذا كانت الصفحة تجيب عن طلبات Markdown.
تحافظ Markdown المجموعة على بنية URL نفسها لـMarkdown الخام:
| صفحة URL | Markdown URL خام |
|---|---|
/docs/ |
/docs.md |
/docs/getting-started/ |
/docs/getting-started.md |
/docs/guide/install/ |
/docs/guide/install.md |
عطّل استجابات Markdown الخام باستخدام المرشح blockstudio/pages/serve_markdown:
add_filter( 'blockstudio/pages/serve_markdown', '__return_false' );
لا تُرجع .md URL الذي لا يُطابق صفحة مدعومة بـMarkdown استجابة 404 إلا عندما يقع المسار ضمن مجموعة صفحات. أما خارج جميع المجموعات، فيترك Blockstudio الطلب كما هو لتتعامل معه WordPress والإضافات الأخرى.
صفحات المكوّنات
يُعرض المكوّن عبر عارض صفحات بدلاً من تخزينه ككتل. لا يأتي Blockstudio مزودًا بعارض. ويسجّل قالب أو إضافة عارضًا لملفات الإدخال التي يتعامل معها، مثل عارض React لـpage.tsx، وتستدعيه Blockstudio مع الصفحة ومقالة WordPress ومحتوى الخانة المعروض.
pages/legal-notice/
page.json
page.tsx
data.php
{
"name": "legal-notice",
"title": "Legal Notice",
"slug": "legal-notice",
"postStatus": "publish",
"render": { "entry": "page.tsx", "data": "data.php" }
}
يُحدَّد render صراحةً. يظل الدليل الذي يحتوي على index.php وpage.tsx دون render صفحة عادية، لذا فإن إضافة عارض لا تعرض الصفحة الموجودة مرتين أبدًا. والصيغ هي:
| القيمة | المعنى |
|---|---|
"page.tsx" |
إدخال فقط، دون مُحمّل بيانات |
{ "entry": "page.tsx", "data": "data.php" } |
إدخال ومُحمّل بيانات |
{ "entry": "page.tsx", "renderer": "react" } |
إدخال مع معرّف عارض صريح |
false |
دون عارض، حتى عندما تحدد المجموعة عارضًا افتراضيًا |
تُحلّ المسارات نسبةً إلى دليل الصفحة، أو إلى جذر المجموعة في حالة إدخالات المُحمّل. ويجب أن تبقى داخل مصدر الاكتشاف ما لم يسمح blockstudio/pages/allow_external_loader_path بذلك. إذا لم يوجد renderer، فسيُستخدم العارض الذي يتولى امتداد الإدخال. ويُعدّ render الذي يشير إلى إدخال أو ملف بيانات مفقود، أو إلى عارض غير معروف، أو إلى امتداد لا يتولاه أي عارض، خطأً في الاكتشاف، ما يؤدي إلى فشل المصالحة قبل حذف أي شيء.
ما يخزنه التزامن
يخزّن التزامن كتلة blockstudio/page واحدة. وعندما يحتوي دليل الصفحة أيضًا على مصدر index.*، يُحلَّل ذلك المصدر مثل أي مصدر صفحة ويصبح الكتل الداخلية للكتلة، أي خانتها:
<!-- wp:blockstudio/page /-->
<!-- wp:blockstudio/page -->
<!-- wp:paragraph -->
<p>[download_checkout]</p>
<!-- /wp:paragraph -->
<!-- /wp:blockstudio/page -->
احتفظ بالمحتوى الذي تديره WordPress، مثل الرموز القصيرة، في الخانة. ويُخزَّن المصدر الذي لا يحتوي إلا على رمز قصير واحد، مثل [download_checkout]، ككتلة core/shortcode، كي لا يُضاف أي فقرة حول مخرجاته. ويظل في post_content، بحيث تراه فحوصات has_shortcode()، وتندمج كتل الخانات ذات المفاتيح مع تغييرات المحرر كما تندمج الكتل المتداخلة ذات المفاتيح، كما يوسّع do_shortcode الرموز القصيرة مرة واحدة عند أولوية the_content المعتادة، بعد أن يضعها العارض داخل إطار.
يُخزَّن تعريف العرض مع المقالة كمسارات theme: قابلة للنقل. وتغطي بصمة الصفحة التعريف، لا بايتات الإدخال أو مُحمّل البيانات: فتحرير page.tsx أو data.php لا يغيّر المقالة، وتصل التغييرات إلى الزوار عبر العرض والرسم البياني للعرض المسبق الثابت، الذي يسجل الإدخال ومُحمّل البيانات وكل ملف يبلّغ عنه العارض.
تسجيل عارض
سجّل العارضات في الإجراء blockstudio/pages/renderers. يُنفَّذ مرة واحدة لكل طلب، قبل أول عملية اكتشاف أو عرض، لذا ترى طلبات wp bs pages sync والواجهة الأمامية السجل نفسه.
add_action(
'blockstudio/pages/renderers',
static function (): void {
Blockstudio\Page_Renderers::register(
'react',
array(
'extensions' => array( 'tsx' ),
'layouts' => array( 'layout.tsx' ),
'render' => 'my_theme_render_page',
)
);
}
);
تكون معرّفات العارضات بأحرف صغيرة. ولا يمكن أن يتبع الامتداد أو اسم التخطيط إلا عارض واحد، ويظل layout.php تخطيطًا خاصًا بـBlockstudio. وتتلقى الدالة القابلة للاستدعاء طلبًا واحدًا:
| المفتاح | القيمة |
|---|---|
kind |
page، أو layout لتخطيط عارض واجهة |
renderer |
معرّف العارض |
entry |
مسار الإدخال المطلق |
data |
مسار مُحمّل البيانات المطلق، أو null |
page |
بيانات الصفحة القياسية، بما فيها meta |
post_id |
معرّف مقالة WordPress |
slot |
محتوى الخانة المعروض، أو محتوى الصفحة للتخطيط |
context |
frontend أو rest أو feed أو cli |
ويُعيد HTML والملفات التي قرأها العرض والأصول الاختيارية:
function my_theme_render_page( array $request ): array {
return array(
'html' => '<main>...</main>',
'dependencies' => array( '/abs/path/to/a/file/the/render/read.tsx' ),
'assets' => array( array( 'path' => '/abs/path/to/page.js' ) ),
);
}
يأتي context من نوع الطلب، وليس من الزائر، لذلك لا يمكن لعارض أن يخلّ بتطابق البايتات بين المستخدمين المسجلين والمجهولين بقراءته. إذا أخفق العارض، فإنه يرمي خطأً: لا تُعرض الصفحة بمحتوى فارغ. في معاينة المحرر REST، تعرض الكتلة الخطأ في إشعار بدلًا من ذلك. بعد نجاح العرض، يتلقى الإجراء blockstudio/pages/rendered الصفحة وHTML وتبعياتها.
يسرد assets ملفات البرامج النصية والأنماط التي تحتاج إليها الصفحة. وتخضع لمعالجة أصول الكتل (اصطلاح *.inline.*، ووحدات ES، والتصغير، و?ver)، ثم تطبعها الصفحة مرة واحدة عبر المخزن المؤقت نفسه الذي يطبع أصول الكتل، لتتضمنها الصفحة المعروضة مسبقًا. يمكن للأصل تعيين version لاستبدال قيمة ?ver الخاصة به. ويمكن للتعليمات البرمجية خارج العارض استخدام القناة نفسها عبر Blockstudio\Assets::register_owner()، الذي يعيد تعليق العلامة المراد طباعته.
المحرر
في المحرر، تعرض blockstudio/page معاينةً للصفحة معروضة على الخادم، وتكون الخانة فيها كتلًا داخلية تتبع templateLock الخاص بالصفحة. لا يمكن إدراج الكتلة أو تكرارها أو تضمينها داخل كتلة أخرى.
مجموعات الصفحات
المجموعة مجلد يحتوي على بيان pages.json. وهي تجمع مصادر صفحات عديدة تحت مقطع مجموعة واحد، وتطبّق القيم الافتراضية، وتدعم المسارات المتداخلة، ويمكنها تسجيل نوع منشور مخصص تلقائيًا.
pages/
docs/
pages.json
layout.php
index.md
guide/
install/
index.md
reference/
page.json
index.md
loader.php
{
"collection": "docs",
"title": "Documentation",
"postType": "bs_docs",
"postTypeArgs": {
"label": "Docs",
"rewrite": {
"slug": "docs"
},
"supports": ["title", "editor", "page-attributes"]
},
"defaults": {
"postStatus": "publish",
"templateLock": "contentOnly"
}
}
| الخاصية | النوع | الوصف |
|---|---|---|
collection / slug / name |
string |
اسم المجموعة المختصر. يُعد collection أوضح صيغة، ويصبح أساس URL العام. |
title |
string |
عنوان المجموعة بصيغة مقروءة للبشر. |
postType |
string |
نوع المنشور للصفحات المُنشأة. القيمة الافتراضية هي page. وإذا لم يكن موجودًا، فإن Blockstudio يسجله. |
postTypeArgs |
object |
الوسائط الممررة إلى register_post_type() عندما يسجل Blockstudio نوع منشور المجموعة. |
defaults |
object |
خصائص الصفحة الافتراضية المطبقة على كل صفحة في المجموعة. لا ينطبق render الافتراضي على الصفحة إلا إذا كان مدخله موجودًا في دليل الصفحات. |
scope |
string |
collection (افتراضي) أو site. راجع مجموعات الموقع. |
meta |
object |
بيانات وصفية مخصصة للمجموعة. تُخزَّن أيضًا مفاتيح البيان غير المعروفة في meta. |
مسارات صفحات المجموعة هي مسارات منطقية. تتم مزامنة الصفحة ذات path: "guide/install" كصفحة فرعية لـguide، وتتم مزامنة guide كصفحة فرعية لجذر المجموعة عند وجود تلك الصفحات الأصلية.
إذا احتوت مجموعة هرمية على صفحة متداخلة من دون وجود مصدر لصفحة وسيطة أصلية، فإن Blockstudio ينشئ صفحة حاوية فارغة لذلك المسار، مما يحافظ على اكتمال التسلسل الهرمي لـWordPress. أما أنواع المنشورات غير الهرمية (التي لا تدعم العنصر الأصل page-attributes) فلا تنشئ حاويات فارغة. وهي توجّه الصفحات استنادًا إلى مسار المجموعة المخزّن، لذا يمكن أن تتعايش المسارات المتداخلة مثل guide/install وsetup/install حتى لو انتهى كلاهما بـinstall.
أنواع منشورات المجموعة وعناوين URL
عيّن postType في بيان المجموعة لمزامنة كل صفحة في المجموعة مع نوع المنشور هذا. لا حاجة إلى تكرار القيمة نفسها داخل defaults. ويمكن للصفحات الفردية أن تتجاوز postType في البيانات الوصفية الأولية أو page.json.
عندما لا يكون نوع المنشور موجودًا، يسجّله Blockstudio باستخدام show_in_rest: true وإعداد محرر شبيه بالصفحات، مع مقطع المجموعة كأساس URL العام. ويمكن لـpostTypeArgs تجاوز وسائط التسجيل. تُحدَّث قواعد إعادة كتابة نوع منشور المجموعة تلقائيًا عند تغير أنواع منشورات المجموعات المسجلة أو وسائط إعادة الكتابة، لذا لا تحتاج إلى إعادة حفظ الروابط الدائمة لـWordPress.
تستخدم عناوين URL الخاصة بالمجموعة مقطع المجموعة بالإضافة إلى path المنطقي لكل صفحة:
| مسار المصدر | URL العام |
|---|---|
path: "." |
/docs/ |
path: "getting-started" |
/docs/getting-started/ |
path: "guide/install" |
/docs/guide/install/ |
يعمل نموذج URL هذا مع أنواع منشورات المجموعات الهرمية وغير الهرمية. كما يعيد Blockstudio توجيه عناوين URL المكررة مثل /docs/docs/ أو /docs/docs/getting-started/ إلى URL الأساسي.
تتيح صفحات المجموعة Markdown خامًا عبر عناوين URL نفسها (راجع Markdown الخام).
إذا غيّرت المجموعة من postType: "page" إلى نوع منشور مخصص، ينقل Blockstudio منشورات المجموعة التي تمت مزامنتها بالفعل إلى النوع الجديد في مواضعها عندما تتطابق هوية الصفحة المخزنة. ويحافظ ذلك على معرّفات المنشورات والبيانات الوصفية والمحتوى الحالي، مع تجنب تكرار المنشورات القديمة النوع. وتُنظَّف منشورات المجموعة القديمة عبر جميع حالات المنشور وفقًا للمرشح blockstudio/pages/orphan_action.
مجموعات الموقع
يجمع البيان الذي يحتوي على "scope": "site" كل صفحة تحته دون تحويلها إلى صفحات مجموعة. استخدمه في جذر شجرة صفحات الموقع لتطبيق الإعدادات الافتراضية المشتركة وسرد صفحات الموقع باستخدام blockstudio_page_tree( 'my-site' ).
{
"collection": "my-site",
"title": "My Site",
"scope": "site",
"defaults": {
"postStatus": "publish",
"templateLock": "all",
"render": { "entry": "page.tsx", "data": "data.php" }
}
}
تحتفظ صفحات مجموعة الموقع بهويتها نفسها تمامًا التي كانت لها قبل إضافة البيان، لذلك لا تؤدي إضافته إلى شجرة موجودة إلى تحديث صفوف المنشورات أو إنشاء أي شيء أو نقله إلى المهملات:
- تظل المفاتيح عامة: يظل كل من
Pages::get_page( 'home' )ومفاتيح الصفحات المخزنة متطابقًا. - تظل عناوين URL هي عناوين صفحات WordPress. ولا تنطبق قواعد إعادة كتابة المجموعات أو مرشح الروابط الدائمة أو إعادة التوجيه ذات URL المزدوج، ولا تُنشأ صفحات حاوية فارغة.
- تظل المسارات المنطقية والأسماء المختصرة والصفحات الرئيسية وهويات المصدر كما هي للصفحات المستقلة، وتُحدَّد التخطيطات وفق أقرب عنصر سلف.
- تحتفظ بيانات البيان المتداخلة من
pages.jsonبمجموعاتها الخاصة، وتُستثنى أشجارها الفرعية من مجموعة الموقع. - تُطبَّق الإعدادات الافتراضية لكل صفحة: لا ينطبق
renderالافتراضي إلا على الصفحات التي يحتوي دليلها على مدخله، لذا تحتفظ صفحات الرموز القصيرة وMarkdown بمصادرها.
أدوات تحميل المجموعات
يمكن أن تتضمن المجموعات أداة loader.php محلية موثوقة. استخدمها عندما تأتي صفحات المجموعة من مصدر محلي آخر، مثل مجلد توثيق خارجي أو حزمة أو بيان مُنشأ.
تعمل أداة التحميل أثناء اكتشاف الصفحات ومزامنتها صراحةً. وينبغي أن تكون حتمية ومحلية. تجنب جلب محتوى عن بُعد من loader.php، لأن ذلك سيجعل مزامنة النشر تعتمد على تلك الخدمة.
<?php
return array(
'meta' => array(
'source' => 'loader',
),
'paths' => array(
__DIR__ . '/external-docs',
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
'pages' => array(
array(
'name' => 'docs-api',
'title' => 'API',
'path' => 'api',
'content' => "# API\n\nGenerated markdown content.",
'contentType' => 'markdown',
),
array(
'name' => 'docs-template',
'title' => 'Template',
'path' => 'template',
'file' => __DIR__ . '/template.md',
),
),
);
يمكن لأداة التحميل أن تعيد مصفوفة تحتوي على المفاتيح pages وmeta وpaths:
| المفتاح | الوصف |
|---|---|
pages |
قائمة من مصفوفات الصفحات. تدعم كل صفحة المفاتيح المعروفة نفسها الموجودة في الواجهة الأمامية لكل من page.json وMarkdown. |
meta |
بيانات وصفية تُدمج في مصفوفة meta لكل صفحة ينشئها المُحمِّل. |
paths |
أدلة محلية إضافية لاكتشافها ضمن هذه المجموعة. يمكن أن تكون المدخلات سلاسل نصية أو كائنات مسارات. |
render |
تعريف العرض لكل صفحة Markdown يكتشفها paths. |
اختصارًا، يمكن لأداة التحميل إعادة قائمة مجردة من مصفوفات الصفحات.
يمكن لإدخالات صفحات أداة التحميل توفير المحتوى بالطرق التالية:
| البنية | الوصف |
|---|---|
markdown |
محتوى Markdown مضمن. |
html |
محتوى HTML مضمن. |
content + contentType |
محتوى عام مضمن. يجب أن يُحلّ contentType إلى markdown أو html. |
file |
مصدر ملف محلي. يُستنتج النوع من الامتداد ما لم يُحدَّد contentType. |
template |
اسم بديل لـfile. |
يمكن لمراجع الملفات في أداة التحميل الإشارة إلى مصادر PHP أو Blade أو Twig أو Markdown أو HTML. تُحل المسارات النسبية انطلاقًا من جذر المجموعة. ولا يُسمح بالمسارات المطلقة والمسارات الواقعة خارج جذر المجموعة إلا إذا سمح المرشح blockstudio/pages/allow_external_loader_path بها.
تكون القيمة الافتراضية لصفحات أداة التحميل هي generated: true. عندما تختفي صفحة أنشأتها أداة التحميل من مخرجاتها، يتعامل Blockstudio مع المنشور المتزامن كمنشور يتيم عند المزامنة التالية، وتتم تصفيته وفقًا للمرشح blockstudio/pages/orphan_action.
تُكتشف الأدلة المدرجة في paths كالمجلدات العادية للمجموعة. ويمكن أن تحتوي على ملفات Markdown أو مجلدات page.json. وإذا كانت تلك المسارات خارج جذر المجموعة، فسيُطبق مرشح المسارات الخارجية نفسه.
استخدم إدخالًا نصيًا عندما ينبغي أن يحتفظ الدليل الخارجي بمساراته المنطقية الخاصة. واستخدم إدخال كائن عندما ينبغي تركيب الدليل تحت بادئة مسار للمجموعة:
'paths' => array(
array(
'path' => __DIR__ . '/cli-docs',
'prefix' => 'cli',
'meta' => array(
'doc_set' => 'cli',
),
),
),
بهذا الإعداد، يصبح cli-docs/index.md هو path: "cli" ويصبح cli-docs/getting-started.md هو path: "cli/getting-started" في المجموعة. كما تجعل البادئات أسماء الصفحات المُنشأة آمنة من التعارض، بحيث يمكن لكل دليل مُضمَّن أن يحتوي على index.md أو getting-started.md. عيّن preserveNames إلى true في كائن المسار إذا كان ينبغي الاحتفاظ بقيم name الصريحة من الواجهة الأمامية لـpage.json أو Markdown.
خصائص كائن المسار:
| الخاصية | النوع | الوصف |
|---|---|---|
path |
string |
الدليل المحلي المراد اكتشافه. تُحل المسارات النسبية انطلاقًا من جذر المجموعة. |
prefix |
string |
بادئة مسار منطقية اختيارية داخل المجموعة. |
preserveNames |
boolean |
الإبقاء على أسماء الصفحات المحددة بدلًا من إنشاء أسماء من المسار ذي البادئة. القيمة الافتراضية هي false عند تعيين prefix. |
meta |
object |
بيانات وصفية تُدمج في كل صفحة يكتشفها هذا المسار. تسود البيانات الوصفية على مستوى الصفحة عند تكرار المفاتيح. |
render |
string|object |
تعريف عرض لصفحات Markdown في هذا المسار، ويحل محل render الخاص بالمُحمِّل. |
عرض Markdown عبر مكوّن
باستخدام render، تُعرض صفحات Markdown التي يكتشفها المُحمِّل عبر عارض صفحات بدلًا من تخزينها ككتل:
<?php
return array(
'paths' => array( __DIR__ . '/external-docs' ),
'render' => array(
'entry' => __DIR__ . '/document.tsx',
'data' => __DIR__ . '/document.php',
),
);
تظل صفحات Markdown: نوع المحتوى ومسار المحتوى واستجابات .md والواجهة الأمامية دون تغيير. يخزّن المزامن كتلة blockstudio/page واحدة، ويكون محتواها الداخلي HTML هو Markdown المحوّل، مع تنقيته عندما تنقّي المجموعة محتواها، بدلًا من الكتل المحللة، حتى يحافظ post_content على نص المستند. يتلقى العارض ذلك HTML بوصفه الخانة، ويمكنه قراءة المصدر من page.content_path. تُحل المسارات النسبية انطلاقًا من جذر المجموعة، وينطبق مرشح المسارات الخارجية كما ينطبق على المسارات. تُستثنى الصفحة إذا كانت واجهتها الأمامية تعيّن render الخاص بها أو render: false.
التخطيطات
يلتف ملف layout.php حول عرض الواجهة الأمامية لصفحة معتمدة على ملف. ولا يحل محل post_content المتزامن والمخزن في WordPress، كما لا يلتف حول لوحة المحرر. لا يعمل التخطيط إلا مع طلبات الواجهة الأمامية للصفحات الفردية.
للمجموعات، ضع layout.php بجانب pages.json ليحيط بكل صفحة في المجموعة على الواجهة الأمامية:
<?php $current = blockstudio_current_page(); ?>
<main class="docs-layout">
<aside>
<?php foreach (blockstudio_page_tree('docs') as $item) : ?>
<?php $is_current = ($item['post_id'] ?? null) === ($current['post_id'] ?? null); ?>
<a
href="<?php echo esc_url($item['permalink'] ?? '#'); ?>"
<?php echo $is_current ? 'aria-current="page"' : ''; ?>
>
<?php echo esc_html($item['title']); ?>
</a>
<?php endforeach; ?>
</aside>
<article>
<?php echo blockstudio_page_content(); ?>
</article>
</main>
يعرض blockstudio_page_content() متن الصفحة الذي يعرضه WordPress عادةً عبر the_content. إذا لم يُخرج التخطيط blockstudio_page_content()، فسيكون محتوى الصفحة مخفيًا عمدًا.
يمكن للتخطيطات استخدام دوال المساعدة الخاصة بالصفحة:
blockstudio_current_page();
blockstudio_page_collection('docs');
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_content();
يمكن أيضًا للصفحات المتداخلة غير التابعة لمجموعة أن ترث أقرب layout.php سلف لها ضمن شجرة pages. أما صفحات المجموعات، فيُخزَّن تخطيط جذر المجموعة في كل منشور متزامن، وتتم مراقبته ضمن بصمة الصفحة، لذا تُلتقط تغييرات التخطيط عند المزامنة التالية.
تخطيطات العارض
يمكن أن يكون التخطيط أيضًا مدخلًا للعارض، مثل layout.tsx لعارض يسجل layouts: ["layout.tsx"]. ويُعثر عليه في المواضع نفسها التي يُعثر فيها على layout.php، ويكون layout.data.php اختياري بجانبه هو مُحمِّل بياناته. عند العرض، يتلقى العارض kind: "layout" ومحتوى الصفحة المعروض على هيئة slot، وبأولوية the_content نفسها التي لدى layout.php. يمكن أن يحتوي الدليل على layout.php أو تخطيط عارض واحد، لا كليهما؛ فوجودهما معًا خطأ في الاكتشاف. يؤدي فشل التخطيط إلى إطلاق blockstudio/pages/layout_error وترك محتوى الصفحة دون تغليف، كما يحدث مع layout.php.
وضع تحرير الكتل
تتحكم الخاصية blockEditingMode في كيفية تحرير الكتل داخل المحرر. عيّن قيمة افتراضية على مستوى الصفحة في page.json، ثم تجاوزها لكل عنصر في القالب:
{
"name": "about",
"title": "About Us",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<h1 blockEditingMode="contentOnly">Editable Title</h1>
<p>This paragraph inherits "disabled" from the page default.</p>
<block name="core/buttons" blockEditingMode="default">
<block name="core/button" url="/contact">Fully editable button</block>
</block>
| القيمة | الوصف |
|---|---|
"default" |
تحرير كامل. يمكن تحديد الكتل ونقلها وتحريرها |
"contentOnly" |
تحرير النص فقط. يمكن تحرير نص الكتلة، لكن الإعدادات والبنية مقفلتان |
"disabled" |
بلا تحرير. لا يمكن التفاعل مع الكتل إطلاقًا |
تُعيَّن التجاوزات لكل عنصر باستخدام سمات HTML على أي عنصر (مثل <h1> و<p> و<div> وغيرها) أو على عناصر <block>. تُعيَّن كتل الحاوية السلفية للعناصر التي عليها تجاوزات تلقائيًا إلى contentOnly حتى تظل العناصر الفرعية متاحة. يصعد هذا التسلسل من العنصر الذي عليه تجاوز إلى جذر الصفحة، لذلك لا تحتاج إلا إلى تعيين blockEditingMode على العناصر التي تريد إتاحتها للتحرير.
قفل القالب
تتحكم الخاصية templateLock في كيفية تحرير المستخدمين للصفحة داخل المحرر:
| القيمة | إضافة/إزالة | نقل | تحرير المحتوى |
|---|---|---|---|
"all" |
لا | لا | لا |
"insert" |
لا | نعم | نعم |
"contentOnly" |
لا | لا | نعم |
false |
نعم | نعم | نعم |
عند تعيين templateLock، يعطّل Blockstudio إمكانية إلغاء قفل الكتل عبر UI في المحرر.
المسارات الافتراضية
لا تقف بعض المستندات خلف منشور: مثل مرجع مكوّن مُنشأ من البيانات، أو كتالوج، أو منطقة حساب. سجّلها كمسارات افتراضية بدلًا من ربط template_redirect بنفسك:
add_action( 'init', function () {
Blockstudio\Virtual_Routes::register(
'components',
function ( $component, string $rest ) {
get_header();
echo my_component_page( $component );
get_footer();
},
[
'prefix' => true,
'match' => fn ( string $rest ) => '' === $rest ? 'index' : my_component( $rest ),
'title' => fn ( $component ) => my_component_title( $component ),
'urls' => fn () => my_component_paths(),
]
);
} );
المسار نسبي إلى الصفحة الرئيسية للموقع. باستخدام prefix، يخدم المسار أيضًا كل المسارات الواقعة تحته، ويتلقى match الجزء المتبقي (كسلسلة فارغة للمسار نفسه)، ثم يعيد القيمة التي يتلقاها ردّ الاستدعاء المسؤول عن العرض، أو null لترك URL إلى WordPress، الذي يعيد عندها 404 كالمعتاد. يُخرج ردّ الاستدعاء المسؤول عن العرض المستند أو يعيده كسلسلة نصية؛ أما title فهو سلسلة نصية أو دالة إغلاق تتلقى قيمة المطابقة.
في الطلب المطابق، يمنع Blockstudio WordPress من الإبلاغ عن 404، ويمنع redirect_canonical من إعادة التوجيه إليه، ويمسح حالة الصفحة الفردية التي يُبلغ عنها الاستعلام الرئيسي، ويرسل رمز الحالة (status، والافتراضي 200)، ويعرض الصفحة بأولوية template_redirect Virtual_Routes::PRIORITY. يحدث ذلك مباشرةً بعد فتح مخزن الإخراج الخاص بـBlockstudio عند Assets::BUFFER_PRIORITY، كي يحصل المستند المكتمل على أصول الكتل وأصول UI المجمّعة وTailwind المترجم مثل أي صفحة، وقبل redirect_canonical عند الأولوية 10. ويجب أيضًا تشغيل المعالج الذي يعرض مستندًا كاملًا بمفرده بعد Assets::BUFFER_PRIORITY، وإلا فسيتم تخطي تلك المعالجة. تُضاف المسارات في urls (افتراضيًا، مسار المسار نفسه عندما لا يكون مسارًا ببادئة) إلى عمليات إنشاء إعادة العرض المسبق الثابت، ويعيدها Virtual_Routes::urls() كعناوين URL مطلقة لخريطة الموقع. يحل Virtual_Routes::match( $path ) المسار بالطريقة نفسها التي يُحل بها الطلب.
سلوك المزامنة
لا تتغير منشورات الصفحات إلا من خلال عملية مزامنة صريحة:
wp bs pages sync
يكتشف الأمر مخزون المصدر كاملًا، وينشئ المنشورات المتغيرة أو يحدّثها، ويحذف العناصر اليتيمة المؤكدة، ويحدّث توجيه المجموعات وإعدادات templateFor المترجمة، ثم يعرض تقريرًا بالتغييرات. أضف --authoritative لاستبدال المحتوى المُدار بدلًا من الاحتفاظ بمحتوى المحرر المرتبط بالمفاتيح، وأضف --full للإبلاغ عن أن العملية تسوية كاملة بصرف النظر عن هوية المصدر المحفوظة:
wp bs pages sync --authoritative --full
لا تنفّذ طلبات الواجهة الأمامية أو لوحة الإدارة أو AJAX أو REST أو cron أو طلبات تهيئة WP-CLI العامة اكتشافًا كاملًا للصفحات، أو استعلامًا عن مخزون التسوية المُدار، أو كتابةً لمنشورات الصفحات. بل تستخدم منشورات WordPress المتزامنة مسبقًا، إلى جانب إعدادات المجموعات وقوالب أنواع المنشورات الموجزة التي حفظتها آخر عملية صريحة. قد يفحص التثبيت أو الترقية لأول مرة ملفات تعريف المجموعات مرة واحدة لاستعادة بيانات التوجيه؛ ولا تؤدي عملية التهيئة هذه، المقتصرة على القراءة، إلى مزامنة المحتوى. نقطة نهاية تحديث Canvas الاختيارية والمصادق عليها هي API صريحة للتأليف: يستدعيها Canvas مرة عند فتح مساحة العمل كي تظهر المصادر الجديدة أو المتغيرة في المخزون الأولي. ويستدعي وضع Live نقطة النهاية نفسها عند رصد تغيير في مصدر الصفحة.
يسجّل Blockstudio\Pages::init() الآن الخطافات التي تعمل وقت الطلب فقط. يجب على عمليات التكامل التي كانت تمرر سابقًا وسيطة force إلى هذه الطريقة استدعاء Blockstudio\Pages::reconcile() أو تشغيل wp bs pages sync بدلًا من ذلك.
لمنع استبدال صفحة بعد تعديلها يدويًا، عيّن "sync": false في page.json.
مواضع المصدر القابلة للنقل
تُخزَّن ملفات السمات المتزامنة كمواضع نسبية إلى السمة بدلًا من مسارات التثبيت المطلقة. وتحتفظ ملفات السمات الفرعية وملفات السمات الأصلية بهويات منفصلة، حتى عند تطابق أسماء ملفاتها النسبية. مع ذلك، تظل مساعدات الصفحة تعرض قيم template_path وcontent_path وlayout_path وdirectory المطلقة بعد حلها للطلب الحالي.
يتيح ذلك استخدام CLI لمزامنة الملفات وطلبات الويب جذورًا مختلفة لنظام الملفات، كما في الاستضافات المقيّدة، دون التأثير في استجابات Markdown أو التخطيطات أو فحص Tailwind أو تتبّع مصدر العرض المسبق. تُعاد مواءمة مسارات القوالب المطلقة الموجودة عند قراءتها إذا ظل اسم مجلد القالب كما هو. لا يلزم إجراء مزامنة أو ترحيل قاعدة بيانات أو كتابة بيانات وصفية وقت الطلب لقراءتها؛ إذ تحفظ المزامنة الصريحة التالية المواقع القابلة للنقل.
إذا كان مجلد القالب رابطًا رمزيًا، كأن يشير إلى نسخة عمل للتطوير، فستُخزَّن مواقع theme: نفسها سواء قُرئ المصدر عبر الرابط الرمزي أو عبر هدفه، وستُحلّ هذه المواقع إلى مجلد القالب المُعدّ.
يظل دعم الملفات خارج القالبين النشطين، الفرعي والأصل، قائمًا باستخدام مساراتها المطلقة المُعدّة، مع مراعاة قيود open_basedir الخاصة بـPHP. ولا يمكن نقلها تلقائيًا: بعد نقل مصدر خارجي، حدّث مساره المُعدّ وأجرِ مزامنة صريحة.
ملكية حقول المقالة
يحدّد postStatus الحالة الأولية. وتحافظ عمليات المزامنة اللاحقة على الحالات الحالية، سواء كانت مسودة أو معلّقة أو خاصة أو منشورة أو مجدولة، بما في ذلك مع --authoritative. لا يُعاد نشر المسودة لمجرد أن ملفها يذكر postStatus: "publish". يظل سلوك استعادة العناصر اليتيمة كما هو: تعيد المزامنة الصريحة المقالة المدارة من المهملات إذا كان مصدرها موجودًا. اقفل الصفحة أو عطّل المزامنة لمنع استعادتها.
يظل الملف هو المرجع للعنوان والرابط المختصر ونوع المقالة والأصل وترتيب القائمة المُعدّ. لا يؤدي تعديل هذه الحقول في WordPress إلى تغيير تعريف المصدر. تعيد المزامنة الصريحة التالية تطبيق قيم الملف وتذكر الحقول المتأثرة في pages.<name>.overwritten، مع تحذير في مخرجات جدول CLI. وتظل أذونات WordPress الأصلية سارية، بما فيها الرابط المختصر الفارغ للمقالات المعلّقة عندما لا يستطيع المستخدم الذي يجري المزامنة نشرها.
استخدم blockstudio/pages/update_post_data لتكامل يملك صراحةً سياسة حالة مختلفة. تحافظ الكتل ذات المفاتيح على محتوى الكتل الذي يملكه المحرر؛ ولا تغيّر المفاتيح ملكية عنوان المقالة أو رابطها المختصر.
بالنسبة إلى صفحات المجموعات، تشمل البصمات ملف التعريف والمحمّل ومصدر الصفحة وملف التخطيط والبيانات الوصفية ومسارات المصدر ذات الصلة. تطبّق المزامنة الصريحة التالية التغييرات في هذه المدخلات.
عند إزالة مصدر مجموعة، يحذف Blockstudio الصفحة المُنشأة كي لا تبقى صفحات المجموعة القديمة بعد حذف ملف المصدر. افتراضيًا، تُنقل صفحات المجموعة اليتيمة إلى سلة المهملات. استخدم blockstudio/pages/orphan_action لإرجاع trash أو delete أو keep.
في طلبات الواجهة الأمامية، يهيئ Blockstudio سجل الصفحات من المنشورات المنشورة المتزامنة مسبقًا. تتوفر الصفحات المسودة والخاصة في سياقي الإدارة والمزامنة، لكن أدوات الواجهة الأمامية لا تهيئ إلا الصفحات المنشورة.
تسوية النشر
Blockstudio\Pages::reconcile() هو نقطة دخول النشر الخاصة بـPHP. يكتشف المخزون المطلوب كاملًا، ويقارن بصمات المصدر ومحرك المزامنة، ويعيد تقريرًا قابلًا للقراءة آليًا:
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
'renames' => [
[
'from' => 'pages/old/index.php',
'to' => 'pages/new/index.php',
],
],
]);
يتضمن التقرير discovered وcreated وupdated وunchanged وlocked وpreserved وremoved وremovedPages وfailed وfullReconciliation، ونتائج كل صفحة، وأخطاء الاكتشاف، وsourceIdentity حتميًا.
تتضمن الصفحات المقفلة status: "locked" وتُحصى منفصلةً عن الصفحات التي لم تتغير. يسرد removedPages لكل صفحة مُزالة name وkey وpostId وaction الفعلي (trash أو delete)؛ ولا تُحتسب المقالات المُبقية أو المنقولة مسبقًا إلى المهملات ضمن العناصر المُزالة حديثًا. كما تسمي مخرجات جدول CLI الصفحات المنشأة والمحدّثة والمقفلة والمزالة والمحفوظ محتواها، مع معرّفات مقالاتها.
بعد التحليل والدمج باستخدام المفاتيح، لا تستدعي المقالة النهائية المطابقة wp_update_post()، ولا تغيّر post_modified، ولا تنشئ مراجعة، ولا تطلق خطافات تحديث المقالة. وتكون نتيجتها unchanged. عندما يختلف محتوى المصدر عن محتوى المفاتيح الذي يملكه المحرر، يحدّد preserved: true هذا القرار، ويشمل إجمالي preserved في المستوى الأعلى هذه الحالة. ويظل تسجيل بصمة المصدر الجديدة والبيانات الوصفية المُدارة قائمًا، بحيث لا تفعل المزامنة التالية للمحتوى غير المتغير شيئًا. يُعد preserved علامة إضافية لا حالة حصرية: فقد تحافظ الصفحة على محتوى الكتل ذات المفاتيح مع تحديث عنوان يملكه الملف أو إضافة كتلة أخرى.
قد يمسح authoritative: true قفل Page Sync، ويستبدل المحتوى بتعريف الملف بدلًا من الاحتفاظ بمحتوى المحرر المرتبط بالمفاتيح. اتركه false لإجراء مزامنة صريحة عادية. إن plan_valid: false أو full: true أو broad: true أو غياب هوية المصدر السابقة أو تغيّر بصمة محرك المزامنة، يجعل العملية تسوية كاملة (fullReconciliation في التقرير). تقارن كل عملية المخزون كاملًا على أي حال. سجلات إعادة التسمية في Git تلميحات للهوية فقط؛ ولا تحل أبدًا محل مقارنة المخزون الكامل.
لا تؤدي البصمات المتطابقة مع مسارات تشغيل لم تتغير إلى كتابة المنشور أو بياناته الوصفية، ولا تُطلق خطافات التحديث. عندما ينتقل مصدر لم يتغير إلى دليل إصدار جديد، تحدّث التسوية مسارات القالب والمحتوى والتخطيط والدليل المحفوظة فقط؛ ولا تحدّث post_content أو طابع وقت تعديل المنشور. لا تُحذف الصفحات المُدارة المفقودة إلا بعد انتهاء عملية التسوية الكاملة دون أخطاء في الاكتشاف أو كتابة الصفحات.
لا تعتبر التسوية المباشرة عبر API عملية النشر ناجحة. بعد تفعيل الأثر الثابت المطابق ومساراته والتحقق منهما، احفظ الهوية المُعادة صراحةً:
Blockstudio\Pages::store_successful_source_identity(
$report['sourceIdentity']
);
يحفظ wp bs pages sync الهوية المُعادة بعد نجاح العملية. لا تسجل تهيئة WP-CLI العادية سوى أنواع منشورات المجموعات وقواعد إعادة الكتابة المحفوظة. ولا تكتشف الصفحات أو تزامنها.
تثبيت معرّف المنشور
افتراضيًا، يعيّن WordPress معرّفات المنشورات تلقائيًا. إذا حُذفت صفحة ثم أُنشئت من جديد، يتغير المعرّف، ما يؤدي إلى كسر المراجع الخارجية مثل القوائم أو الروابط المكتوبة مباشرةً.
استخدم postId لتثبيت الصفحة على معرّف محدد:
{
"name": "about",
"title": "About Us",
"postId": 42
}
عند إنشاء الصفحة، يمرر Blockstudio المعرّف إلى WordPress عبر import_id. إذا كان المعرّف متاحًا، يستخدمه WordPress كما هو. وإذا كان منشور غير ذي صلة يستخدم المعرّف بالفعل، يعيّن WordPress معرّفًا جديدًا تلقائيًا دون إشعار.
عند البحث عن الصفحات الموجودة، يتحقق Blockstudio من المعرّف المثبّت أولًا، قبل التحقق من البيانات الوصفية أو الاسم المختصر. وهذا يعني أنه إذا حُذفت صفحة ثم أعيدت مزامنتها، فستستعيد المعرّف نفسه.
دمج الكتل ذات المفاتيح
افتراضيًا، عندما يتغير ملف القالب، يستبدل Blockstudio محتوى المنشور بالكامل بالقالب الجديد. وهذا يعني فقدان أي تعديلات أُجريت في محرر WordPress.
أضف سمة key إلى الكتل للاحتفاظ بتعديلات المستخدمين بين عمليات مزامنة القالب. عندما يحتوي القالب على كتل ذات مفاتيح، يدمج Blockstudio تغييرات القالب مع محتوى المنشور الحالي بدلًا من استبداله.
إضافة المفاتيح
استخدم السمة key على أي عنصر HTML أو عنصر <block>:
<h1 key="title">Default Title</h1>
<p key="intro">Default intro text.</p>
<div key="features">
<p>First feature.</p>
<p>Second feature.</p>
</div>
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h2>Hero Title</h2>
<p>Hero description.</p>
</block>
<block
name="acme/testimonial"
key="featured-quote"
quote="Default quote"
/>
يجب أن تكون المفاتيح فريدة على مستوى القالب بأكمله. يحمي المفتاح الكتلة كاملةً وكل محتواها. لا حاجة إلى تعيين مفتاح لكل عنصر فرعي داخل كتلة ذات مفتاح. يمكن نقل الكتل ذات المفاتيح إلى أي موضع أو مستوى تداخل بين تحديثات القالب، مع الاحتفاظ بمحتوى المستخدم فيها.
تعمل المفاتيح بالطريقة نفسها مع الكتل المخصصة في Blockstudio. يُعد key بيانات وصفية بنيوية خاصة بـPage Sync؛ أما قيم الحقول المخصصة فتبقى سمات Blockstudio عادية. عندما يغيّر محرر هذه الحقول، تحتفظ مزامنة القالب اللاحقة بقيم المحرر مع مواصلة تطبيق تغييرات القالب المستقلة. تُرحّل الصفحات المنشأة بإصدارات أقدم، التي كان فيها المفتاح داخل بيانات الحقول المخصصة، تلقائيًا عند المزامنة التالية.
آلية الدمج
عندما يتغير ملف القالب وتُعاد مزامنة الصفحة:
| الكتلة | السلوك |
|---|---|
| كتلة ذات مفتاح | يُحتفظ بمحتوى المستخدم وقيم حقول Blockstudio. وتُطبّق السمات والبنية التي يتحكم بها القالب. |
| كتلة بلا مفتاح | تُستبدل بالكامل بنسخة القالب (كما يحدث دون مفاتيح) |
أمثلة
تُحفظ تعديلات المستخدم في الكتل ذات المفاتيح:
- يعرّف القالب
<p key="intro">Default intro.</p> - يعدّل المستخدم الفقرة في المحرر إلى "نص مقدمة مخصص."
- يحدّث المطور القالب ويضيف كتلة جديدة ويغيّر التخطيط
- عند المزامنة: تحتفظ الفقرة بنص "نص مقدمة مخصص." ويُطبّق التخطيط الجديد
تظل سمات القالب سارية:
- يحتوي القالب على كتلة غلاف بها
key="hero"وسمةurl - يغيّر المطور سمة
urlللغلاف إلى صورة خلفية جديدة - عند المزامنة: تُطبّق صورة الخلفية الجديدة، مع الاحتفاظ بتعديلات المستخدم للمحتوى داخل الغلاف
حالات خاصة
| السيناريو | السلوك |
|---|---|
| إضافة كتلة جديدة ذات مفتاح إلى القالب | تظهر بمحتوى القالب الافتراضي |
| إزالة كتلة ذات مفتاح من القالب | تُحذف من المنشور |
| تغيّر نوع الكتلة (مع بقاء المفتاح نفسه) | يسود القالب بالكامل، دون دمج المحتوى |
| مفاتيح مكررة | يُتعامل مع التكرار الثاني ككتلة بلا مفتاح |
| لا توجد مفاتيح في القالب | استبدال كامل (السلوك نفسه كما دون مفاتيح) |
| فرض المزامنة | استبدال كامل، مع تجاهل المفاتيح |
| منشور مقفل | لا تُجرى أي مزامنة |
الجمع بين عناصر التحكم في التحرير
تتيح لك المفاتيح وtemplateLock وblockEditingMode التحكم بدقة فيما يمكن للعملاء فعله وما لا يمكنهم فعله. إليك أنماط العمل الشائعة.
صفحة مقفلة بالكامل
يتحكم المطور في كل شيء. الصفحة تخطيط ثابت لا يستطيع العملاء لمسه إطلاقًا. يناسب ذلك الصفحات القانونية أو شروط الخدمة أو أي صفحة ينبغي ألا تتغير إلا عبر الكود.
{
"name": "terms",
"title": "Terms of Service",
"templateLock": "all"
}
<h1>Terms of Service</h1>
<p>Last updated: January 2025</p>
<p>These terms govern your use of our service...</p>
لا حاجة إلى مفاتيح. القالب هو المصدر الوحيد للحقيقة. تستبدل كل مزامنة الصفحة بالكامل.
تخطيط مقفل مع محتوى قابل للتحرير
هذا هو النمط الأكثر شيوعًا. اقفل بنية الصفحة كي لا يستطيع العملاء إضافة الكتل أو إزالتها أو إعادة ترتيبها، مع السماح لهم بتحرير النص في مواضع محددة. تضمن المفاتيح بقاء تعديلاتهم بعد تحديثات القالب.
{
"name": "landing",
"title": "Landing Page",
"templateLock": "all",
"blockEditingMode": "disabled"
}
<block name="core/cover" key="hero" url="https://example.com/bg.jpg">
<h1 blockEditingMode="contentOnly">Edit This Title</h1>
<p blockEditingMode="contentOnly">Edit this description.</p>
</block>
<div key="features">
<h2>Features</h2>
<p blockEditingMode="contentOnly">Editable feature intro.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
</block>
يمكن للعميل تحرير عنوان القسم الرئيسي ووصفه ومقدمة الميزات. ولا يمكنه تعديل أي شيء آخر. يتحكم المطور في نص الزر وURL وصورة خلفية الغلاف. عندما يحدّث المطور القالب (e.g.، ويضيف زرًا ثانيًا)، تحتفظ الأقسام ذات المفاتيح بنص العميل.
قالب متطور مع محتوى محفوظ
للصفحات التي تنمو بمرور الوقت. يضيف المطور أقسامًا جديدة إلى القالب، وتضيف كل مزامنة المحتوى الجديد دون المساس بما سبق أن خصصه العميل.
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<h1 key="title">Welcome</h1>
<p key="intro">Our introduction.</p>
<div key="services">
<h2>Our Services</h2>
<p>We offer great things.</p>
</div>
<div key="testimonials">
<h2>Testimonials</h2>
<p>What our clients say.</p>
</div>
<block name="core/buttons">
<block name="core/button" url="/contact">Get in Touch</block>
</block>
يظهر قسم الشهادات الجديد والزر عند المزامنة. وتبقى تعديلات العميل على العنوان والمقدمة والخدمات دون تغيير.
هيكل أولي لمرة واحدة
أنشئ صفحة ببنية أولية، ثم سلّمها بالكامل. عيّن sync إلى false كي لا تنشئ المزامنة العادية الصفحة أو تحدّثها مطلقًا، وأنشئها مرة واحدة باستخدام Blockstudio\Pages::force_sync('blog'). بعد ذلك، تصبح الصفحة ملكًا للعميل بالكامل.
{
"name": "blog",
"title": "Blog",
"sync": false
}
<h1>Our Blog</h1>
<p>Welcome to our blog. Start writing!</p>
يتخطى wp bs pages sync هذه الصفحة، لذا ينشئها force_sync() مرة واحدة. بعد ذلك، يمكن للعميل إضافة الكتل وإزالتها وإعادة ترتيبها بحرية. ويتم تجاهل تغييرات القالب.
ربط الكتل
بديلًا عن الدمج باستخدام المفاتيح، يمكنك استخدام ربط الكتل الأصلي في WordPress ربط الكتل API لربط الكتل ببيانات المنشور الوصفية. هذه ليست ميزة في Blockstudio، بل هي WordPress API أصلية. يمرر Blockstudio ببساطة سمة metadata إلى ترميز الكتل المُنشأ. يُخزّن المحتوى في البيانات الوصفية للمنشور بدلًا من ترميز الكتل، لذا يمكن لمزامنات القالب استبدال الترميز بحرية، لأن المحرر يقرأ المحتوى من البيانات الوصفية لا من innerHTML.
مرّر سمة metadata إلى أي عنصر HTML أو عنصر <block>:
<h1
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_title"}}}}'
>
Default Title
</h1>
<p
metadata='{"bindings":{"content":{"source":"core/post-meta","args":{"key":"hero_description"}}}}'
>
Default description text.
</p>
<img
metadata='{"bindings":{"url":{"source":"core/post-meta","args":{"key":"hero_image"}},"alt":{"source":"core/post-meta","args":{"key":"hero_image_alt"}}}}'
/>
يجب تسجيل مفاتيح البيانات الوصفية مع تفعيل show_in_rest:
register_post_meta( 'page', 'hero_title', array(
'show_in_rest' => true,
'single' => true,
'type' => 'string',
'default' => 'Default Title',
) );
المفاتيح مقابل الروابط
| الجانب | المفاتيح | الروابط |
|---|---|---|
| مكان تخزين المحتوى | ترميز الكتلة (post_content) |
البيانات الوصفية للمنشور (wp_postmeta) |
| البقاء بعد مزامنة القالب | نعم (مدمج حسب المفتاح) | نعم (البيانات محفوظة في البيانات الوصفية) |
إمكانية الاستعلام عبر WP_Query |
لا | نعم (meta_query) |
| متاح في REST API | لا | نعم |
| يتطلب التسجيل | لا | نعم (register_post_meta) |
| يمكن للمستخدم نقل الكتل | لا (يعيد القالب فرض البنية) | لا (يعيد القالب فرض البنية) |
يمكن استخدام النهجين معًا في القالب نفسه. استخدم المفاتيح للأقسام التي تهم فيها بنية الكتلة (مثل e.g أو مجموعة تضم عدة عناصر فرعية). واستخدم الروابط للحقول الفردية عندما تريد أيضًا إتاحة البيانات خارج محرر الكتل.
قوالب أنواع المنشورات
استخدم templateFor لتعيين صفحة كقالب افتراضي لنوع منشور:
{
"name": "product-template",
"title": "Product Template",
"templateFor": "product",
"templateLock": "insert"
}
ستبدأ أي منشورات جديدة من هذا النوع ببنية الكتل المحددة.
المسارات المخصصة
افتراضيًا، يفحص Blockstudio get_template_directory() . '/pages'. أضف مسارات أخرى باستخدام عامل التصفية:
add_filter( 'blockstudio/pages/paths', function( $paths ) {
$paths[] = get_stylesheet_directory() . '/custom-pages';
$paths[] = MY_PLUGIN_DIR . '/pages';
return $paths;
} );
يمكن لعمليات التكامل وقت التشغيل التي تجمع ملفات من عدة جذور استبدال فحص نظام الملفات بمصدر اكتشاف منطقي. عندئذٍ، تُحل ملفات تعريف الصفحات والتخطيطات والمحمّلات وقوالب المصدر حسب المسار المنطقي، حتى لو كانت الملفات المحددة موجودة في جذور مختلفة.
عوامل التصفية والإجراءات
تتيح نقاط التوسعة التالية اكتشاف الصفحات ومزامنتها وتوجيه المجموعات:
| الخطاف | النوع | الوصف |
|---|---|---|
blockstudio/pages/paths |
مرشّح | إضافة أدلة تفحصها Blockstudio للعثور على مصادر الصفحات. |
blockstudio/pages/collection_post_type_args |
مرشّح | ضبط وسيطات register_post_type() لنوع محتوى مخصص لمجموعة. |
blockstudio/pages/template_candidates |
مرشّح | ضبط أسماء ملفات القوالب التي تُؤخذ في الحسبان لمصدر الصفحة. |
blockstudio/pages/serve_markdown |
مرشّح | تمكين استجابات Markdown الخام أو تعطيلها. |
blockstudio/pages/orphan_action |
مرشّح | إرجاع trash أو delete أو keep لتنظيف العناصر اليتيمة. |
blockstudio/pages/docs_allowed_html |
مرشّح | ضبط قيم HTML المسموح بها لمحتوى مستندات Markdown المُنشأ. |
blockstudio/pages/allow_external_loader_path |
مرشّح | السماح لـpaths المُحمِّل بالعمل خارج جذر المجموعة. |
blockstudio/pages/manifest_scan_interval |
مرشّح | تحديد الحد الأقصى لعمر ذاكرة التخزين المؤقت للبيان القديم السابق لـ7.6.2، التي يمكن أن تهيّئ الإعدادات الدائمة لوقت التشغيل أثناء الترقية. |
blockstudio/pages/create_post_data |
مرشّح | تعديل بيانات المقالة قبل إنشاء صفحة متزامنة. |
blockstudio/pages/update_post_data |
مرشّح | تعديل بيانات المقالة قبل تحديث صفحة متزامنة. |
blockstudio/pages/sync_engine_inputs |
مرشّح | إضافة إصدار لمحلّل أو تعيين أو ترحيل، لتوسيع نطاق التسوية عمدًا لمرة واحدة. |
blockstudio/pages/post_created |
إجراء | يُنفَّذ بعد إنشاء مقالة صفحة متزامنة. |
blockstudio/pages/post_updated |
إجراء | يُنفَّذ بعد تحديث مقالة صفحة متزامنة. |
blockstudio/pages/synced |
إجراء | يُنفَّذ بعد اكتمال مزامنة سجل الصفحات. |
blockstudio/pages/reconciled |
إجراء | يُنفَّذ بعد تسوية صريحة، مع تقرير قابل للقراءة آليًا. |
blockstudio/pages/renderers |
إجراء | تسجيل عارضات الصفحات باستخدام Blockstudio\Page_Renderers::register(). يُنفَّذ مرة واحدة لكل طلب. |
blockstudio/pages/rendered |
إجراء | يُنفَّذ بعد عرض صفحة مكوّن، مع الصفحة وHTML الخاص بها وتبعياتها. |
blockstudio/pages/layout_error |
إجراء | يُنفَّذ عند تعذّر عرض تخطيط، مع الخطأ ومسار التخطيط والصفحة. |
PHP API
// Get all registered pages.
$pages = Blockstudio\Pages::pages();
// Get pages from one collection.
$docs = Blockstudio\Pages::pages('docs');
// Get the pages of one collection, sorted (same result as pages('docs')).
$docs = Blockstudio\Pages::in_collection('docs');
// Get a nested page tree.
$tree = Blockstudio\Pages::tree('docs');
// Get direct children for a page.
$children = Blockstudio\Pages::children('docs-guide', 'docs');
// Get collection metadata.
$collection = Blockstudio\Pages::collection('docs');
// Get a specific page.
$page = Blockstudio\Pages::get_page('about');
// Get the WordPress post ID for a page.
$postId = Blockstudio\Pages::get_post_id('about');
// Force sync a page explicitly (ignores fingerprints, locks, and sync: false).
Blockstudio\Pages::force_sync('about');
// Force sync all discovered pages explicitly.
Blockstudio\Pages::force_sync_all();
// Reconcile a complete deployment inventory without rewriting equal pages.
$report = Blockstudio\Pages::reconcile([
'authoritative' => true,
'plan_valid' => true,
'source' => [
'commit' => $commit,
'dirtyHash' => $dirtyHash,
],
]);
// Store this only after the matching static artifact and routes verify.
Blockstudio\Pages::store_successful_source_identity($report['sourceIdentity']);
// Lock a page against non-authoritative reconciliation.
Blockstudio\Pages::lock('about');
// Unlock a page.
Blockstudio\Pages::unlock('about');
// Register a page renderer (inside the blockstudio/pages/renderers action).
Blockstudio\Page_Renderers::register('react', [
'extensions' => ['tsx'],
'layouts' => ['layout.tsx'],
'render' => 'my_theme_render_page',
]);
// Find the renderer of an entry file.
$renderer = Blockstudio\Page_Renderers::for_entry('page.tsx');
// Register assets for rendered output and print the returned marker with it.
$marker = Blockstudio\Assets::register_owner('page-home', [$scriptPath]);
راجع مصالحة النشر للاطلاع على دلالات الوسيطات وحقول التقرير وحدود هوية المصدر التي تم التحقق منها.
تتوفر دوال مساعدة عامة للقوالب والتخطيطات:
blockstudio_pages('docs');
blockstudio_page_tree('docs');
blockstudio_page_children('docs-guide', 'docs');
blockstudio_page_collection('docs');
blockstudio_page_content();
blockstudio_current_page();
تتضمن مصفوفات الصفحات التي تُعيدها Blockstudio\Pages::pages() وBlockstudio\Pages::tree() وBlockstudio\Pages::children() والدوال المساعدة العامة هوية المنشور المتزامن، ومسارات المصدر والقالب، وبيانات المجموعة والمسار الوصفية، ونوع المحتوى، وسياسة المزامنة، ونوع المنشور وحالته، وسياسة التحرير، والبيانات الوصفية المخصصة، ومفتاح permalink. تُحمّل البيانات الوصفية للمجموعة من آخر مصالحة صريحة ناجحة. تعيد الطلبات العادية إنشاء بيانات وقت التشغيل هذه من الإعدادات المحفوظة والبيانات الوصفية للمنشور المتزامن، من دون قراءة أشجار مصادر الصفحات. لا يوفّر صنف Pages دالة مستقلة للرابط الدائم.
إنشاء صفحات مستندة إلى الملفات
قفل القوالب، وأوضاع تحرير الكتل، والدمج باستخدام المفاتيح، والتحكم في ما يمكن للعملاء تحريره.