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

InnerBlocks

Внутрішні блоки дають змогу вставляти додаткові блоки в інші блоки. Для цього Blockstudio використовує компонент InnerBlocks. Зверніть увагу: у кожному блоці можна використовувати лише один компонент InnerBlocks — це обмеження WordPress.

Основне використання

Щоб використовувати InnerBlocks, додайте компонент <InnerBlocks /> до шаблону блока:

PHP
<InnerBlocks />

Структура композиції залежить від вас. Компонент InnerBlocks можна вкладати на будь-яку глибину або використовувати самостійно.

Властивості

allowedBlocks

Властивість allowedBlocks дає змогу визначити, які блоки можна вставляти в компонент InnerBlocks.

PHP

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode(['core/heading', 'core/paragraph'])); ?>" />

Twig

Twig
<InnerBlocks allowedBlocks="{{ ['core/heading', 'core/paragraph']|json_encode|escape('html_attr') }}" />

allowedBlocks також підтримує токени, що розгортаються на сервері. Токени розгортаються до того, як редактор отримує шаблон, а буквальні назви блоків залишаються без змін.

Токен Опис
namespace/* Усі зареєстровані блоки в цьому просторі назв
category:<slug> Усі зареєстровані блоки в цій категорії блоків WordPress
@theme Усі блоки Blockstudio, зареєстровані в активній темі

Розгорнуті записи усувають дублікати зі збереженням порядку автора:

PHP
<InnerBlocks allowedBlocks="<?php echo esc_attr(wp_json_encode([
  'core/paragraph',
  'category:content',
  'bsui/field',
])); ?>" />

Токени, для яких не знайдено блоків, ігноруються. Вивід фронтенду не змінюється, оскільки allowedBlocks використовується лише в редакторі.

Тег

За замовчуванням компонент InnerBlocks рендериться як елемент div. Це можна змінити за допомогою властивості tag.

PHP
<InnerBlocks tag="section" />

Шаблон

Властивість template дає змогу визначити шаблон для компонента InnerBlocks.

PHP

PHP
<InnerBlocks template="<?php echo esc_attr(wp_json_encode([
  ['core/heading', ['placeholder' => 'Book Title']],
  ['core/paragraph', ['placeholder' => 'Summary']]
])); ?>" />

Twig

Twig
<InnerBlocks template="{{ [
  ['core/heading', { placeholder: 'Book Title' }],
  ['core/paragraph', { placeholder: 'Summary' }]
]|json_encode|escape('html_attr') }}" />

templateLock

Властивість templateLock дає змогу визначити, чи можна змінювати шаблон.

Значення Опис
contentOnly Забороняє всі операції. Типи блоків без вмісту приховуються зі списку. Дочірні блоки не можуть це перевизначити.
all Забороняє всі операції. Не можна вставляти, переміщувати або видаляти блоки.
insert Забороняє вставлення та видалення блоків, але дозволяє переміщувати наявні.
false Забороняє застосовувати блокування, навіть якщо його містить батьківський блок.

renderAppender

Властивість renderAppender дає змогу визначити тип засобу додавання блоків.

Значення Опис
default Показувати типовий додаток блока (додаток у стилі абзацу, якщо дозволено блок абзацу)
button Показувати кнопку з піктограмою + як додаток

useBlockProps

useBlockProps видалить зовнішню обгортку компонента InnerBlocks у редакторі. Докладніше див. useBlockProps.

Контекст

Реєстрація

Blockstudio підтримує контекст для компонента InnerBlocks. Це дає змогу передавати дані від батьківського блоку до дочірніх блоків. Хоча під капотом використовується базовий механізм контексту WordPress, Blockstudio забезпечує зручніший API.

Замість того щоб окремо визначати всі атрибути, які потрібно передати через контекст, можна просто підписатися на всі атрибути батьківського блока.

Кожен дочірній блок отримує значення власного батьківського блока, зокрема під час першого попередньо завантаженого відображення в редакторі. Зміна полів провайдера оновлює його дочірні блоки в редакторі, навіть якщо попереднє відображення ще завантажується. Однакові дочірні блоки в різних провайдерів зберігають окремі кешовані відображення з урахуванням контексту.

Уявімо, що ви налаштували блок-контейнер так:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/container",
  "title": "Container",
  "category": "design",
  "icon": "star-filled",
  "description": "Container block.",
  "blockstudio": {
    "attributes": [
      {
        "id": "full-width",
        "type": "toggle",
        "label": "Makes section full width"
      }
    ]
  }
}

У дочірньому блоці просто скористайтеся властивістю usesContext із назвою батьківського блока, щоб отримати доступ до всіх його атрибутів у шаблоні блока.

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/element",
  "title": "Element",
  "category": "design",
  "icon": "star-filled",
  "description": "Element block.",
  "usesContext": ["blockstudio/container"],
  "parent": ["blockstudio/container"],
  "blockstudio": true
}

Шаблони

Змінні $context і $c доступні в шаблонах блоків, щоб отримати доступ до всіх атрибутів батьківського блока. Дочірні блоки автоматично перезавантажуються в редакторі, якщо дані батьківського блока змінюються.

PHP

PHP
<?php $container = $context['blockstudio/container']; ?>

<h1>
  <?php echo $container['full-width']
      ? 'is full width'
      : 'no full width'; ?>
</h1>

Twig

Twig
{% set container = context['blockstudio/container'] %}

<h1>
  {{ container['full-width']
      ? 'is full width'
      : 'no full width' }}
</h1>

Обгортка на фронтенді

InnerBlocks має виводити елемент-обгортку навколо дочірніх блоків у редакторі, проте на фронтенді його можна прибрати за допомогою фільтра blockstudio/blocks/components/inner_blocks/frontend/wrap.

PHP
add_filter('blockstudio/blocks/components/inner_blocks/frontend/wrap', function($wrap, $block) {
  return false; // Remove wrapper
}, 10, 2);

Дострокове повернення

Щоб достроково повернути результат із методу render блока, перевірте, чи порожня змінна $innerBlocks. Це зручно, якщо потрібно нічого не виводити, коли внутрішніх блоків немає.

PHP
<?php if (strip_tags($innerBlocks) === '') {
  return;
} ?>
<InnerBlocks tag="section" />

Оскільки <InnerBlocks/> завжди виводить порожній тег абзацу, можна скористатися функцією strip_tags, щоб перевірити, чи порожній вміст.

Динамічні шаблони

Типи полів Вибір та Перемикач підтримують динамічне створення шаблону InnerBlocks залежно від значення поля. Це зручно, якщо потрібно дозволити користувачеві вибрати інший шаблон для компонента InnerBlocks.

Для цього просто додайте ключ innerBlocks до масиву параметрів із шаблоном:

JSON
{
  "$schema": "https://blockstudio.dev/schema/block",
  "name": "blockstudio/dynamic-layout",
  "title": "Dynamic Layout",
  "blockstudio": {
    "attributes": [
      {
        "id": "layout",
        "type": "select",
        "label": "Layout",
        "options": [
          {
            "value": "1",
            "label": "Two Columns",
            "innerBlocks": [
              {
                "name": "core/columns",
                "innerBlocks": [
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Left Heading",
                          "level": 1
                        }
                      }
                    ]
                  },
                  {
                    "name": "core/column",
                    "innerBlocks": [
                      {
                        "name": "core/heading",
                        "attributes": {
                          "content": "Right Heading",
                          "level": 1
                        }
                      }
                    ]
                  }
                ]
              }
            ]
          },
          {
            "value": "2",
            "label": "Single Column",
            "innerBlocks": [
              {
                "name": "core/heading",
                "attributes": {
                  "content": "Main Heading",
                  "level": 1
                }
              },
              {
                "name": "core/paragraph",
                "attributes": {
                  "content": "Main content goes here."
                }
              }
            ]
          }
        ],
        "allowNull": "Select a layout"
      }
    ]
  }
}

Контекст блоків і взаємодія

Дізнайтеся, як батьківські та дочірні блоки обмінюються даними за допомогою контексту.