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:
{
"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>
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.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.json gebruikt het standaardformaat WordPress block.json met de sleutel blockstudio voor velden en configuratie:
{
"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:
['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" }
Gebruik voor bewerkbare tekst in de blokeditor (niet alleen een tekstinvoerveld) het type richtext met de component <RichText />:
{ "id": "heading", "type": "richtext" }
<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:
['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"] }
De structuur van het geretourneerde object is vergelijkbaar:
// 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:
[
'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" }
]
}
Gebruik "returnFormat": "both" om zowel de waarde als het label op te halen:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Hetzelfde patroon geldt voor de typen radio en checkbox.
Schakelaar en waar/onwaar
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Linkveld
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'];
Kleur en kleurverloop
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "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:
['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" }
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:
['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; ?>
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:
['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>
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:
['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 }]]
}
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:
{
"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:
<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:
{
"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:
{
"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:
{
"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
- Maak de blokmap aan in
theme/blockstudio/{block-name}/metblock.jsonenindex.php. - Verplaats de velddefinities uit de veldgroep van het blok (Local JSON,
acf_add_local_field_group()of een inline-arrayacf.fields) naar de arrayblockstudio.attributesinblock.json. Wijzignameinid, verwijderkeyen pas zo nodig de typenamen aan. - Werk de toegang in de template bij van
get_field('name')naar$a['name']. Vervanghave_rows()-lussen doorforeach ($a['repeater'] as $item). - Vervang
get_sub_field()door directe toegang tot de array:$item['fieldId']. - Voeg
useBlockPropstoe aan het buitenste element in je template voor een goede integratie met de editor. - Verplaats de voorwaardelijke logica van ACF’s
conditional_logicnaar Blockstudio’sconditionsen verwijs naar veld-ID’s in plaats van veldsleutels. - Voeg opslag toe voor velden die eerder werden opgevraagd via
get_post_meta()of werden gebruikt inWP_Query. - Verwijder de registratiescode voor ACF: de aanroepen van
register_block_type()en de sleutelsacfvan de gemigreerde blokken (of hun aanroepen vanacf_register_block_type()), en hun veldgroepen, of die nu in Local JSON,acf_add_local_field_group(), een inline-arrayacf.fieldsof de beheeromgeving staan. - Test in de editor of de velden correct verschijnen en controleer daarna de uitvoer aan de voorkant.