Миграция от ACF Blocks
Ако сте създавали персонализирани блокове WordPress с ACF (Advanced Custom Fields), миграцията към Blockstudio е лесна. Понятията са сходни: дефинирате полета, пишете шаблон и блокът се появява в редактора. Разликите са, че Blockstudio открива сам папките с блокове, дефинира полетата в собствена схема във block.json и подава на всеки шаблон стойностите на полетата в един масив $a.
Това ръководство разглежда миграцията стъпка по стъпка със съпоставки на моделите в ACF и Blockstudio.
Основната разлика
От ACF 6.0 насам блокът ACF е block.json с ключ acf, който задава шаблона за визуализиране, а всяка папка с блок се регистрира със собствено извикване на register_block_type(). Полетата идват от група полета, свързана с блока чрез правило за местоположение на блок (създадена в административния панел, синхронизирана чрез Local JSON или регистрирана с acf_add_local_field_group()), или, от ACF PRO 6.8.1 насам, от вграден масив acf.fields в същия block.json. Blockstudio заменя извикването за регистрация с автоматично откриване на файлове: създайте папка с block.json и index.php и блокът ще бъде регистриран автоматично.
ACF:
{
"name": "acf/hero",
"title": "Hero",
"acf": {
"renderTemplate": "template.php"
}
}
add_action( 'init', function () {
register_block_type( __DIR__ . '/blocks/hero' );
} );
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
$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:
{
"name": "my-theme/hero",
"title": "Hero",
"blockstudio": {
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "image", "type": "files", "label": "Background", "multiple": false }
]
}
}
<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 за полетата и конфигурацията:
{
"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 |
Метаданни на блока (name, title, dir, url, postId) |
$context |
$c |
Контекст на родителския блок |
$content |
Съдържание на InnerBlocks | |
$post_id |
ID на текущата публикация (работи в редактора и фронтенда; post_id или postId във Twig) |
Съпоставяне на типовете полета
Повечето типове полета на ACF имат пряк еквивалент в Blockstudio. Синтаксисът на JSON е различен, но понятията се съпоставят лесно.
Текстови полета и полета за съдържание
ACF:
['name' => 'title', 'type' => 'text', 'label' => 'Title', 'default_value' => 'Hello']
['name' => 'bio', 'type' => 'textarea', 'label' => 'Bio', 'rows' => 4]
['name' => 'content', 'type' => 'wysiwyg', 'label' => 'Content']
Blockstudio:
{ "id": "title", "type": "text", "label": "Title", "default": "Hello" }
{ "id": "bio", "type": "textarea", "label": "Bio", "rows": 4 }
{ "id": "content", "type": "wysiwyg", "label": "Content" }
За редактируем текст в редактора на блокове (а не само за текстово поле) използвайте типа richtext с компонента <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Полета за изображения и файлове
Полетата image и file на ACF съответстват на типа files на Blockstudio:
ACF:
['name' => 'photo', 'type' => 'image', 'return_format' => 'array']
['name' => 'gallery', 'type' => 'gallery', 'return_format' => 'array']
['name' => 'document', 'type' => 'file', 'return_format' => 'array']
Blockstudio:
{ "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"] }
Структурата на върнатия обект е подобна:
// 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:
[
'name' => 'color',
'type' => 'select',
'choices' => ['red' => 'Red', 'blue' => 'Blue'],
'return_format' => 'value',
]
Blockstudio:
{
"id": "color",
"type": "select",
"label": "Color",
"options": [
{ "value": "red", "label": "Red" },
{ "value": "blue", "label": "Blue" }
]
}
Използвайте "returnFormat": "both", за да получите както стойността, така и етикета:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Същият модел важи за типовете radio и checkbox.
Превключвател и вярно/невярно
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Поле за връзка
ACF:
['name' => 'cta', 'type' => 'link', 'return_format' => 'array']
// Template
$link = get_field('cta');
echo $link['url'];
echo $link['title'];
echo $link['target'];
Blockstudio:
{ "id": "cta", "type": "link", "label": "CTA", "opensInNewTab": true }
echo $a['cta']['url'];
echo $a['cta']['title'];
echo $a['cta']['target'];
Цвят и градиент
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
Типът color се интегрира с цветовата палитра на WordPress. Типът gradient предоставя инструмент за избор на градиент.
Число, диапазон и дата
ACF:
['name' => 'count', 'type' => 'number', 'min' => 1, 'max' => 10]
['name' => 'opacity', 'type' => 'range', 'min' => 0, 'max' => 100, 'step' => 5]
['name' => 'eventDate', 'type' => 'date_picker']
Blockstudio:
{ "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:
['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:
{
"id": "features",
"type": "repeater",
"label": "Features",
"min": 1,
"max": 10,
"attributes": [
{ "id": "title", "type": "text", "label": "Title" },
{ "id": "description", "type": "textarea", "label": "Description" }
]
}
<?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:
['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:
{
"id": "author",
"type": "group",
"title": "Author",
"attributes": [
{ "id": "name", "type": "text", "label": "Name" },
{ "id": "role", "type": "text", "label": "Role" }
]
}
<?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:
['name' => 'showSubtitle', 'type' => 'true_false'],
[
'name' => 'subtitle',
'type' => 'text',
'conditional_logic' => [[['field' => 'field_showSubtitle', 'operator' => '==', 'value' => '1']]]
]
Blockstudio:
{ "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 на потребителя:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
И ACF, и Blockstudio поддържат InnerBlocks за влагане на други блокове във вашия персонализиран блок със същия етикет <InnerBlocks /> и същите атрибути allowedBlocks, template и templateLock, така че тази част от шаблона обикновено остава непроменена.
Blockstudio:
<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:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
Ключът за метаданните се регистрира автоматично с show_in_rest. Достъп до него отвсякъде чрез get_post_meta($post_id, 'is_featured', true).
За стойности за целия сайт (като страниците с настройки на ACF) използвайте съхранение в опциите:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Разширяване на съществуващи блокове
Правилото за местоположение на блокове в ACF прикрепя групи полета само към блокове на ACF; то не добавя полета към основни или блокове на трети страни. Начинът на ACF за работа с основни блокове като Heading, Paragraph, Image и Button е WordPress Block Bindings API, което свързва съществуващите атрибути на блокове със стойности на полета в ACF. Blockstudio може да добавя нови полета и контроли към всеки регистриран блок чрез файлове за разширения.
Създайте файл за разширение в директорията си blockstudio:
{
"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/*".
Контролен списък за миграция
- Създайте папката на блока в
theme/blockstudio/{block-name}/сblock.jsonиindex.php. - Преместете дефинициите на полетата от групата полета на блока (Local JSON,
acf_add_local_field_group()или вграден масивacf.fields) в масиваblockstudio.attributesвblock.json. Променетеnameнаid, премахнетеkeyи коригирайте имената на типовете при нужда. - Актуализирайте достъпа в шаблоните от
get_field('name')на$a['name']. Заменете циклитеhave_rows()сforeach ($a['repeater'] as $item). - Заменете
get_sub_field()с директен достъп до масива:$item['fieldId']. - Добавете
useBlockPropsкъм най-външния елемент в шаблона за правилна интеграция с редактора. - Преместете условната логика от ACF на
conditional_logicкъм Blockstudio наconditions, като използвате ID-тата на полетата вместо ключовете им. - Добавете съхранение за всички полета, които преди са били заявявани чрез
get_post_meta()или използвани вWP_Query. - Премахнете кода за регистрация на ACF: извикванията
register_block_type()и ключоветеacfна мигрираните блокове (или извикванията им наacf_register_block_type()), както и групите им полета, независимо дали са в Local JSON,acf_add_local_field_group(), вграден масивacf.fieldsили администраторския панел. - Тествайте в редактора, за да проверите дали полетата се показват правилно, след което проверете резултата във фронтенда.