Vai al contenuto

Migrazione da ACF Blocks

Se avete creato blocchi WordPress personalizzati con ACF (Advanced Custom Fields), la migrazione a Blockstudio è semplice. I concetti sono simili: definite i campi, scrivete un template e il blocco appare nell’editor. Le differenze sono che Blockstudio individua autonomamente le cartelle dei blocchi, dichiara i campi nel proprio schema all’interno di block.json e fornisce a ogni template i valori dei campi in un unico array $a.

Questa guida illustra la migrazione passo dopo passo, con confronti affiancati tra i modelli di ACF e Blockstudio.

La differenza fondamentale

A partire da ACF 6.0, un blocco ACF è un block.json con una chiave acf che indica il template di rendering, e ogni cartella di blocchi viene registrata con una propria chiamata register_block_type(). I campi provengono da un gruppo di campi associato al blocco con una regola di posizione Block (creato nell’admin, sincronizzato tramite Local JSON o registrato con acf_add_local_field_group()) oppure, da ACF PRO 6.8.1, da un array acf.fields inline nello stesso block.json. Blockstudio sostituisce la chiamata di registrazione con il rilevamento automatico basato sui file: create una cartella con un block.json e un index.php e il blocco viene registrato automaticamente.

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>

Nessuna chiamata di registrazione né callback di rendering: la struttura delle cartelle costituisce la registrazione e i campi si trovano in block.json accanto al template. Il template legge $a invece di chiamare get_field().

Registrazione dei blocchi

ACF

I blocchi ACF attuali vengono registrati da un block.json con una chiave acf (renderTemplate o renderCallback, oltre a opzioni come blockVersion), caricato tramite una chiamata esplicita a register_block_type() per ogni cartella di blocchi, in genere in init in functions.php o in un file del plugin. I blocchi più vecchi potrebbero ancora usare acf_register_block_type(), che ACF documenta come deprecato da ACF 6.0; continua a funzionare, quindi migrate questi blocchi allo stesso modo.

Blockstudio

Create una cartella nella directory blockstudio/ del vostro tema (o blocks/, se preferite). Aggiungete un block.json con i metadati standard dei blocchi WordPress e una chiave blockstudio. Tutto qui.

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

block.json usa il formato standard WordPress block.json con la chiave blockstudio per i campi e la configurazione:

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

Accesso ai valori dei campi

È la modifica più comune da apportare durante la migrazione.

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

La variabile $a è una forma abbreviata di $attributes e contiene tutti i valori dei campi del blocco corrente. È sempre disponibile nel template, sia nell’editor sia nel frontend.

Variabili del template

Blockstudio mette a disposizione diverse variabili in ogni template:

Variabile Forma abbreviata Descrizione
$attributes $a Tutti i valori dei campi
$block $b Metadati del blocco (nome, titolo, dir, url, postId)
$context $c Contesto del blocco genitore
$content Contenuto di InnerBlocks
$post_id ID del post corrente (funziona nell’editor e nel frontend; post_id o postId in Twig)

Mappatura dei tipi di campo

La maggior parte dei tipi di campo ACF ha un equivalente diretto in Blockstudio. La sintassi JSON è diversa, ma i concetti corrispondono chiaramente.

Campi di testo e contenuto

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

Per il testo modificabile nell’editor dei blocchi (non solo un campo di testo), usate il tipo richtext con il componente <RichText />:

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

Campi immagine e file

I campi ACF image e file corrispondono al tipo Blockstudio files:

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

La struttura dell’oggetto restituito è simile:

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

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

Proprietà disponibili: ID, title, alt, caption, description, href, url, sizes. Le dimensioni sono in sizes, per esempio $a['photo']['sizes']['full-width'].

Selezione, pulsanti di scelta e caselle di controllo

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

Usate "returnFormat": "both" per ottenere sia il valore sia l’etichetta:

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

Lo stesso schema si applica ai tipi radio e checkbox.

Attivazione e valori vero/falso

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

Colore e gradiente

ACF:

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

Blockstudio:

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

Il tipo color si integra con la palette di colori WordPress. Il tipo gradient offre un selettore di gradienti.

Numero, intervallo e data

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

Campi ripetitore

Il campo ripetitore di ACF corrisponde direttamente al tipo Blockstudio di repeater. I template ACF di solito usano have_rows() / the_row() / get_sub_field() nei cicli (anche get_field() su un ripetitore restituisce un array di righe); Blockstudio dispone solo del semplice array PHP, già in $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; ?>

