Treci la conținut

Migrare de la ACF Blocks

Dacă ați creat blocuri WordPress personalizate cu ACF (Advanced Custom Fields), migrarea la Blockstudio este simplă. Conceptele sunt similare: definiți câmpuri, scrieți un șablon, iar blocul apare în editor. Diferențele sunt că Blockstudio descoperă singur dosarele blocurilor, declară câmpurile în propria schemă din block.json și transmite fiecărui șablon valorile câmpurilor într-o singură matrice $a.

Acest ghid prezintă migrarea pas cu pas, cu comparații alăturate ale modelelor ACF și Blockstudio.

Diferența fundamentală

Începând cu ACF 6.0, un bloc ACF este un block.json cu o cheie acf care îi indică șablonul de redare, iar fiecare dosar de bloc este înregistrat prin propriul apel register_block_type(). Câmpurile provin dintr-un grup de câmpuri asociat blocului printr-o regulă de localizare Block (creat în panoul de administrare, sincronizat prin Local JSON sau înregistrat cu acf_add_local_field_group()) ori, începând cu ACF PRO 6.8.1, dintr-o matrice acf.fields inline în același block.json. Blockstudio înlocuiește apelul de înregistrare cu detectarea automată bazată pe fișiere: creați un dosar care conține un block.json și un index.php, iar blocul se înregistrează automat.

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>

Nu există niciun apel de înregistrare și niciun apel de redare: structura dosarelor ține loc de înregistrare, iar câmpurile se află în block.json, lângă șablon. Șablonul citește $a în loc să apeleze get_field().

Înregistrarea blocurilor

ACF

Blocurile ACF actuale sunt înregistrate dintr-un block.json cu o cheie acf (renderTemplate sau renderCallback, plus opțiuni precum blockVersion), încărcate printr-un apel explicit register_block_type() pentru fiecare dosar de bloc, de obicei la init din functions.php sau într-un fișier de plugin. Blocurile mai vechi pot folosi în continuare acf_register_block_type(), pe care ACF îl consideră depreciat începând cu ACF 6.0; acesta continuă să funcționeze, așa că migrați blocurile respective în același mod.

Blockstudio

Creați un dosar în directorul blockstudio/ al temei (sau în blocks/, dacă preferați). Adăugați un block.json cu metadatele standard WordPress ale blocului și o cheie blockstudio. Gata.

Cod
theme/
└── blockstudio/
    └── hero/
        ├── block.json
        └── index.php

block.json folosește formatul standard WordPress block.json cu cheia blockstudio pentru câmpuri și configurare:

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

Accesarea valorilor câmpurilor

Aceasta este cea mai frecventă schimbare pe care o veți face în timpul migrării.

ACF Blockstudio
get_field('title') $a['title']
get_field('title', $post_id) $a['title'] (disponibil întotdeauna)
the_field('title') <?php echo $a['title']; ?>
have_rows('items') / the_row() foreach ($a['items'] as $item)
get_sub_field('name') $item['name']

Variabila $a este prescurtarea pentru $attributes și conține toate valorile câmpurilor blocului curent. Este disponibilă întotdeauna în șablon, atât în editor, cât și în interfața publică.

Variabilele șablonului

Blockstudio furnizează mai multe variabile în fiecare șablon:

Variabilă Prescurtare Descriere
$attributes $a Toate valorile câmpurilor
$block $b Metadatele blocului (name, title, dir, url, postId)
$context $c Contextul blocului părinte
$content Conținutul InnerBlocks
$post_id ID-ul publicației curente (funcționează în editor și în interfața publică; post_id sau postId în Twig)

Corespondența tipurilor de câmpuri

Majoritatea tipurilor de câmpuri ACF au un echivalent direct în Blockstudio. Sintaxa JSON diferă, însă conceptele corespund bine.

Câmpuri de text și conținut

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" }

Pentru text editabil în editorul de blocuri (nu doar într-un câmp de introducere text), folosiți tipul richtext cu componenta <RichText />:

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

Câmpuri pentru imagini și fișiere

Câmpurile image și file din ACF corespund tipului files din 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"] }

Structura obiectului returnat este similară:

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

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

Proprietăți disponibile: ID, title, alt, caption, description, href, url, sizes. Dimensiunile sunt în sizes, de exemplu $a['photo']['sizes']['full-width'].

Selectoare, butoane radio și casete de selectare

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" }
  ]
}

Folosiți "returnFormat": "both" pentru a obține atât valoarea, cât și eticheta:

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

Același model se aplică tipurilor radio și checkbox.

Comutare și adevărat/fals

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'];

Culoare și gradient

ACF:

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

Blockstudio:

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

Tipul color se integrează cu paleta de culori WordPress. Tipul gradient oferă un selector de gradient.

Număr, interval și dată

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" }

Câmpuri repetabile

