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

Перехід із ACF Blocks

Якщо ви створювали власні блоки WordPress за допомогою ACF (Advanced Custom Fields), перехід на Blockstudio буде простим. Підходи подібні: ви визначаєте поля, пишете шаблон, і блок з’являється в редакторі. Відмінності полягають у тому, що Blockstudio самостійно знаходить папки блоків, визначає поля у власній схемі всередині block.json і передає кожному шаблону значення полів одним масивом $a.

У цьому посібнику покроково описано перехід і наведено паралельні порівняння шаблонів ACF та Blockstudio.

Основна відмінність

Починаючи з ACF 6.0, блок ACF — це block.json із ключем acf, який указує на шаблон відображення, а кожна папка блока реєструється окремим викликом register_block_type(). Поля беруться з групи полів, прив’язаної до блока правилом розташування Block (створеної в адмінпанелі, синхронізованої через Local JSON або зареєстрованої за допомогою acf_add_local_field_group()), або, починаючи з ACF PRO 6.8.1, із вбудованого масиву acf.fields у тому самому block.json. Blockstudio замінює виклик реєстрації автоматичним пошуком файлів: створіть папку з block.json та index.php — і блок буде зареєстровано автоматично.

ACF:

JSON
{
  "name": "acf/hero",
  "title": "Hero",
  "acf": {
    "renderTemplate": "template.php"
  }
}
PHP
add_action( 'init', function () {
  register_block_type( __DIR__ . '/blocks/hero' );
} );
PHP
acf_add_local_field_group([
  'key'      => 'group_hero',
  'title'    => 'Hero Fields',
  'fields'   => [
    ['key' => 'field_title', 'name' => 'title', 'type' => 'text', 'label' => 'Title'],
    ['key' => 'field_image', 'name' => 'image', 'type' => 'image', 'label' => 'Background', 'return_format' => 'array'],
  ],
  'location' => [[['param' => 'block', 'operator' => '==', 'value' => 'acf/hero']]],
]);
PHP
<?php
$title = get_field('title');
$image = get_field('image');
?>
<div class="hero" <?php if ($image) : ?>style="background-image: url(<?php echo esc_url($image['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($title); ?></h1>
</div>

Blockstudio:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "blockstudio": {
    "attributes": [
      { "id": "title", "type": "text", "label": "Title" },
      { "id": "image", "type": "files", "label": "Background", "multiple": false }
    ]
  }
}
PHP
<div useBlockProps class="hero" <?php if ($a['image']) : ?>style="background-image: url(<?php echo esc_url($a['image']['url']); ?>)"<?php endif; ?>>
  <h1><?php echo esc_html($a['title']); ?></h1>
</div>

Немає виклику реєстрації чи зворотного виклику відображення: структуру папок використовують для реєстрації, а поля зберігаються в block.json поруч із шаблоном. Шаблон читає $a замість виклику get_field().

Реєстрація блока

ACF

Нинішні блоки ACF реєструються з block.json із ключем acf (renderTemplate або renderCallback, а також параметри на кшталт blockVersion). Їх завантажують окремим викликом register_block_type() для кожної папки блока, зазвичай на init у functions.php або у файлі плагіна. У старіших блоках може використовуватися acf_register_block_type(); ACF позначає її застарілою, починаючи з ACF 6.0. Вона й далі працює, тож переносьте такі блоки так само.

Blockstudio

Створіть папку в каталозі blockstudio/ своєї теми (або blocks/, якщо так зручніше). Додайте block.json зі стандартними метаданими блока WordPress і ключем blockstudio. Ось і все.

Код
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

block.json використовує стандартний формат WordPress block.json із ключем blockstudio для полів і конфігурації:

JSON
{
  "name": "my-theme/hero",
  "title": "Hero",
  "category": "theme",
  "icon": "cover-image",
  "description": "Full-width hero section with background image.",
  "blockstudio": {
    "attributes": []
  }
}

Доступ до значень полів

Це найпоширеніша зміна під час переходу.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (завжди доступне)
the_field('title') <?php echo $a['title']; ?>
have_rows('items') / the_row() foreach ($a['items'] as $item)
get_sub_field('name') $item['name']

Змінна $a — це скорочення для $attributes; вона містить значення всіх полів поточного блока. Вона завжди доступна в шаблоні — і в редакторі, і на фронтенді.

Змінні шаблону

Blockstudio надає кілька змінних у кожному шаблоні:

Змінна Скорочення Опис
$attributes $a Усі значення полів
$block $b Метадані блока (назва, заголовок, dir, url, postId)
$context $c Контекст батьківського блока
$content Вміст InnerBlocks
$post_id ID поточного запису (працює в редакторі й на фронтенді; post_id або postId у Twig)

Відповідність типів полів

Більшість типів полів ACF мають прямі відповідники в Blockstudio. Синтаксис JSON відрізняється, але поняття легко зіставити.

Текстові поля та поля вмісту

ACF:

PHP
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']

Blockstudio:

JSON
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }

