Заполнение параметров
Вместо использования отдельных типов полей, таких как записи, пользователи или таксономические термины, 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} или массив с любым из них. Для скалярного значения в качестве подписи используется оно само, если только оно не совпадает с объявленным статическим вариантом. Объект варианта сохраняет заданную для него подпись; совпадающий статический вариант имеет приоритет. На сервере callback-функция заполнения не запускается для поиска этих значений по умолчанию.