Към съдържанието

Попълване на опции

Вместо да предоставя различни типове полета, като публикации, потребители или термини, Blockstudio позволява модулно попълване на данни директно от block.json. Тази функция работи с типовете полета select, radio, checkbox, color и gradient.

Данните могат да се попълват по четири начина:

  • Заявка – Връща резултати от заявка за публикации, потребители или термини
  • Извличане – Връща резултати от външен източник
  • Функция – Връща резултати от персонализирана функция
  • Персонализирани данни – Връща резултати от персонализиран набор от данни

Заявка

При избор на режим за заявка могат да се попълват публикации, потребители или термини.

JSON
{
  "$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:

Заявка Функция
posts get_posts
users get_users
terms get_terms

Аргументи

Персонализирани аргументи могат да се подават чрез атрибута arguments:

JSON
{
  "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:

JSON
{
  "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:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "query",
          "query": "posts",
          "fetch": true,
          "arguments": {
            "post_type": "posts",
            "numberposts": "20"
          }
        }
      }
    ]
  }
}

Това включва stylisedUi и първоначално извлича първите 20 публикации. При въвеждане в полето за избор се търсят публикации чрез аргумента s.

Функция

Използвайте персонализирана функция за попълване на опциите:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types"
        }
      }
    ]
  }
}

Аргументи

Подайте аргументи като масив (вътрешно се използва call_user_func_array):

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"]
        }
      }
    ]
  }
}

Формат на резултата

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "postTypes",
        "type": "checkbox",
        "label": "Post types",
        "populate": {
          "type": "function",
          "function": "get_post_types",
          "arguments": [[], "objects"],
          "returnFormat": {
            "value": "name",
            "label": "label"
          }
        }
      }
    ]
  }
}

Комбиниране на опции

Комбинирайте статични опции с попълнени данни:

JSON
{
  "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. Филтърът получава един аргумент — масив от всички персонализирани набори от данни, подредени по ключ. Добавете набора си под даден ключ и върнете масива:

PHP
add_filter('blockstudio/blocks/attributes/populate', function($options) {
  $options['customData'] = [
    ['value' => '1', 'label' => 'Option 1'],
    ['value' => '2', 'label' => 'Option 2'],
  ];
  return $options;
});

След това посочете ключа в блока си:

JSON
{
  "blockstudio": {
    "attributes": [
      {
        "id": "posts",
        "type": "select",
        "label": "Posts",
        "populate": {
          "type": "custom",
          "custom": "customData"
        }
      }
    ]
  }
}

Външни данни

Извличайте данни от външен източник:

JSON
{
  "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.*}. Когато препратеният атрибут се промени, опциите на полето се извличат отново автоматично.

JSON
{
  "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} или масив от едното или другото за поле с множествен избор. Скаларната стойност използва собствената си стойност като етикет, освен ако не съвпада с декларирана статична опция. Обектът на опцията запазва подадения етикет; съвпадаща статична опция има предимство. На сървъра не се изпълнява функция за попълване, която да търси тези стойности по подразбиране.