Для редагування тексту в редакторі блоків (а не лише у текстовому полі) використовуйте тип richtext із компонентом <RichText />:

JSON
{ "id": "heading", "type": "richtext" }
PHP
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />

Поля зображень і файлів

Поля image і file у ACF відповідають типу files у Blockstudio:

ACF:

PHP
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']

Blockstudio:

JSON
{ "id": "photo", "type": "files", "label": "Photo", "multiple": false }
{ "id": "gallery", "type": "files", "label": "Gallery", "multiple": true }
{ "id": "document", "type": "files", "label": "Document", "multiple": false, "allowedTypes": ["application/pdf"] }

Структура повернутого об’єкта подібна:

PHP
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];

// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];

Доступні властивості: ID, title, alt, caption, description, href, url, sizes. Розміри задаються в sizes, наприклад $a['photo']['sizes']['full-width'].

Списки, перемикачі та прапорці

ACF:

PHP
[
  'name' => 'color',
  'type' => 'select',
  'choices' => ['red' => 'Red', 'blue' => 'Blue'],
  'return_format' => 'value',
]

Blockstudio:

JSON
{
  "id": "color",
  "type": "select",
  "label": "Color",
  "options": [
    { "value": "red", "label": "Red" },
    { "value": "blue", "label": "Blue" }
  ]
}

Використовуйте "returnFormat": "both", щоб отримати і значення, і мітку:

PHP
echo $a['color']['value'];  // "red"
echo $a['color']['label'];  // "Red"

Такий самий підхід застосовується до типів radio і checkbox.

Перемикач і значення true/false

ACF:

PHP
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']

Blockstudio:

JSON
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }

ACF:

PHP
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']

// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];

Blockstudio:

JSON
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
PHP
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];

Колір і градієнт

ACF:

PHP
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']

Blockstudio:

JSON
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }

Тип color інтегрується з палітрою кольорів WordPress. Тип gradient надає інструмент вибору градієнта.

Числа, діапазони та дати

ACF:

PHP
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']

Blockstudio:

JSON
{ "id": "count", "type": "number", "label": "Count", "min": 1, "max": 10 }
{ "id": "opacity", "type": "range", "label": "Opacity", "min": 0, "max": 100, "step": 5 }
{ "id": "eventDate", "type": "date", "label": "Event Date" }

Поля з повторюваними елементами

Поле з повторюваними елементами в ACF безпосередньо відповідає типу repeater у Blockstudio. У шаблонах ACF зазвичай використовують цикли have_rows() / the_row() / get_sub_field() (get_field() для такого поля також повертає масив рядків); у Blockstudio є лише звичайний масив PHP, уже в $a.

ACF:

PHP
['name' => 'features', 'type' => 'repeater', 'sub_fields' => [
  ['name' => 'title', 'type' => 'text'],
  ['name' => 'description', 'type' => 'textarea'],
]]

// Template
if (have_rows('features')) :
  while (have_rows('features')) : the_row();
    echo get_sub_field('title');
    echo get_sub_field('description');
  endwhile;
endif;

Blockstudio:

JSON
{
  "id": "features",
  "type": "repeater",
  "label": "Features",
  "min": 1,
  "max": 10,
  "attributes": [
    { "id": "title", "type": "text", "label": "Title" },
    { "id": "description", "type": "textarea", "label": "Description" }
  ]
}
PHP
<?php foreach ($a['features'] as $feature) : ?>
  <h3><?php echo esc_html($feature['title']); ?></h3>
  <p><?php echo esc_html($feature['description']); ?></p>
<?php endforeach; ?>

У полях із повторюваними елементами Blockstudio можна створювати вкладені рівні (поле всередині поля) — до 3 рівнів.

Групи

Поле групи в ACF відповідає типу group у Blockstudio. До ID полів усередині груп додається ID групи як префікс.

ACF:

PHP
['name' => 'author', 'type' => 'group', 'sub_fields' => [
  ['name' => 'name', 'type' => 'text'],
  ['name' => 'role', 'type' => 'text'],
]]

// Template
$author = get_field('author');
echo $author['name'];
echo $author['role'];

Blockstudio:

JSON
{
  "id": "author",
  "type": "group",
  "title": "Author",
  "attributes": [
    { "id": "name", "type": "text", "label": "Name" },
    { "id": "role", "type": "text", "label": "Role" }
  ]
}
PHP
<?php $author = bs_get_group($a, 'author'); ?>
<p><?php echo esc_html($author['name']); ?></p>
<p><?php echo esc_html($author['role']); ?></p>

Допоміжна функція bs_get_group() вилучає префікс групи з ID полів, спрощуючи доступ до них. Без неї до полів довелося б звертатися як до $a['author_name'] і $a['author_role'].

Умовна логіка

І ACF, і Blockstudio підтримують умовну логіку для показу та приховування полів залежно від значень інших полів.

ACF:

