الصفحات والأنماط
يتيح لك Blockstudio تعريف صفحات WordPress وأنماط الكتل وقوالب محرر الموقع كملفات ضمن قالبك. اكتب قوالب شبيهة بـ HTML، وسيحوّل محلل Blockstudio محتواها إلى كتل WordPress أصلية.
- الصفحات تُزامن مع قاعدة البيانات على هيئة منشورات WordPress، مع إبقاء قوالب الملفات ومحتوى الصفحات متزامنة.
- الأنماط تُسجّل في الذاكرة عبر
register_block_pattern()، وتتوفر في أداة إدراج الكتل ليضعها المستخدمون في أي مكان. - قوالب الموقع توفر مصادر
wp_templateوwp_template_partمستندة إلى ملفات لمحرر الموقع WordPress.
تشترك الميزات الثلاث في محلل HTML نفسه وصياغة الكتل نفسها.
شرح عملي لقوالب الصفحات المستندة إلى ملفات ومزامنتها وقفلها.
بنية المجلدات
theme/
├── pages/
│ ├── about/
│ │ ├── page.json
│ │ └── index.php
│ └── contact/
│ ├── page.json
│ └── index.twig
├── patterns/
├── hero/
│ ├── pattern.json
│ └── index.php
└── cta/
├── pattern.json
└── index.blade.php
├── templates/
└── front-page/
├── template.json
└── index.php
└── parts/
└── header/
├── part.json
└── index.php
يحتوي كل مجلد فرعي على ملف إعداد JSON (page.json أو pattern.json أو template.json أو part.json) وملف قالب.
محركات القوالب
يمكن كتابة القوالب كترميز عادي في index.php، أو باستخدام Twig أو Blade:
| الملف | المحرك | المتطلب |
|---|---|---|
index.php |
لا شيء (يُقرأ كما هو؛ ولا تُنفّذ شيفرة PHP) | لا شيء |
index.twig |
Twig | Timber |
index.blade.php |
Blade | illuminate/view |
إذا وُجدت ملفات قوالب متعددة، يكون ترتيب الأولوية: index.php > index.blade.php > index.twig.
نظرًا إلى أن القوالب تُجمّع وقت التهيئة (قبل توفر سياق أي طلب)، لا يمكن لقوالب Twig وBlade الوصول إلى المتغيرات الديناميكية. وهي مفيدة للدوال والمرشحات المضمّنة مثل {{ "text"|upper }} أو {{ strtoupper("text") }}.
ربط HTML بالكتل
تُحوّل عناصر HTML القياسية تلقائيًا إلى كتل WordPress المقابلة.
النص
| HTML | الكتلة |
|---|---|
<p> |
core/paragraph |
<h1> – <h6> |
core/heading |
<ul> |
core/list (غير مرتبة) |
<ol> |
core/list (مرتبة) |
<li> |
core/list-item |
<blockquote> |
core/quote |
<code> |
core/code |
<pre> |
core/preformatted |
تحافظ القوائم على بنيتها. يتحول <ul> أو <ol> داخل <li> إلى كتلة داخلية core/list ضمن ذلك core/list-item، وهي البنية التي يحفظها المحرر، لذا يمكن تداخل القوائم بأي عمق. وتتحول class على قائمة أو عنصر فيها إلى className الخاص بها، وهي الطريقة التي يُضبط بها نمط كتلة مثل is-style-checks من ملف الصفحة؛ ويؤدي <block name="core/list" className="..."> الغرض نفسه.
الوسائط
| HTML | الكتلة |
|---|---|
<img> |
core/image |
<figure> |
core/image (مع تسمية توضيحية) |
<audio> |
core/audio |
<video> |
core/video |
التخطيط
| HTML | الكتلة |
|---|---|
<div>، <section> |
core/group |
<main>، <header>، <footer>، <article>، <aside> |
core/group يحافظ على العنصر باعتباره tagName |
<hr> |
core/separator |
<details> |
core/details |
<table> |
core/table |
صياغة الكتل
للكتل التي لا تملك مكافئًا مباشرًا في HTML، استخدم العنصر <block>:
<block name="core/cover" url="https://example.com/hero.jpg">
<h1>Welcome</h1>
<p>Content inside the cover block.</p>
</block>
الكتل الأساسية
<!-- Pullquote -->
<block name="core/pullquote">
<p>An important quote.</p>
</block>
<!-- Verse -->
<block name="core/verse">Roses are red,
Violets are blue.</block>
<!-- Cover -->
<block name="core/cover" url="https://example.com/image.jpg">
<h2>Cover Title</h2>
</block>
<!-- Embed -->
<block name="core/embed" url="https://youtube.com/watch?v=..." providerNameSlug="youtube" />
<!-- Spacer -->
<block name="core/spacer" height="50px" />
<!-- Gallery -->
<block name="core/gallery">
<img src="https://example.com/1.jpg" alt="Image 1" />
<img src="https://example.com/2.jpg" alt="Image 2" />
</block>
<!-- Columns -->
<block name="core/columns">
<block name="core/column">
<h3>Column 1</h3>
</block>
<block name="core/column">
<h3>Column 2</h3>
</block>
</block>
<!-- Buttons -->
<block name="core/buttons">
<block name="core/button" url="/get-started">Get Started</block>
</block>
<!-- Row (flex layout) -->
<block name="core/group" layout='{"type":"flex","flexWrap":"nowrap"}'>
<p>Item 1</p>
<p>Item 2</p>
</block>
الكتل المخصصة
تعمل الصياغة نفسها مع أي كتلة مسجلة:
<block name="blockstudio/section">
<h1>Welcome</h1>
</block>
<block name="acf/hero" title="Hero Title" background="dark">
<p>Inner content becomes InnerBlocks.</p>
</block>
السمات
تُمرَّر السمات HTML على عناصر <block> بوصفها سمات للكتلة. وتُدعم القيم JSON:
<block name="core/heading" level="3">Custom Heading</block>
<block name="core/group" layout='{"type":"flex","orientation":"vertical"}'>
<p>Stacked content.</p>
</block>
<img src="https://example.com/photo.jpg" alt="Photo" width="800" height="400" />
تُفك ترميز قيم السمات مرة واحدة، بالطريقة التي يقرأها بها المتصفح، لذا تخزّن data-animate="[&>span]:fade" وdata-animate="[&>span]:fade" القيمة نفسها.
في العنصر المطابق لكتلة Blockstudio، تُخزَّن كل سمة مع الكتلة. تصل الحقول المعلنة إلى القالب؛ أما السمات العامة التي لا تعلنها الكتلة (id وstyle وrole وtitle وlang وdir وhidden وtabindex وaria-* وdata-*) فتُضاف إلى العنصر الجذر للكتلة عند عرضه، تمامًا كما في وسوم الكتل. في مصادر الصفحات والأنماط، لا تسمّي بادئة html- إلا إحدى تلك السمات العامة، لذا يُمرَّر html-role="note" باعتباره role، بينما لا تُعرض معالجات الأحداث مثل html-onclick مطلقًا. وتظل كل الأشياء الأخرى، بما فيها class غير المعلنة، ضمن محتوى المنشور من دون أن تصل إلى الصفحة، ويُبلغ wp bs pages sync عنها لكل صفحة يحللها.
عارضات الكتل المخصصة
يستخدم محلل HTML بنية قائمة على سجل. أضف منشئًا لكتلة مخصصة باستخدام blockstudio/block_tags/builders:
add_filter( 'blockstudio/block_tags/builders', function( $builders, $parser ) {
$builders['acf/hero'] = function( array $attrs, string $inner_content ) {
$inner_blocks = Blockstudio\Block_Tags::parse_inner_blocks( $inner_content );
return array(
'blockName' => 'acf/hero',
'attrs' => $attrs,
'innerBlocks' => $inner_blocks,
'innerHTML' => '',
'innerContent' => array_fill( 0, count( $inner_blocks ), null ),
);
};
return $builders;
}, 10, 2 );
ثم استخدمه في أي قالب:
<block name="acf/hero" background="dark">
<h1>Welcome</h1>
</block>
يمكنك أيضًا تجاوز طريقة عرض الكتل الأساسية:
add_filter( 'blockstudio/parser/renderers', function( $renderers, $parser ) {
$renderers['core/paragraph'] = function( array $attrs, string $inner_content ) {
$content = trim( $inner_content );
$attrs['align'] = $attrs['align'] ?? 'center';
return array(
'blockName' => 'core/paragraph',
'attrs' => $attrs,
'innerBlocks' => array(),
'innerHTML' => '<p class="has-text-align-center">' . $content . '</p>',
'innerContent' => array( '<p class="has-text-align-center">' . $content . '</p>' ),
);
};
return $renderers;
}, 10, 2 );
تتلقى دوال الاستدعاء للمنشئ السمات المحللة والمحتوى الداخلي الخام. ويجب أن تعيد مصفوفة كتلة WordPress. راجع العارضات المخصصة للاطلاع على ترتيب المرشحات الكامل ومثال الحاوية.
توقيع دالة المنشئ
/**
* @param array $attrs Parsed element or block-tag attributes.
* @param string $inner_content Raw inner content.
* @return array WordPress block array.
*/
function my_builder( array $attrs, string $inner_content ): array {}
مطابقة العناصر
افتراضيًا، تُطابق عناصر HTML القياسية مثل <h1> و<p> و<img> كتل WordPress الأساسية. يمكنك تجاوز هذه المطابقة لتوجيه أي عنصر HTML إلى كتلة مختلفة باستخدام المرشح blockstudio/parser/element_mapping:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['h1'] = 'custom/heading';
$mapping['h2'] = 'custom/heading';
$mapping['p'] = 'custom/paragraph';
$mapping['img'] = 'custom/image';
return $mapping;
}, 10, 2 );
عند تفعيل هذا المرشح، سينشئ كل <h1> في قوالبك كتلة custom/heading بدلًا من core/heading. وتُمرَّر سمات العنصر إلى الكتلة المستهدفة. إذا كان هناك عارض مسجل باسم الكتلة المستهدفة، فسيُستخدم؛ وإلا فستُنشأ بنية كتلة عامة.
يفيد هذا عندما يوفّر القالب أو الإضافة أنواع كتل مخصصة ينبغي أن تحل محل الأنواع الافتراضية في جميع قوالب الصفحات والأنماط.
في عمليات المطابقة البسيطة لـ<p>، يمكن لـBlockstudio توجيه المحتوى الداخلي لـHTML مباشرةً إلى سمة richtext في كتلة Blockstudio مسجلة وغير أساسية. يجب أن تعلن الكتلة المستهدفة سمة باستخدام content وid: "content".
يظل التنسيق المضمّن (type: "richtext" وa وb وbr وcode وdel وem وi وimg وins وmark وs وsmall وspan وstrong وsub وsup وu) ضمن القيمة الموجّهة حتى عندما تكون العلامة نفسها مطابقة لعنصر، كما في code وimg افتراضيًا. وتتحول الفقرة التي تكون صورتها الطفل الوحيد إلى الكتلة التي تطابقها <img>، وهي الكتلة التي ينشئها Markdown للصورة المستقلة. وتستمر وسوم الكتل المتداخلة وعناصر HTML على مستوى الكتلة في التحليل ككتل داخلية.
يمكن أن تكون قيم المطابقة أيضًا دوال قابلة للاستدعاء عندما تعتمد الكتلة المستهدفة على سمات العنصر:
add_filter( 'blockstudio/parser/element_mapping', function( $mapping ) {
$mapping['div'] = function( array $attrs ) {
if ( isset( $attrs['width'] ) ) {
return 'theme/row';
}
if ( isset( $attrs['gap'] ) ) {
return 'theme/flow';
}
return 'theme/div';
};
return $mapping;
} );
تُحلل الكتل المخصصة المطابقة لعناصر حاوية مثل <section> و<div> أبناء HTML المتداخلين تكراريًا، لذا تصبح العناوين والصور ووسوم الكتل والفقرات الداخلية كتلًا فرعية أصلية.
مثال كامل
قالب صفحة كامل يجمع أنواعًا متعددة من الكتل:
<div>
<h1>Welcome to Our Site</h1>
<p>This is an <strong>introduction</strong> with <em>formatting</em>.</p>
<block name="core/columns">
<block name="core/column">
<h3>Feature One</h3>
<p>First feature description.</p>
</block>
<block name="core/column">
<h3>Feature Two</h3>
<p>Second feature description.</p>
</block>
</block>
<block name="core/cover" url="https://example.com/hero.jpg">
<h2>Our Mission</h2>
<p>Building amazing things together.</p>
</block>
<details>
<summary>FAQ</summary>
<p>Answers to common questions.</p>
</details>
<block name="core/buttons">
<block name="core/button" url="/contact">Contact Us</block>
<block name="core/button" url="/learn-more">Learn More</block>
</block>
</div>