Migration von ACF Blocks
Wenn du benutzerdefinierte WordPress-Blöcke mit ACF (Advanced Custom Fields) erstellst, ist die Migration zu Blockstudio unkompliziert. Die Konzepte ähneln sich: Du definierst Felder, schreibst ein Template und der Block erscheint im Editor. Die Unterschiede: Blockstudio erkennt Blockordner selbstständig, definiert Felder in einem eigenen Schema in block.json und übergibt jedem Template seine Feldwerte als ein $a-Array.
Dieser Leitfaden führt dich Schritt für Schritt durch die Migration und vergleicht dabei die Vorgehensweisen von ACF und Blockstudio.
Der zentrale Unterschied
Seit ACF 6.0 ist ein ACF-Block ein block.json mit einem acf-Schlüssel, der sein Render-Template benennt. Jeder Blockordner wird mit einem eigenen Aufruf von register_block_type() registriert. Die Felder stammen aus einer Feldgruppe, die über eine Block-Standortregel dem Block zugeordnet ist (im Admin erstellt und über Local JSON synchronisiert oder mit acf_add_local_field_group() registriert), oder seit ACF PRO 6.8.1 aus einem Inline-acf.fields-Array im selben block.json. Blockstudio ersetzt den Registrierungsaufruf durch dateibasierte automatische Erkennung: Erstelle einen Ordner mit einer block.json und einem index.php, dann wird der Block automatisch registriert.
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>
Kein Registrierungsaufruf und kein Render-Callback: Die Ordnerstruktur übernimmt die Registrierung, und die Felder stehen in block.json neben dem Template. Das Template liest $a aus, statt get_field() aufzurufen.
Blockregistrierung
ACF
Aktuelle ACF-Blöcke werden aus einem block.json mit einem Schlüssel acf registriert (renderTemplate oder renderCallback sowie Optionen wie blockVersion). Sie werden für jeden Blockordner durch einen expliziten Aufruf von register_block_type() geladen, üblicherweise in functions.php unter init oder in einer Plugin-Datei. Ältere Blöcke verwenden möglicherweise noch acf_register_block_type(). ACF dokumentiert dies seit ACF 6.0 als veraltet; es funktioniert weiterhin. Migriere diese Blöcke auf dieselbe Weise.
Blockstudio
Erstelle einen Ordner im Verzeichnis blockstudio/ deines Themes (oder in blocks/, wenn dir das lieber ist). Füge eine block.json mit den üblichen WordPress-Blockmetadaten und einem blockstudio-Schlüssel hinzu. Das ist alles.
theme/
└── blockstudio/
└── hero/
├── block.json
└── index.php
block.json verwendet das standardmäßige Format WordPress block.json] mit dem Schlüssel blockstudio für Felder und Konfiguration:
{
"name": "my-theme/hero",
"title": "Hero",
"category": "theme",
"icon": "cover-image",
"description": "Full-width hero section with background image.",
"blockstudio": {
"attributes": []
}
}
Feldwerte abrufen
Das ist die häufigste Änderung, die du bei einer Migration vornehmen wirst.
| ACF | Blockstudio |
|---|---|
get_field('title') |
$a['title'] |
get_field('title', $post_id) |
$a['title'] (immer verfügbar) |
the_field('title') |
<?php echo $a['title']; ?> |
have_rows('items') / the_row() |
foreach ($a['items'] as $item) |
get_sub_field('name') |
$item['name'] |
Die Variable $a ist eine Kurzform für $attributes und enthält alle Feldwerte des aktuellen Blocks. Sie ist im Template immer verfügbar, sowohl im Editor als auch im Frontend.
Template-Variablen
Blockstudio stellt in jedem Template mehrere Variablen bereit:
| Variable | Kurzform | Beschreibung |
|---|---|---|
$attributes |
$a |
Alle Feldwerte |
$block |
$b |
Blockmetadaten (Name, Titel, dir, url, postId) |
$context |
$c |
Kontext des übergeordneten Blocks |
$content |
InnerBlocks-Inhalt | |
$post_id |
Aktuelle Beitrags-ID (funktioniert im Editor und Frontend; post_id oder postId in Twig) |
Feldtypen zuordnen
Die meisten ACF-Feldtypen haben ein direktes Gegenstück in Blockstudio. Die Syntax von JSON ist anders, aber die Konzepte lassen sich gut zuordnen.
Text- und Inhaltsfelder
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" }
Für bearbeitbaren Text im Blockeditor (nicht nur ein Texteingabefeld) verwendest du den Typ richtext mit der Komponente <RichText />:
{ "id": "heading", "type": "richtext" }
<RichText attribute="heading" tag="h1" placeholder="Enter heading" />
Bild- und Dateifelder
Die Felder image und file von ACF entsprechen dem Typ files von 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"] }
Die Struktur des zurückgegebenen Objekts ist ähnlich:
// ACF
$image = get_field('photo');
echo $image['url'];
echo $image['alt'];
// Blockstudio
echo $a['photo']['url'];
echo $a['photo']['alt'];
Verfügbare Eigenschaften: ID, title, alt, caption, description, href, url, sizes. Die Abmessungen findest du in sizes, zum Beispiel $a['photo']['sizes']['full-width'].
Auswahl, Optionsfelder und Kontrollkästchen
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" }
]
}
Verwende "returnFormat": "both", um sowohl den Wert als auch die Bezeichnung abzurufen:
echo $a['color']['value']; // "red"
echo $a['color']['label']; // "Red"
Dasselbe Muster gilt für die Typen radio und checkbox.
Umschalter und Wahr/Falsch
ACF:
['name' => 'show_cta', 'type' => 'true_false', 'label' => 'Show CTA']
Blockstudio:
{ "id": "showCta", "type": "toggle", "label": "Show CTA" }
Link-Feld
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'];
Farbe und Farbverlauf
ACF:
['name' => 'bgColor', 'type' => 'color_picker', 'label' => 'Background']
Blockstudio:
{ "id": "bgColor", "type": "color", "label": "Background" }
{ "id": "bgGradient", "type": "gradient", "label": "Background Gradient" }
Der Typ color ist in die Farbpalette von WordPress integriert. Der Typ gradient bietet eine Auswahl für Farbverläufe.
Zahl, Bereich und 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" }
Repeater
Das Repeater-Feld von ACF entspricht direkt dem Typ repeater von Blockstudio. In ACF-Templates wird üblicherweise mit have_rows() / the_row() / get_sub_field() durchlaufen (get_field() gibt bei einem Repeater ebenfalls ein Array von Zeilen zurück). Blockstudio stellt nur das einfache PHP-Array bereit, bereits 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; ?>
Blockstudio-Repeater unterstützen Verschachtelungen von bis zu 3 Ebenen.
Gruppen
Das Gruppenfeld von ACF entspricht dem Typ group von Blockstudio. Feld-IDs innerhalb von Gruppen erhalten die Gruppen-ID als Präfix.
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>
Der Helfer bs_get_group() entfernt das Gruppenpräfix aus Feld-IDs und ermöglicht so den direkten Zugriff. Ohne ihn würdest du auf Felder als $a['author_name'] und $a['author_role'] zugreifen.
Bedingte Logik
Sowohl ACF als auch Blockstudio unterstützen bedingte Logik, um Felder anhand der Werte anderer Felder ein- und auszublenden.
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 }]]
}
Bedingungen in Blockstudio verweisen direkt auf Feld-IDs, nicht auf Feldschlüssel. Verfügbare Operatoren: ==, !=, includes, !includes, empty, !empty, <, >, <=, >=.
Blockstudio unterstützt außerdem globale Bedingungen anhand des Inhaltstyps, der Beitrags-ID, der Benutzerrolle und der Benutzer-ID:
{
"conditions": [[{ "type": "postType", "operator": "==", "value": "page" }]]
}
InnerBlocks
Sowohl ACF als auch Blockstudio unterstützen InnerBlocks, um andere Blöcke in deinen benutzerdefinierten Block zu verschachteln. Dafür werden dasselbe <InnerBlocks />-Tag und dieselben Attribute allowedBlocks, template und templateLock verwendet. Dieser Teil des Templates kann daher meist unverändert übernommen werden.
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>
Das Tag <InnerBlocks /> wird im Editor durch die Komponente React und im Frontend durch den gerenderten Blockinhalt ersetzt.
Speicherung in Post-Metadaten
Standardmäßig speichern sowohl ACF Blocks als auch Blockstudio Feldwerte als Blockattribute im Beitragsinhalt, nicht in den Post-Metadaten. Daher lassen sich Feldwerte nicht mit WP_Query abfragen, solange du die Speicherung in Metadaten nicht aktivierst.
ACF ergänzte in ACF PRO 6.3 die optionale Speicherung von Blockdaten in Post-Metadaten über usePostMeta: true, für einen Block auf oberster Ebene pro Seite. Blockstudio bietet einen optionalen Mechanismus pro Feld über die Eigenschaft storage:
{
"id": "featured",
"type": "toggle",
"label": "Featured",
"storage": {
"type": "postMeta",
"postMetaKey": "is_featured"
}
}
Der Metaschlüssel wird automatisch mit show_in_rest registriert. Mit get_post_meta($post_id, 'is_featured', true) kannst du überall darauf zugreifen.
Für websiteweite Werte, etwa von ACF-Optionsseiten, verwendest du die Speicherung in Optionen:
{
"storage": {
"type": "option",
"optionKey": "site_company_name"
}
}
Vorhandene Blöcke erweitern
Die Block-Standortregel von ACF ordnet Feldgruppen nur ACF-Blöcken zu. Sie fügt core- oder Drittanbieter-Blöcken keine Felder hinzu. Für Core-Blöcke wie Überschrift, Absatz, Bild und Button bietet ACF die WordPress Block Bindings API, die vorhandene Blockattribute mit ACF-Feldwerten verknüpfen. Blockstudio kann über Erweiterungsdateien neue Felder und Steuerelemente zu jedem registrierten Block hinzufügen.
Erstelle eine Erweiterungsdatei in deinem blockstudio-Verzeichnis:
{
"name": "core/heading",
"blockstudio": {
"extend": true,
"attributes": [
{
"id": "accentColor",
"type": "color",
"label": "Accent Color",
"set": [{ "attribute": "style", "value": "color: {attributes.accentColor}" }]
}
]
}
}
Die Eigenschaft set wendet den Feldwert automatisch auf HTML des Blocks an. Mit Platzhaltern kannst du mehrere Blöcke gleichzeitig erweitern: "name": "core/*".
Migrations-Checkliste
- Erstelle den Blockordner in
theme/blockstudio/{block-name}/mitblock.jsonundindex.php. - Übertrage die Felddefinitionen aus der Feldgruppe des Blocks (Local JSON,
acf_add_local_field_group()oder ein Inline-acf.fields-Array) in dasblockstudio.attributes-Array inblock.json. Änderenamezuid, entfernekeyund passe bei Bedarf die Typnamen an. - Aktualisiere den Zugriff im Template von
get_field('name')zu$a['name']. Ersetzehave_rows()-Schleifen durchforeach ($a['repeater'] as $item). - Ersetze
get_sub_field()durch direkten Arrayzugriff:$item['fieldId']. - Füge
useBlockPropszum äußersten Element im Template hinzu, damit die Integration in den Editor funktioniert. - Übertrage die bedingte Logik von
conditional_logicin ACF zuconditionsvon Blockstudio und verweise dabei auf Feld-IDs statt Feldschlüssel. - Füge Speicherung hinzu für Felder, die zuvor über
get_post_meta()abgefragt oder inWP_Queryverwendet wurden. - Entferne den ACF-Registrierungscode: die Aufrufe von
register_block_type()undacf-Schlüssel der migrierten Blöcke (oder ihre Aufrufe vonacf_register_block_type()) sowie ihre Feldgruppen, unabhängig davon, ob sie in Local JSON,acf_add_local_field_group(), einem Inline-acf.fields-Array oder im Admin liegen. - Teste im Editor, ob die Felder korrekt angezeigt werden, und prüfe anschließend die Ausgabe im Frontend.