I campi ripetitore di Blockstudio supportano l’annidamento, cioè un ripetitore all’interno di un altro, fino a 3 livelli.

Gruppi

Il campo gruppo di ACF corrisponde al tipo group di Blockstudio. Gli ID dei campi all’interno dei gruppi hanno come prefisso l’ID del gruppo.

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>

L’helper bs_get_group() rimuove il prefisso del gruppo dagli ID dei campi, così potete accedervi in modo semplice. Senza, accedereste ai campi come $a['author_name'] e $a['author_role'].

Logica condizionale

Sia ACF sia Blockstudio supportano la logica condizionale per mostrare e nascondere i campi in base ai valori di altri campi.

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

Le condizioni Blockstudio fanno riferimento direttamente agli ID dei campi, non alle chiavi. Operatori disponibili: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio supporta anche condizioni globali basate sul tipo di post, sull’ID del post, sul ruolo dell’utente e sull’ID dell’utente:

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

InnerBlocks

Sia ACF sia Blockstudio supportano InnerBlocks per annidare altri blocchi nel vostro blocco personalizzato, con lo stesso tag <InnerBlocks /> e gli stessi attributi allowedBlocks, template e templateLock; perciò questa parte del template di solito si trasferisce senza modifiche.

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>

Il tag <InnerBlocks /> viene sostituito dal componente React nell’editor e dal contenuto del blocco renderizzato nel frontend.

Archiviazione dei metadati dei post

Sia ACF Blocks che Blockstudio salvano per impostazione predefinita i valori dei campi come attributi dei blocchi nel contenuto del post, non nei metadati del post. Ciò significa che i valori dei campi non sono interrogabili con WP_Query, a meno che non si scelga di salvarli nei metadati.

ACF ha aggiunto la possibilità di salvare facoltativamente i dati dei post nei metadati per i blocchi in ACF PRO 6.3 tramite usePostMeta: true, per un blocco di primo livello per pagina. Blockstudio offre un meccanismo facoltativo per ogni campo, usando la proprietà storage:

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

La chiave dei metadati viene registrata automaticamente con show_in_rest. Accedetevi ovunque con get_post_meta($post_id, 'is_featured', true).

Per i valori a livello di sito (come le pagine delle opzioni di ACF), usate l’archiviazione delle opzioni:

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

Estendere i blocchi esistenti

La regola di posizione dei blocchi di ACF collega i gruppi di campi solo ai blocchi di ACF; non aggiunge campi ai blocchi core o di terze parti. Il metodo di ACF per i blocchi core come Titolo, Paragrafo, Immagine e Pulsante è WordPress Block Bindings API, che collega gli attributi dei blocchi esistenti ai valori dei campi di ACF. Blockstudio può aggiungere nuovi campi e controlli a qualsiasi blocco registrato tramite file di estensione.

Create un file di estensione nella directory blockstudio:

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

La proprietà set applica automaticamente il valore del campo all’HTML del blocco. Usate i caratteri jolly per estendere più blocchi contemporaneamente: "name": "core/*".

Lista di controllo per la migrazione

  1. Create la cartella del blocco in theme/blockstudio/{block-name}/ con block.json e index.php.
  2. Spostate le definizioni dei campi dal gruppo di campi del blocco (Local JSON, acf_add_local_field_group() o un array acf.fields inline) all’array blockstudio.attributes in block.json. Cambiate name in id, rimuovete key e modificate i nomi dei tipi secondo necessità.
  3. Aggiornate l’accesso ai template da get_field('name') a $a['name']. Sostituite i cicli have_rows() con foreach ($a['repeater'] as $item).
  4. Sostituite get_sub_field() con l’accesso diretto all’array: $item['fieldId'].
  5. Aggiungete useBlockProps all’elemento più esterno del template per una corretta integrazione con l’editor.
  6. Spostate la logica condizionale da ACF’s conditional_logic a Blockstudio’s conditions, facendo riferimento agli ID dei campi invece che alle chiavi dei campi.
  7. Aggiungete l’archiviazione per tutti i campi interrogati in precedenza tramite get_post_meta() o usati in WP_Query.
  8. Rimuovete il codice di registrazione di ACF: le chiamate register_block_type() e le chiavi acf dei blocchi migrati (o le relative chiamate acf_register_block_type()), e i rispettivi gruppi di campi, che si trovino in Local JSON, acf_add_local_field_group(), un array acf.fields inline o nell’area di amministrazione.
  9. Verificate nell’editor che i campi siano visualizzati correttamente, poi controllate l’output del frontend.