Ga naar de inhoud

Migreren vanaf ACF Blocks

Als je aangepaste WordPress-blokken bouwt met ACF (Advanced Custom Fields), is migreren naar Blockstudio eenvoudig. De concepten zijn vergelijkbaar: je definieert velden, schrijft een template en het blok verschijnt in de editor. De verschillen zijn dat Blockstudio blokmappen zelf ontdekt, velden in een eigen schema in block.json declareert en elke template de veldwaarden geeft als één array van $a.

Deze gids behandelt de migratie stap voor stap, met vergelijkingen naast elkaar van patronen voor ACF en Blockstudio.

Het belangrijkste verschil

Sinds ACF 6.0 is een ACF-blok een block.json met een acf-sleutel die het render-template benoemt. Elke blokmap wordt geregistreerd met een eigen aanroep van register_block_type(). De velden komen uit een veldgroep die aan het blok is gekoppeld met een bloklocatieregel (gemaakt in de beheeromgeving, gesynchroniseerd via Local JSON of geregistreerd met acf_add_local_field_group()), of, sinds ACF PRO 6.8.1, uit een inline-array van acf.fields in dezelfde block.json. Blockstudio vervangt de registratieaanroep door automatische detectie op basis van bestanden: maak een map met een block.json en een index.php, en het blok wordt automatisch geregistreerd.

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>

Geen registratieaanroep en geen rendercallback: de mapstructuur is de registratie en de velden staan in block.json naast het template. Het template leest $a uit in plaats van get_field() aan te roepen.

Blokregistratie

ACF

Huidige ACF-blokken worden geregistreerd vanuit een block.json met een acf-sleutel (renderTemplate of renderCallback, plus opties zoals blockVersion), geladen via een expliciete aanroep van register_block_type() per blokmap, meestal op init in functions.php of in een pluginbestand. Oudere blokken gebruiken mogelijk nog acf_register_block_type(), waarvan ACF sinds ACF 6.0 de status verouderd heeft gedocumenteerd; het blijft werken, dus migreer die blokken op dezelfde manier.

Blockstudio

Maak een map in de blockstudio/-directory van je theme (of in blocks/ als je dat liever hebt). Voeg een block.json toe met de standaardblokmetadata van WordPress en een sleutel blockstudio. Dat is alles.

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

block.json gebruikt het standaardformaat WordPress block.json met de sleutel blockstudio voor velden en configuratie:

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

Veldwaarden uitlezen

Dit is de meest voorkomende wijziging die je tijdens de migratie zult doorvoeren.

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

De variabele $a is een verkorte schrijfwijze voor $attributes en bevat alle veldwaarden van het huidige blok. Deze is altijd beschikbaar in het template, zowel in de editor als op de frontend.

Templatevariabelen

Blockstudio biedt verschillende variabelen in elk template:

Variabele Verkorte schrijfwijze Beschrijving
$attributes $a Alle veldwaarden
$block $b Blokmetadata (name, title, dir, url, postId)
$context $c Context van het bovenliggende blok
$content Inhoud van InnerBlocks
$post_id Huidige post-ID (werkt in editor en frontend; post_id of postId in Twig)

Toewijzing van veldtypen

De meeste veldtypen van ACF hebben een rechtstreeks equivalent in Blockstudio. De syntaxis van JSON is anders, maar de concepten komen goed overeen.

Tekst- en inhoudsvelden

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

Gebruik voor bewerkbare tekst in de blokeditor (niet alleen een tekstinvoerveld) het type richtext met de component <RichText />:

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

Afbeeldings- en bestandsvelden

De velden ACF image en file komen overeen met het type Blockstudio van 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"] }

De structuur van het geretourneerde object is vergelijkbaar:

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

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

Beschikbare eigenschappen: ID, title, alt, caption, description, href, url, sizes. De afmetingen staan in sizes, bijvoorbeeld $a['photo']['sizes']['full-width'].

Keuzelijst, keuzerondje en selectievakje

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

Gebruik "returnFormat": "both" om zowel de waarde als het label op te halen:

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

Hetzelfde patroon geldt voor de typen radio en checkbox.

Schakelaar en waar/onwaar

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

Kleur en kleurverloop

ACF:

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

Blockstudio:

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

Het type color is geïntegreerd met het kleurenpalet van WordPress. Het type gradient biedt een kleurverloopkiezer.

Getal, bereik en datum

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

Herhaalvelden

Het herhaalveld van ACF komt rechtstreeks overeen met het type repeater van Blockstudio. Templates van ACF gebruiken meestal have_rows() / the_row() / get_sub_field() in lussen (get_field() op een herhaalveld retourneert ook een array met rijen); Blockstudio heeft alleen de gewone array van PHP, al 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; ?>

