Перейти до вмісту

Заповнення параметрів

Замість використання різних типів полів, як-от дописи, користувачі або терміни, 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) визначає розташування заповнених параметрів відносно статичних.

Попередження

Поєднання параметрів і заповнення даними не підтримується в режимі fetch.

Власні дані

Створюйте багаторазові набори даних за допомогою фільтра 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 заповнення.