Câmpul repetabil din ACF corespunde direct tipului repeater din Blockstudio. Șabloanele ACF parcurg de obicei datele cu have_rows() / the_row() / get_sub_field() (și get_field() într-un câmp repetabil returnează o matrice de rânduri); Blockstudio are doar matricea simplă PHP, deja în $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; ?>

Câmpurile repetabile Blockstudio acceptă până la 3 niveluri de imbricare (câmp repetabil în interiorul altui câmp repetabil).

Grupuri

Câmpul de grup din ACF corespunde tipului group din Blockstudio. ID-urile câmpurilor din grupuri au ca prefix ID-ul grupului.

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>

Funcția de ajutor bs_get_group() elimină prefixul grupului din ID-urile câmpurilor, oferindu-vă acces direct. Fără ea, ați accesa câmpurile ca $a['author_name'] și $a['author_role'].

Logică condițională

Atât ACF, cât și Blockstudio acceptă logică condițională pentru afișarea și ascunderea câmpurilor în funcție de valorile altor câmpuri.

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 }]]
}

Condițiile Blockstudio fac referire directă la ID-urile câmpurilor (nu la cheile câmpurilor). Operatorii disponibili: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio acceptă și condiții globale bazate pe tipul publicației, ID-ul publicației, rolul utilizatorului și ID-ul utilizatorului:

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

InnerBlocks

Atât ACF, cât și Blockstudio acceptă InnerBlocks pentru imbricarea altor blocuri în blocul personalizat, cu aceeași etichetă <InnerBlocks /> și aceleași atribute allowedBlocks, template și templateLock, așa că această parte a șablonului se transferă de obicei fără modificări.

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>

Eticheta <InnerBlocks /> este înlocuită cu componenta React în editor și cu conținutul blocului redat în interfața publică.

Stocarea metadatelor publicației

Atât ACF Blocks, cât și Blockstudio stochează implicit valorile câmpurilor ca atribute ale blocurilor în conținutul articolului, nu în metadatele articolului. Asta înseamnă că valorile câmpurilor nu pot fi interogate cu WP_Query decât dacă optați pentru stocarea în metadate.

ACF a adăugat stocarea opțională în metadatele articolului pentru blocuri în ACF PRO 6.3, prin usePostMeta: true, pentru câte un bloc de nivel superior pe pagină. Blockstudio oferă un mecanism opțional pentru fiecare câmp, folosind proprietatea storage:

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

Cheia de metadate este înregistrată automat cu show_in_rest. O puteți accesa oriunde cu get_post_meta($post_id, 'is_featured', true).

Pentru valori la nivelul întregului site (precum paginile de opțiuni ACF), folosiți stocarea în opțiuni:

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

Extinderea blocurilor existente

Regula de localizare a blocurilor din ACF atașează grupuri de câmpuri doar blocurilor ACF; nu adaugă câmpuri blocurilor de bază sau celor terțe. Pentru blocurile de bază precum Heading, Paragraph, Image și Button, ACF folosește WordPress Block Bindings API, care conectează atributele existente ale blocurilor la valorile câmpurilor ACF. Blockstudio poate adăuga câmpuri și controale noi oricărui bloc înregistrat, prin fișiere de extensie.

Creați un fișier de extensie în directorul blockstudio:

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

Proprietatea set aplică automat valoarea câmpului blocului HTML. Folosiți caractere wildcard pentru a extinde mai multe blocuri simultan: "name": "core/*".

Listă de verificare pentru migrare

  1. Creați folderul blocului în theme/blockstudio/{block-name}/, cu block.json și index.php.
  2. Mutați definițiile câmpurilor din grupul de câmpuri al blocului (Local JSON, acf_add_local_field_group() sau un tablou acf.fields inline) în tabloul blockstudio.attributes din block.json. Schimbați name în id, eliminați key și ajustați numele tipurilor după caz.
  3. Actualizați accesarea din șablon de la get_field('name') la $a['name']. Înlocuiți buclele have_rows() cu foreach ($a['repeater'] as $item).
  4. Înlocuiți get_sub_field() cu accesarea directă a tabloului: $item['fieldId'].
  5. Adăugați useBlockProps la elementul exterior din șablon, pentru integrarea corectă în editor.
  6. Mutați logica condițională din conditional_logic din ACF în conditions din Blockstudio, folosind ID-urile câmpurilor în locul cheilor câmpurilor.
  7. Adăugați stocare pentru orice câmpuri interogate anterior prin get_post_meta() sau folosite în WP_Query.
  8. Eliminați codul de înregistrare ACF: apelurile register_block_type() și cheile acf ale blocurilor migrate (sau apelurile lor acf_register_block_type()), precum și grupurile lor de câmpuri, indiferent dacă se află în Local JSON, acf_add_local_field_group(), într-un tablou acf.fields inline sau în zona de administrare.
  9. Testați în editor pentru a verifica dacă câmpurile apar corect, apoi verificați rezultatul din partea publică.