ملء الخيارات
بدلًا من توفير أنواع حقول مختلفة مثل المنشورات أو المستخدمين أو التصنيفات، يتيح Blockstudio طريقة معيارية لملء البيانات مباشرةً من block.json. تعمل هذه الميزة مع أنواع الحقول select وradio وcheckbox وcolor وgradient.
يمكن ملء البيانات بأربع طرق:
- استعلام – إرجاع النتائج من استعلام عن منشور أو مستخدم أو تصنيف
- جلب – إرجاع النتائج من مصدر خارجي
- دالة – إرجاع النتائج من دالة مخصصة
- مخصص – إرجاع النتائج من مجموعة بيانات مخصصة
الاستعلام
عند اختيار وضع الاستعلام، يمكن ملء المنشورات أو المستخدمين أو التصنيفات.
{
"$schema": "https://blockstudio.dev/schema/block",
"name": "blockstudio/native",
"title": "Native Block",
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts"
}
}
]
}
}
تستخدم أنواع الاستعلامات المتاحة دوال WordPress التالية داخليًا:
الوسائط
يمكن تمرير وسائط مخصصة باستخدام السمة arguments:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "jobs",
"numberposts": "20"
}
}
}
]
}
}
تنسيق الإرجاع
افتراضيًا، يعيد Blockstudio ما يلي:
| الاستعلام | القيمة | التسمية |
|---|---|---|
posts |
كائن المنشور | post_title |
users |
كائن المستخدم | display_name |
terms |
كائن التصنيف | name |
خصّص الاستجابة باستخدام returnFormat:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "posts",
"numberposts": "20"
},
"returnFormat": {
"value": "id",
"label": "post_name"
}
}
}
]
}
}
وضع الجلب
فعّل البحث الديناميكي باستخدام الخيار fetch:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "query",
"query": "posts",
"fetch": true,
"arguments": {
"post_type": "posts",
"numberposts": "20"
}
}
}
]
}
}
يتيح ذلك stylisedUi ويجلب أول 20 منشورًا مبدئيًا. يؤدي الكتابة في حقل الاختيار إلى البحث عن المنشورات باستخدام الوسيط s.
الدالة
استخدم دالة مخصصة لملء الخيارات:
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types"
}
}
]
}
}
الوسائط
مرر الوسائط كمصفوفة (يستخدم call_user_func_array داخليًا):
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"]
}
}
]
}
}
تنسيق الإرجاع
{
"blockstudio": {
"attributes": [
{
"id": "postTypes",
"type": "checkbox",
"label": "Post types",
"populate": {
"type": "function",
"function": "get_post_types",
"arguments": [[], "objects"],
"returnFormat": {
"value": "name",
"label": "label"
}
}
}
]
}
}
مزج الخيارات
ادمج الخيارات الثابتة مع البيانات المملوءة:
{
"blockstudio": {
"attributes": [
{
"id": "users",
"type": "radio",
"label": "Users",
"options": [
{
"value": "administrators",
"label": "Administrators"
},
{
"value": "editors",
"label": "Editors"
}
],
"populate": {
"type": "query",
"query": "users",
"position": "before"
}
}
]
}
}
يتحكم الخيار position (before أو after) في موضع ظهور الخيارات المملوءة بالنسبة إلى الخيارات الثابتة.
تحذير
لا يُدعم مزج الخيارات والبيانات المملوءة عند استخدام وضع الجلب.
البيانات المخصصة
أنشئ مجموعات بيانات قابلة لإعادة الاستخدام باستخدام المرشح blockstudio/blocks/attributes/populate. يتلقى المرشح وسيطًا واحدًا، وهو مصفوفة تضم جميع مجموعات البيانات المخصصة مرتبة حسب الاسم. أضف مجموعة البيانات ضمن مفتاح وأعِد المصفوفة:
add_filter('blockstudio/blocks/attributes/populate', function($options) {
$options['customData'] = [
['value' => '1', 'label' => 'Option 1'],
['value' => '2', 'label' => 'Option 2'],
];
return $options;
});
ثم أشر إلى المفتاح في كتلتك:
{
"blockstudio": {
"attributes": [
{
"id": "posts",
"type": "select",
"label": "Posts",
"populate": {
"type": "custom",
"custom": "customData"
}
}
]
}
}
البيانات الخارجية
اجلب البيانات من مصدر خارجي:
{
"blockstudio": {
"attributes": [
{
"id": "select",
"type": "select",
"label": "Select",
"multiple": true,
"populate": {
"type": "fetch",
"arguments": {
"urlSearch": "https://example.com/wp-json/wp/v2/posts?search="
},
"returnFormat": {
"value": "id",
"label": "title.rendered"
}
}
}
]
}
}
تُضاف عبارة البحث إلى urlSearch.
الوسائط الديناميكية
يمكن أن تشير وسائط الملء إلى سمات الكتلة الأخرى باستخدام صيغة {attributes.*}. عند تغيير السمة المشار إليها، يجلب الحقل خياراته من جديد تلقائيًا.
{
"blockstudio": {
"attributes": [
{
"id": "post_type",
"type": "select",
"label": "Post Type",
"options": [
{ "label": "Pages", "value": "page" },
{ "label": "Posts", "value": "post" }
]
},
{
"id": "selected_post",
"type": "select",
"label": "Select Post",
"populate": {
"type": "query",
"query": "posts",
"arguments": {
"post_type": "{attributes.post_type.value}",
"numberposts": 10
}
}
}
]
}
}
يعمل هذا مع جميع أنواع الملء (query وfunction وcustom). وتُحل أي قيمة في إعدادات الملء تحتوي على {attributes.*} من جهة العميل باستخدام قيمة السمة الحالية قبل تشغيل الاستعلام.
تستخدم المراجع القيم المخزنة في المحرر. لخيار القائمة المنسدلة، استخدم {attributes.post_type.value} لقيمته أو {attributes.post_type.label} لتسميته؛ يتحكم returnFormat في قيمة القالب، لا في شكل القيمة المخزنة في المحرر.
تُحسم الوسائط المتداخلة دون تسلسلها في سلسلة قالب. ويحتفظ الوسيط المكوّن من عنصر نائب واحد بالنوع الذي يشير إليه، بما في ذلك الأرقام والقيم المنطقية والمصفوفات والكائنات. أما العنصر النائب المضمّن في نص آخر فينتج سلسلة. وتظل المراجع غير الموجودة دون تغيير، وتُرسل القيم المقتبسة أو متعددة الأسطر كما هي.
تحتفظ استدعاءات الدوال الراجعة بقوائم وسائطها الموضعية. ولا يضيف المحرر وسائط البحث WordPress إلا إلى عمليات التعبئة التي تستخدم query، وليس إلى استدعاءات الدوال.
عرض الخيارات التابعة
لا تُحمّل الخيارات التابعة عند تسجيل الكتلة، لأن لكل مثيل كتلة وسائط مختلفة. ويستخدم العرض الخيار المحفوظ بدلًا من إسقاطه بسبب قائمة خيارات فارغة. ولا يُنفذ الاستدعاء الراجع للتعبئة مرة أخرى في الواجهة الأمامية.
يظل returnFormat الخاص بالحقل ساريًا:
returnFormat |
اختيار واحد | اختيار متعدد |
|---|---|---|
value (افتراضي) |
القيمة المحفوظة، مثل "a" |
مصفوفة من القيم المحفوظة، مثل ["a", "b"] |
label |
التسمية المحفوظة | مصفوفة من التسميات المحفوظة |
both |
الخيار {value, label} المحفوظ |
مصفوفة من الخيارات المحفوظة |
بالنسبة إلى الاختيارات المملوءة بالاستعلام، تظل القيم تُحل إلى كائن المنشور أو المستخدم أو المصطلح المقابل WordPress ما لم يكن populate.returnFormat.value هو "id". تأتي التسميات من الاختيار المحفوظ. إذا لم يكن للاختيار المستورَد تسمية، تُستخدم قيمته كتسمية. يكون للخيار الثابت المطابق المُعلن في options الأولوية على الخيار المحفوظ، لذا تُطبَّق تسميته الحالية.
تظل الاختيارات الفارغة بقيمة false (أو بقيمة fallback المضبوطة للحقل). لا يغيّر هذا التحقق من الخيارات الثابتة العادية: فالقيمة المحفوظة التي لم تعد موجودة في قائمة الخيارات الثابتة تظل تُرجع false.
تحافظ القوائم المنسدلة الديناميكية أيضًا على اختيارات default وfallback بينما يظل تحميل خياراتها مؤجلًا. استخدم قيمة مفردة أو خيارًا من نوع {value, label} أو مصفوفة من أيٍّ منهما لقائمة منسدلة متعددة الاختيارات. تستخدم القيمة المفردة قيمتها كتسمية ما لم تطابق خيارًا ثابتًا مُعلنًا. يحافظ كائن الخيار على التسمية التي زُوّد بها؛ وتكون الأولوية للخيار الثابت المطابق. لا يُشغَّل أي رد نداء للتعبئة على الخادم للبحث عن هذه القيم الافتراضية.