Перейти к содержимому

Заполнение параметров

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