Met Blockstudio kunnen herhaalvelden tot 3 niveaus diep genest worden (een herhaalveld in een herhaalveld).

Groepen

Het groepsveld van ACF komt overeen met het type group van Blockstudio. Veld-ID’s binnen groepen krijgen het groeps-ID als voorvoegsel.

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>

De helper bs_get_group() verwijdert het groepsvoorvoegsel uit veld-ID’s, zodat je ze direct kunt gebruiken. Zonder deze helper zou je velden benaderen als $a['author_name'] en $a['author_role'].

Voorwaardelijke logica

Zowel ACF als Blockstudio ondersteunen voorwaardelijke logica om velden te tonen of te verbergen op basis van de waarden van andere velden.

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

Voorwaarden in Blockstudio verwijzen rechtstreeks naar veld-ID’s (niet naar veldsleutels). Beschikbare operatoren: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.

Blockstudio ondersteunt ook globale voorwaarden op basis van het berichttype, de bericht-ID, de gebruikersrol en de gebruikers-ID:

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

InnerBlocks

Zowel ACF als Blockstudio ondersteunen InnerBlocks om andere blokken in je aangepaste blok te nesten, met dezelfde <InnerBlocks />-tag en dezelfde attributen allowedBlocks, template en templateLock. Dit deel van een template kan daardoor meestal ongewijzigd worden overgezet.

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>

De tag <InnerBlocks /> wordt in de editor vervangen door de component React en op de frontend door de gerenderde blokinhoud.

Opslag van berichtmetadata

Zowel ACF Blocks als Blockstudio slaan veldwaarden standaard op als blokkenmerken in de berichtinhoud, niet in berichtmeta. Dat betekent dat veldwaarden niet opvraagbaar zijn met WP_Query, tenzij u opslag in meta inschakelt.

ACF heeft in ACF PRO 6.3 optionele opslag van berichtmeta voor blokken toegevoegd via usePostMeta: true, voor één blok op het hoogste niveau per pagina. Blockstudio heeft een optioneel mechanisme per veld, met de eigenschap storage:

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

De metasleutel wordt automatisch geregistreerd met show_in_rest. Gebruik deze overal met get_post_meta($post_id, 'is_featured', true).

Gebruik voor waarden die voor de hele site gelden (zoals optiepagina’s van ACF) opslag in opties:

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

Bestaande blokken uitbreiden

De bloklocatieregel van ACF koppelt veldgroepen alleen aan ACF-blokken; er worden geen velden toegevoegd aan kernblokken of blokken van derden. Voor kernblokken zoals Kop, Alinea, Afbeelding en Knop is de route van ACF WordPress API, die bestaande blokkenmerken koppelt aan veldwaarden van ACF. Blockstudio kan met uitbreidingsbestanden nieuwe velden en bedieningselementen toevoegen aan elk geregistreerd blok.

Maak een uitbreidingsbestand in je blockstudio-map:

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

De eigenschap set past de veldwaarde automatisch toe op de HTML van het blok. Gebruik jokertekens om meerdere blokken tegelijk uit te breiden: "name": "core/*".

Migratiechecklist

  1. Maak de blokmap aan in theme/blockstudio/{block-name}/ met block.json en index.php.
  2. Verplaats de velddefinities uit de veldgroep van het blok (Local JSON, acf_add_local_field_group() of een inline-array acf.fields) naar de array blockstudio.attributes in block.json. Wijzig name in id, verwijder key en pas zo nodig de typenamen aan.
  3. Werk de toegang in de template bij van get_field('name') naar $a['name']. Vervang have_rows()-lussen door foreach ($a['repeater'] as $item).
  4. Vervang get_sub_field() door directe toegang tot de array: $item['fieldId'].
  5. Voeg useBlockProps toe aan het buitenste element in je template voor een goede integratie met de editor.
  6. Verplaats de voorwaardelijke logica van ACF’s conditional_logic naar Blockstudio’s conditions en verwijs naar veld-ID’s in plaats van veldsleutels.
  7. Voeg opslag toe voor velden die eerder werden opgevraagd via get_post_meta() of werden gebruikt in WP_Query.
  8. Verwijder de registratiescode voor ACF: de aanroepen van register_block_type() en de sleutels acf van de gemigreerde blokken (of hun aanroepen van acf_register_block_type()), en hun veldgroepen, of die nu in Local JSON, acf_add_local_field_group(), een inline-array acf.fields of de beheeromgeving staan.
  9. Test in de editor of de velden correct verschijnen en controleer daarna de uitvoer aan de voorkant.