PHP
['name' => 'showSubtitle', 'type' => 'true_false'],
[
  'name' => 'subtitle',
  'type' => 'text',
  'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]

Blockstudio:

JSON
{ "id": "showSubtitle", "type": "toggle", "label": "Show Subtitle" },
{
  "id": "subtitle",
  "type": "text",
  "label": "Subtitle",
  "conditions": [[{ "id": "showSubtitle", "operator": "==", "value": true }]]
}

Умови Blockstudio посилаються безпосередньо на ID полів, а не на їхні ключі. Доступні оператори: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio також підтримує глобальні умови на основі типу запису, ID запису, ролі користувача та ID користувача:

JSON
{
  "conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}

InnerBlocks

І ACF, і Blockstudio підтримують InnerBlocks для вкладення інших блоків у власний блок, використовуючи той самий тег <InnerBlocks /> і ті самі атрибути allowedBlocks, template та templateLock, тож цю частину шаблону зазвичай можна перенести без змін.

Blockstudio:

PHP
<div useBlockProps class="my-wrapper">
  <InnerBlocks
    allowedBlocks='<?php echo esc_attr(wp_json_encode(["core/heading", "core/paragraph", "core/image"])); ?>'
    template='<?php echo esc_attr(wp_json_encode([
      ["core/heading", ["placeholder" => "Section title"]],
      ["core/paragraph", ["placeholder" => "Section content"]]
    ])); ?>'
    templateLock="insert"
  />
</div>

У редакторі тег <InnerBlocks /> замінюється компонентом React, а на фронтенді — відрендереним вмістом блока.

Зберігання метаданих запису

І ACF Blocks, і Blockstudio за замовчуванням зберігають значення полів як атрибути блоку у вмісті запису, а не в метаданих запису. Це означає, що значення полів не можна запитувати за допомогою WP_Query, якщо не ввімкнути зберігання в метаданих.

ACF додав необов’язкове зберігання блоків у метаданих запису в ACF PRO 6.3 через usePostMeta: true — для одного блоку верхнього рівня на сторінку. У Blockstudio можна окремо ввімкнути цей режим для кожного поля за допомогою властивості storage:

JSON
{
  "id": "featured",
  "type": "toggle",
  "label": "Featured",
  "storage": {
    "type": "postMeta",
    "postMetaKey": "is_featured"
  }
}

Ключ метаданих автоматично реєструється через show_in_rest. Отримати доступ до нього можна будь-де за допомогою get_post_meta($post_id, 'is_featured', true).

Для значень на рівні всього сайту (наприклад, параметрів ACF) використовуйте сховище параметрів:

JSON
{
  "storage": {
    "type": "option",
    "optionKey": "site_company_name"
  }
}

Розширення наявних блоків

Правило розташування блоків у ACF додає групи полів лише до блоків ACF; воно не додає поля до базових блоків чи блоків сторонніх розробників. Для базових блоків, як-от заголовок, абзац, зображення та кнопка, у ACF є WordPress прив’язки блоків API, які з’єднують наявні атрибути блоків зі значеннями полів ACF. Blockstudio може додавати нові поля й елементи керування до будь-якого зареєстрованого блоку за допомогою файлів розширень.

Створіть файл розширення у каталозі blockstudio:

JSON
{
  "name": "core/heading",
  "blockstudio": {
    "extend": true,
    "attributes": [
      {
        "id": "accentColor",
        "type": "color",
        "label": "Accent Color",
        "set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
      }
    ]
  }
}

Властивість set автоматично застосовує значення поля до HTML блоку. Використовуйте символи підстановки, щоб одночасно розширити кілька блоків: "name": "core/*".

Контрольний список міграції

  1. Створіть папку блоку в theme/blockstudio/{block-name}/ за допомогою block.json і index.php.
  2. Перенесіть визначення полів із групи полів блоку (Local JSON, acf_add_local_field_group() або вбудованого масиву acf.fields) до масиву blockstudio.attributes у block.json. Замініть name на id, вилучіть key і за потреби змініть назви типів.
  3. Оновіть доступ до шаблонів: замініть get_field('name') на $a['name']. Замініть цикли have_rows() на foreach ($a['repeater'] as $item).
  4. Замініть get_sub_field() на прямий доступ до масиву: $item['fieldId'].
  5. Додайте useBlockProps до зовнішнього елемента шаблону для коректної інтеграції з редактором.
  6. Перенесіть умовну логіку з ACF у conditional_logic до Blockstudio у conditions, використовуючи ідентифікатори полів замість їхніх ключів.
  7. Додайте зберігання для всіх полів, які раніше запитувалися через get_post_meta() або використовувалися в WP_Query.
  8. Вилучіть код реєстрації ACF: виклики register_block_type() та ключі acf перенесених блоків (або їхні виклики acf_register_block_type()), а також групи їхніх полів — незалежно від того, де вони розташовані: у Local JSON, acf_add_local_field_group(), вбудованому масиві acf.fields чи в адмінпанелі.
  9. Перевірте в редакторі, чи правильно відображаються поля, а потім перевірте результат на сайті.