ACF für Anfänger: Eine vollständige Schritt-für-Schritt-Anleitung zu benutzerdefinierten Feldern in WordPress

Lesezeit: ~12 Min. · Niveau: mittel

Der native WordPress-Editor endet bei Titel, Inhalt und Beitragsbild. Sie möchten einen Untertitel für den Beitrag, einen Aktionspreis für ein Produkt oder ein Markenlogo an eine Taxonomie anheften? Die klickbaren Optionen sind an dieser Stelle zu Ende. Advanced Custom Fields löst dieses Problem seit über einem Jahrzehnt – über 2 Mio. aktive Installationen im WordPress.org-Repository sprechen für sich. Diese Anleitung führt vom Fundament – was rohe Custom Fields sind – über die Installation von ACF und die erste Feldgruppe bis hin zu Szenarien mit ACF PRO, WooCommerce und der Registrierung von Custom Post Types ohne zusätzliche Plugins. Ich bringe außerdem den Kontext für 2026 auf den aktuellen Stand: WordPress 6.5–7.0, PHP 8.x, der Fork Secure Custom Fields und die Konsequenzen, die sich daraus für Updates ergeben.

1. ACF ersetzt rohe Custom Fields durch eine grafische Oberfläche für Text-, Bild-, Datums-, Galerie- und Beziehungsfelder – ohne ein eigenes Plugin zu schreiben.
2. Die Daten von ACF landen in der Tabelle wp_postmeta. Nach der Deaktivierung des Plugins bleiben sie in der Datenbank – Sie verlieren nur die komfortable API.
3. Seit Version 6.1 registriert ACF (Free und PRO) Custom Post Types sowie Taxonomien direkt im Panel – ohne Custom Post Type UI.
4. ACF PRO (ab 49 USD/Jahr) ergänzt Repeater, Flexible Content, Gallery, Clone, Options Pages und ACF Blocks für eigene Gutenberg-Blöcke.
5. Umgebung 2026: WordPress 6.5–7.0, PHP mindestens 7.4, in der Praxis 8.3, ACF 6.1+. Denken Sie an den Fork Secure Custom Fields im WordPress.org-Repository.

Was sind benutzerdefinierte Felder in WordPress und warum reicht der native Mechanismus nicht aus?

Custom Fields (benutzerdefinierte Felder) sind ein in WordPress eingebauter Mechanismus – er speichert Schlüssel-Wert-Paare, die an einen Beitrag, eine Seite oder einen anderen Inhaltstyp angeheftet sind. Die Daten landen als Metadaten in der Tabelle wp_postmeta, und im Theme lesen Sie sie mit der Funktion get_post_meta() aus. Der Mechanismus existiert seit den frühesten Versionen von WordPress. Heute ist er für einen Redakteur, der Meta-Keys nicht von Hand eintippen möchte, zu roh.

Wie aktiviert man das native Custom-Fields-Panel im Gutenberg-Editor und im klassischen Editor?

Im Block-Editor Gutenberg ist das Custom-Fields-Panel standardmäßig ausgeblendet. Sie aktivieren es in drei Klicks: die drei Punkte oben rechts im Editor, „Preferences“, Reiter „General“, Bereich „Advanced“, Schalter „Custom fields“, Schaltfläche „Enable & Reload Page“. Die Seite wird neu geladen, und unter dem Inhalt erscheint das klassische Schlüssel-Wert-Panel.

Im klassischen TinyMCE-Editor ist der Weg kürzer. Klicken Sie oben rechts auf „Screen Options“ und aktivieren Sie die Checkbox „Custom Fields“. Das Panel erscheint sofort unter dem Text-Editor, ohne dass die Seite neu geladen werden muss.

Welche Einschränkungen haben rohe Custom Fields für einen Redakteur?

Rohe Custom Fields bestehen aus zwei Textfeldern: „Name“ und „Value“. Alles ist Text. Ohne Validierung, ohne Typen, ohne Hinweise. Der Redakteur muss sich den exakten Meta-Key merken (z. B. subtitle), ihn ohne Tippfehler eingeben und den Wert wie einen einfachen String behandeln – selbst dann, wenn es sich eigentlich um ein Datum oder eine URL handeln soll.

Häufiger Fehler: Der Redakteur trägt den Wert unter dem Schlüssel subTitle mit großem Anfangsbuchstaben ein, das Theme erwartet aber subtitle. Das Feld existiert in der Datenbank, wird im Frontend aber niemals angezeigt – weil der Meta-Name case-sensitive ist. Das rohe Panel gibt Ihnen dazu keinen Hinweis.

Es fehlen Feldtypen wie Image Picker, Date Picker, Select, Gallery oder Beziehungen zu anderen Beiträgen. Es fehlt die Gruppierung in logische Abschnitte – „SEO-Daten“ getrennt von „CTA-Daten“. Es fehlen Bedingungsregeln nach dem Muster „dieses Feld nur für den Produkttyp anzeigen“. All das ergänzt ACF.

Was ist Advanced Custom Fields und wie erweitert es die Möglichkeiten von WordPress?

Advanced Custom Fields ist ein Plugin, das WordPress um eine grafische Oberfläche zum Erstellen von Gruppen benutzerdefinierter Felder ergänzt. Jede Gruppe (Field Group) ist ein logisches Set von Feldern, das Sie bestimmten Bearbeitungsbildschirmen zuweisen – Beiträgen, Seiten, WooCommerce-Produkten, Taxonomien oder Options Pages.

Advanced Custom Fields is a WordPress plugin which allows you to add extra content fields to your WordPress edit screens.

Offizielle ACF-Dokumentation — Getting Started with ACF

Was unterscheidet ACF Free von ACF PRO?

ACF Free ist die Version aus dem WordPress.org-Repository. Kostenlos, mit den grundlegenden Feldtypen: Text, Textarea, Number, Email, Image, File, Select, Checkbox, Radio, True/False, Page Link, Post Object, Taxonomy, User, Date Picker, Color Picker. Seit Version 6.1 unterstützt sie auch die Registrierung von Custom Post Types und Taxonomien – zuvor war das eine exklusive PRO-Funktion.

ACF PRO ergänzt Felder, die sich sinnvoll durch nichts anderes ersetzen lassen: Repeater (wiederholbare Zeilen), Flexible Content (modulare Layouts), Gallery, Clone (Kopieren von Feld-Definitionen), Options Pages (globale Website-Einstellungen) sowie ACF Blocks (eigene Gutenberg-Blöcke auf Basis von ACF-Feldern).

Warum wurde ACF zum Standard für die Erweiterung des WordPress-Editors?

Über 2 Mio. aktive Installationen im WordPress.org-Repository sind ein handfester sozialer Beweis. Es gibt drei Gründe. Erstens werden die Daten in der nativen Tabelle wp_postmeta gespeichert – kein Vendor-Lock-in, kein eigenes Format. Zweitens ist die Frontend-API (get_field(), the_field()) konsistent und vorhersehbar. Sie funktioniert identisch im klassischen Theme und in Gutenberg-Blöcken. Drittens sind Dokumentation und Beispiele umfangreich, und die Community hat die meisten typischen Probleme bereits in Foren und auf Stack Overflow gelöst.

Was ist Secure Custom Fields (SCF) und was bedeutet der Konflikt von 2024 für den Nutzer?

Secure Custom Fields ist ein Fork von ACF, der seit Herbst 2024 im Rahmen des WordPress.org-Projekts gepflegt wird. Er entstand im Zuge des Konflikts zwischen Automattic und WP Engine – WordPress.org übernahm vorübergehend das ACF-Repository und schob den Fork unter dem gleichen Plugin-Namen im Admin-Panel als Update unter. Nach dem Gerichtsurteil erhielt WP Engine die Kontrolle über das Original zurück, aber SCF blieb als paralleles Plugin unter der Adresse developer.wordpress.org/secure-custom-fields/ bestehen.

Falle: Wenn Sie ACF im Herbst 2024 über das WordPress-Panel aktualisiert haben, ist es möglich, dass jetzt der Fork SCF installiert ist und nicht das originale ACF. Prüfen Sie unter „Plugins“ – steht dort „Secure Custom Fields“ statt „Advanced Custom Fields“, handelt es sich um den Fork. Die Felddaten sind kompatibel, aber Funktions-Updates laufen auf einem anderen Weg.

Welche Umgebungsanforderungen gelten für ACF im Jahr 2026?

Die Umgebungsanforderungen für ACF leiten sich aus den Anforderungen von WordPress ab. WordPress 6.5+ verlangt mindestens PHP 7.4, und WordPress 7.0 (geplant für Mai 2026) hebt die Empfehlung auf PHP 8.3 an. ACF verlangt in den aktuellen 6.x-Versionen WordPress 6.2+ und nennt in den Changelogs kein festes PHP-Minimum. In der Praxis halten Sie sich am besten an die Empfehlung von WordPress.

Welche PHP-Version empfiehlt sich für ACF 6.x?

Im Jahr 2026 ist PHP 8.3 der sichere Standard für eine Produktivinstallation mit ACF. PHP 7.4 reicht für den Einstieg, erhält aber seit November 2022 keine Sicherheitspatches mehr – nutzen Sie es nur, wenn Ihnen das Hosting keine Wahl lässt. PHP 8.0 und 8.1 laufen stabil. PHP 8.3 bietet die beste Performance und die längste Support-Perspektive.

Die PHP-Version prüfen Sie im Admin-Panel: „Werkzeuge > Website-Zustand > Informationen > Server > PHP-Version“. Die Änderung nehmen Sie hostingseitig vor – im cPanel, in DirectAdmin oder im Panel Ihres Hosters (Cloudways, SiteGround, Kinsta).

Was ändert das kommende WordPress 7.0 für ACF-Nutzer?

WordPress 7.0 (Mai 2026) bringt Echtzeit-Zusammenarbeit im Editor, Änderungen an den Admin-Panels und eine überarbeitete Block-API. Für ACF bedeutet das potenzielle Verschiebungen im Gutenberg-UI – der Weg zur Aktivierung des Panels „Custom Fields“ über „Preferences“ könnte sich ändern, und ACF Blocks erhalten eine bessere Integration mit der Block API v3. Die aktuellen Anleitungen (einschließlich dieses Artikels) beziehen sich auf WordPress 6.5–6.6. Prüfen Sie nach der stabilen Veröffentlichung von 7.0 die Menüpfade auf Ihrer eigenen Installation.

Wie installiert und aktiviert man ACF Schritt für Schritt?

Die Installation von ACF ist ein Standardverfahren für WordPress-Plugins – aus dem Repository für die Free-Version oder aus einer ZIP-Datei für PRO. Der gesamte Vorgang dauert 2–3 Minuten.

Wie installiert man das kostenlose ACF aus dem WordPress.org-Repository?

Gehen Sie zu „Plugins > Installieren“, geben Sie in die Suche „Advanced Custom Fields“ oder „ACF“ ein. Das erste Ergebnis ist das Plugin von WP Engine – klicken Sie auf „Installieren“, kurz danach auf „Aktivieren“. Im Seitenmenü erscheint ein neuer Punkt „ACF“ (in älteren Versionen „Custom Fields“) mit den Unterseiten „Field Groups“, „Post Types“, „Taxonomies“ und „Tools“.

Pro tip: Wenn Sie in der Suche „Advanced Custom Fields“ und „Secure Custom Fields“ nebeneinander sehen – das ist ein Überbleibsel des Konflikts von 2024. Wählen Sie „Advanced Custom Fields“ von WP Engine, es sei denn, Sie möchten bewusst den Fork.

Wie installiert man ACF PRO aus einer ZIP-Datei und gibt den Lizenzschlüssel ein?

ACF PRO kaufen Sie auf advancedcustomfields.com. Nach dem Kauf finden Sie im Kundenbereich einen Link zur ZIP-Datei und den Lizenzschlüssel. Laden Sie die ZIP-Datei herunter, gehen Sie zu „Plugins > Installieren > Plugin hochladen“, wählen Sie die Datei aus, klicken Sie auf „Jetzt installieren“, danach auf „Aktivieren“. Hatten Sie zuvor das kostenlose ACF installiert, ersetzt der Installer es durch die PRO-Version, ohne Felddaten zu verlieren.

Den Lizenzschlüssel geben Sie unter „ACF > Updates“ ein – fügen Sie den Schlüssel in das Feld „License Key“ ein und klicken Sie auf „Activate License“. Ohne Aktivierung funktioniert das Plugin, aber automatische Updates bleiben aus.

Wie definiert man den PRO-Schlüssel sicher in wp-config.php?

Den PRO-Lizenzschlüssel können Sie als Konstante in wp-config.php definieren, statt ihn im Admin-Panel einzutragen. Praktisch bei mehreren Umgebungen (Staging, Produktion) mit demselben Code – der Schlüssel bleibt in der Konfigurationsdatei, nicht in der Datenbank. Fügen Sie die folgende Zeile oberhalb des Kommentars /* That's all, stop editing! */ hinzu:

define( 'ACF_PRO_LICENSE', 'twoj-klucz-licencyjny-tutaj' );

Nachdem Sie die Datei gespeichert haben, gehen Sie zu „ACF > Updates“. Im Feld „License Key“ sehen Sie den Hinweis, dass der Schlüssel aus wp-config.php stammt und sich nicht über das Panel bearbeiten lässt. Das ist beabsichtigtes Verhalten.

Wie erstellt man die erste Feldgruppe (Field Group) in ACF?

Die Field Group ist die grundlegende Konfigurationseinheit in ACF – ein Container für Felder, der über Location-Regeln an bestimmte Bearbeitungsbildschirme angeheftet wird. Ein einzelnes Feld existiert nicht für sich allein. Es ist immer Teil einer Gruppe.

Gehen Sie zu „ACF > Field Groups > Add New”. Geben Sie der Gruppe einen Namen, der nur im Admin-Panel sichtbar ist — z. B. „Post Subtitle”. Klicken Sie auf „+ Add Field” und füllen Sie mindestens zwei Felder aus: „Field Label” (die für den Redakteur sichtbare Bezeichnung, z. B. „Untertitel”) und „Field Name” (der Programmierschlüssel, z. B. subtitle). Wählen Sie den Feldtyp — für einen Untertitel reicht „Text”.

Wie sollte man das Feld benennen, um Probleme im Frontend zu vermeiden?

Field Name ist der Schlüssel, mit dem Sie das Feld im Code identifizieren. Drei Regeln, die Ihnen Stunden des Debuggens ersparen:

• nur Kleinbuchstaben, Ziffern und Unterstriche — keine Leerzeichen, Bindestriche, polnischen Sonderzeichen,
• kurz und aussagekräftig: subtitle, hero_image, price_promo. Nicht field_1, nicht moje_pole_do_podtytulu,
• ohne ACF-Präfixe (wie acf_) — ACF hängt sein eigenes intern an, eine Verdopplung bringt die Datenbank mit dem Aufruf von get_field() durcheinander.

Achtung: Field Name ist case-sensitive und nach dem Speichern nicht mehr änderbar. Wenn Sie subtitle nach der Veröffentlichung in Subtitle ändern, bleiben alle zuvor gespeicherten Werte in der Datenbank unter dem alten Schlüssel und verschwinden aus dem Editor. Planen Sie den Namen von Anfang an.

Welche Location-Regeln ermöglichen die präzise Platzierung von Feldern im Editor?

Der Abschnitt Location im Field-Group-Editor bestimmt, auf welchen Bildschirmen das Feld erscheint. Die Standardregel lautet „Post Type is equal to Post” — das Feld erscheint bei jedem Blogbeitrag. Mit AND und OR grenzen Sie den Geltungsbereich präzise ein.

• Post Type is equal to Product — die Felder erscheinen nur bei WooCommerce-Produkten.
• Taxonomy is equal to Category — die Felder erscheinen bei der Bearbeitung von Kategorien (z. B. für das Feld „SEO-Beschreibung der Kategorie”).
• Page Template is equal to page-landing.php — die Felder erscheinen nur bei Seiten, die eine bestimmte Vorlage verwenden.
• User Role is equal to Editor — die Felder sind nur für Redakteure sichtbar, für Autoren ausgeblendet.

Welche Feldtypen sind am beliebtesten und wann verwendet man sie?

Wie zeigt man ACF-Feldwerte im WordPress-Theme an?

Die Field Group steht, die Werte im Editor sind ausgefüllt — Zeit, sie im Frontend anzuzeigen. ACF stellt dafür zwei Hauptfunktionen bereit: get_field() und the_field(). Beide rufen Sie aus dem Theme auf — am besten aus einem Child-Theme, damit ein Update des Parent-Themes Ihre Änderungen nicht überschreibt.

Worin unterscheidet sich get_field() von the_field()?

Der Unterschied ist semantischer Natur und identisch wie zwischen get_the_title() und the_title() im WordPress-Core. get_field( 'subtitle' ) gibt den Wert des Feldes zurück — Sie weisen ihn einer Variable zu, prüfen ihn mit einer Bedingung, verarbeiten ihn weiter. the_field( 'subtitle' ) gibt den Wert sofort auf dem Bildschirm aus, ohne die Möglichkeit, mit einem leeren Wert umzugehen.

The get_field() and the_field() functions are some of the most important parts of the ACF API.

WPLake — ACF get_field() and the_field() Functions: Detailed Explanation

Wie zeigt man Felder sicher mit einer Prüfung auf leere Werte an?

Der Wert eines Feldes ist manchmal leer — weil der Redakteur ihn nicht ausgefüllt hat, weil das Feld optional ist, weil der Beitrag dieses Feld gar nicht hat. Schreiben Sie Code, der das berücksichtigt. Das Muster ist einfach: Wert abrufen, Bedingung prüfen, vor der Ausgabe escapen. Fügen Sie den folgenden Snippet in die single.php des Child-Themes ein, an der Stelle, an der der Untertitel erscheinen soll (z. B. direkt unter the_title()):

<?php
// Pobierz wartość pola "subtitle" dla aktualnego wpisu.
$subtitle = get_field( 'subtitle' );

// Wypisz tylko jeśli pole zostało wypełnione.
if ( ! empty( $subtitle ) ) {
    echo '<p class="post-subtitle">' . esc_html( $subtitle ) . '</p>';
}
?>

Drei Elemente sind entscheidend: get_field() (Abruf), ! empty() (Prüfung auf leeren Wert), esc_html() (Escaping vor XSS). Lassen Sie eines davon weg, und Sie erhalten entweder einen leeren Tag <p></p> im HTML oder eine Sicherheitslücke, wenn der Wert HTML enthält.

Wie funktioniert die Beziehung von ACF zu get_post_meta() und warum ist das wichtig?

ACF erstellt keine eigene Tabelle. Alles landet in der nativen wp_postmeta. Den Wert des Feldes subtitle für einen Beitrag mit der ID 42 finden Sie in SQL unter dem Meta-Schlüssel subtitle. Das bedeutet, dass get_post_meta( 42, 'subtitle', true ) denselben Wert zurückgibt wie get_field( 'subtitle', 42 ) — mit einem kleinen Unterschied.

Der kleine Unterschied sieht so aus: get_field() verarbeitet den Wert zusätzlich entsprechend dem Feldtyp (z. B. gibt es für ein Image-Feld ein Objekt mit URL, alt, sizes zurück; für Date Picker formatiert es das Datum). get_post_meta() gibt einen rohen String zurück. Bei einfachen Feldern (Text, Textarea) ist das Ergebnis identisch. Bei komplexen Feldern verwenden Sie get_field().

Pro-Tipp: Wenn Sie ACF deaktivieren, bleiben die Daten in wp_postmeta erhalten. Sie lesen sie mit dem nativen get_post_meta() aus und schreiben das Theme ohne ACF um. Das ist die Garantie, dass Sie nicht in einen Lock-in geraten — das Plugin ist optional, nicht verpflichtend für Ihre Daten.

Wie integriert sich ACF mit WooCommerce und Custom Post Types?

WooCommerce und CPT sind die beiden häufigsten Einsatzszenarien von ACF außerhalb gewöhnlicher Beiträge. Beide basieren auf der Location-Regel „Post Type is equal to …” und funktionieren mit minimaler Konfiguration.

Wie fügt man einem WooCommerce-Produkt Schritt für Schritt ein zusätzliches Feld hinzu?

Angenommen, Sie möchten den Produkten das Feld „Brand” (Marke) hinzufügen. Vorgehensweise:

1. Gehen Sie zu „ACF > Field Groups > Add New” und geben Sie der Gruppe den Namen „Product Brand”.
2. Klicken Sie auf „+ Add Field”. Label: „Marke”. Name: brand. Typ: „Text”.
3. Stellen Sie im Abschnitt Location die Regel „Post Type is equal to Product” ein.
4. Speichern Sie die Gruppe. Gehen Sie zu „Produkte > Alle Produkte” und öffnen Sie ein beliebiges Produkt — unter der Beschreibung sehen Sie den neuen Abschnitt „Product Brand” mit dem Feld „Marke”.
5. Füllen Sie das Feld aus und speichern Sie das Produkt.

Die Anzeige des Feldes im Frontend des Produkts erfordert eine Anpassung des Templates — am besten über einen WooCommerce-Hook, damit Sie single-product.php nicht überschreiben müssen. Fügen Sie den folgenden Snippet in die functions.php des Child-Themes ein:

add_action( 'woocommerce_single_product_summary', 'akst_show_product_brand', 25 );

function akst_show_product_brand() {
    $brand = get_field( 'brand' );
    if ( ! empty( $brand ) ) {
        echo '<p class="product-brand"><strong>Marka:</strong> ' . esc_html( $brand ) . '</p>';
    }
}

Die Priorität 25 platziert das Feld zwischen dem Preis (Priorität 10) und dem Button zum Hinzufügen zum Warenkorb (Priorität 30). Aktualisieren Sie die Produktseite — die Marke erscheint an der beschriebenen Stelle.

Wie registriert man einen Custom Post Type in ACF 6.1+ ohne separates Plugin?

Bis Version 6.1 erforderte die Registrierung eines CPT Code in functions.php oder ein dediziertes Plugin, Custom Post Type UI. Seit 6.1 erledigen Sie das direkt im ACF-Panel — ohne Code und ohne zusätzliches Plugin.

Registering custom taxonomies and post types can be done in both the free and PRO versions of ACF.

WP Engine — Custom Post Types and Taxonomies in ACF 6.1

Vorgehensweise für den CPT „Project” (Portfolio):

1. „ACF > Post Types > Add New”.
2. Plural Label: „Projects”. Singular Label: „Project”. Post Type Key: project.
3. Aktivieren Sie im Reiter „Advanced Configuration” die Optionen „Hierarchical: no”, „Has Archive: yes”, „Show in REST: yes” (für Gutenberg).
4. Speichern. Im Seitenmenü erscheint der neue Eintrag „Projects”.

Wie verbindet man einen CPT mit einer eigenen Taxonomie und Feldern, die die Taxonomie beschreiben?

Ein realistisches Szenario: ein B2B-Produktkatalog mit der Taxonomie „Brand”. Jede Marke hat ein Logo, ein Gründungsjahr und einen Standort des Hauptsitzes. Vorgehensweise:

1. „ACF > Taxonomies > Add New”. Plural: „Brands”, Singular: „Brand”, Key: brand. Weisen Sie den Post Type „Product” zu.
2. „ACF > Field Groups > Add New”. Name: „Brand Meta”.
3. Fügen Sie 3 Felder hinzu: brand_logo (Typ Image), founded_year (Typ Number), headquarters (Typ Text).
4. In Location: „Taxonomy is equal to Brand”.
5. Speichern. Gehen Sie zu „Products > Brands > Add New” — im Formular zum Hinzufügen einer Marke sehen Sie die 3 neuen Felder.

Im Frontend lesen Sie die Taxonomie-Werte über get_field( 'brand_logo', 'brand_' . $term_id ) aus. Das zweite Argument ist nicht die Beitrags-ID, sondern das Präfix brand_ (Name der Taxonomie) + Term-ID. Das ist der Unterschied zu Feldern an einem Beitrag.

Welche erweiterten Funktionen bietet ACF PRO?

ACF PRO fügt Funktionen hinzu, die sich in der Free-Version nicht sinnvoll ersetzen lassen. Die drei wichtigsten sind Repeater, Flexible Content und ACF Blocks — jede löst eine andere Klasse von Problemen.

Wofür dient das Feld Repeater und wann ist es sinnvoll?

Repeater sind wiederholbare Feldzeilen. Sie definieren die Struktur einmal (z. B. „Frage + Antwort” für eine FAQ-Sektion), und der Redakteur fügt so viele Zeilen hinzu, wie er möchte. Ohne Repeater müssten Sie 10 einzelne Felder faq_1_question, faq_1_answer, faq_2_question … von Hand anlegen und sich mit einem starren Limit von vornherein abfinden.

Snippet zur Anzeige des Repeaters „faq” im Template:

<?php if ( have_rows( 'faq' ) ) : ?>
    <dl class="faq-list">
    <?php while ( have_rows( 'faq' ) ) : the_row(); ?>
        <dt><?php echo esc_html( get_sub_field( 'question' ) ); ?></dt>
        <dd><?php echo esc_html( get_sub_field( 'answer' ) ); ?></dd>
    <?php endwhile; ?>
    </dl>
<?php endif; ?>

Die Schleife have_rows() + the_row() + get_sub_field() ist das Muster, das Sie bei jedem Repeater und Flexible Content sehen werden. Einmal merken, überall verwenden.

Wie ersetzt Flexible Content Page-Builder in einfachen Projekten?

Flexible Content ist ein Repeater auf Steroiden. Statt einer einzigen sich wiederholenden Struktur definieren Sie mehrere „Layouts” zur Auswahl. Der Redakteur setzt die Seite aus Blöcken zusammen: „Hero Section”, „Text + Image”, „Testimonials”, „CTA Banner”. Jedes Layout hat eigene Unterfelder.

In einfacheren Projekten ist das eine vollwertige Alternative zu Page-Buildern wie Elementor oder Divi. Vorteile: volle Kontrolle über den HTML-Code (Sie schreiben selbst ein Template-Part für jedes Layout), keine Abhängigkeit von schweren Frontend-Frameworks, Daten im nativen wp_postmeta. Nachteile: Der Redakteur sieht keine „Live-Vorschau” — speichern und im Frontend prüfen.

Die Schleife im Template sieht so aus:

<?php if ( have_rows( 'page_builder' ) ) : ?>
    <?php while ( have_rows( 'page_builder' ) ) : the_row();
        $layout = get_row_layout();
        get_template_part( 'template-parts/blocks/' . $layout );
    endwhile; ?>
<?php endif; ?>

Jedes Layout ist eine eigene Datei in template-parts/blocks/ — z. B. hero-section.php, text-image.php. Ein neues Layout fügen Sie in zwei Schritten hinzu: Datei erstellen + Layout im Flexible-Content-Feld im ACF-Panel registrieren.

Was sind ACF Blocks und wie bauen sie eigene Gutenberg-Blöcke?

ACF Blocks ist ein Mechanismus zur Registrierung von Gutenberg-Blöcken, die auf ACF-Feldern basieren und nicht auf React und der Block API. Der Redakteur fügt den Block im Editor ein, füllt die Felder rechts aus und sieht eine Live-Vorschau — alles ohne JavaScript-Kenntnisse.

Der Workflow sieht so aus: Erstellen Sie eine Field Group mit der Location-Regel „Block is equal to [nazwa bloku]”, registrieren Sie den Block über acf_register_block_type() in functions.php und schreiben Sie ein Template (PHP), das die Feldwerte rendert. Ab ACF 6.x ist der Mechanismus mit der Block API v3 des WordPress-Cores kompatibel.

Registrierung eines einfachen „testimonial”-Blocks:

add_action( 'acf/init', 'akst_register_blocks' );

function akst_register_blocks() {
    if ( ! function_exists( 'acf_register_block_type' ) ) {
        return;
    }

    acf_register_block_type( array(
        'name'            => 'testimonial',
        'title'           => 'Testimonial',
        'description'     => 'Pojedynczy testimonial klienta.',
        'render_template' => 'template-parts/blocks/testimonial.php',
        'category'        => 'formatting',
        'icon'            => 'format-quote',
        'keywords'        => array( 'testimonial', 'opinia', 'cytat' ),
        'mode'            => 'preview',
    ) );
}

Fügen Sie den Code hinzu, erstellen Sie die Datei template-parts/blocks/testimonial.php — der Block erscheint in der Gutenberg-Blocksuche in der Kategorie „Formatting”.

Was sind die häufigsten Anfängerfehler und wie behebt man sie?

Die meisten Probleme mit ACF lassen sich auf drei Kategorien zurückführen: Konfiguration (Location, Feldname), Kontext (falsche $post_id) und Umgebung (Cache, Plugin-Konflikt). Die folgende Diagnosetabelle hilft Ihnen, die Ursache schnell zu lokalisieren.

Warum ist mein Feld in the_field() leer, obwohl ich einen Wert eingegeben habe?

Die drei häufigsten Ursachen:

• Tippfehler im Field Name. Sie haben im Code the_field( 'subTitle' ) eingetragen, im Panel lautet der Name jedoch subtitle. Der Field Name unterscheidet zwischen Groß- und Kleinschreibung. Kopieren Sie den genauen Namen aus dem Panel.
• Sie bearbeiten einen anderen Beitrag als gedacht. Rufen Sie the_field() in einer Archiv-Schleife statt in single.php auf? ACF liest dann die Daten der Hauptabfrage und nicht der aktuellen Iteration. Übergeben Sie explizit get_the_ID() als zweites Argument.
• Theme- oder Seiten-Cache. Cache-Plugins wie WP Rocket und LiteSpeed Cache können eine leere Version der Seite cachen. Leeren Sie den Cache, nachdem Sie den Feldwert eingegeben haben.

Warum erscheinen Felder nicht im Beitrags- oder Produkteditor?

Meistens ist die Location-Regel schuld. Prüfen Sie unter „ACF > Field Groups > [nazwa grupy] > Location” — wenn die Regel „Post Type is equal to Post” lautet, Sie aber ein WooCommerce-Produkt bearbeiten, erscheint das Feld nicht. Ändern Sie sie auf „Post Type is equal to Product” oder fügen Sie eine zweite Regel mit OR hinzu.

Die zweite Möglichkeit: Die Field Group hat den Status „Inactive” — in der Liste der Field Groups befindet sich rechts ein Schalter. Aktivieren Sie die Gruppe und aktualisieren Sie den Editor.

Wie löst man Konflikte zwischen ACF und Page-Buildern oder Cache?

Page-Builder (Elementor, Divi, Bricks) haben eigene Mechanismen zum dynamischen Abrufen von ACF-Feldern. Ein Konflikt entsteht, wenn der Builder den Feldwert cacht und ihn nach der Bearbeitung nicht aktualisiert. Lösung: Aktivieren Sie in den Builder-Einstellungen „CSS nach dem Speichern neu generieren” und leeren Sie den Builder-Cache nach der Änderung des Feldwerts.

Einen Cache-Konflikt lösen Sie der Reihe nach:

1) Cache des Cache-Plugins leeren,

2) Hosting-Cache leeren (Cloudways und Kinsta haben einen eigenen),

3) CDN-Cache leeren (Cloudflare),

4) Hard-Refresh des Browsers (Strg+Umschalt+R).

Das Feld ist immer noch leer? Das Problem liegt nicht am Cache.

Was ist die Zusammenfassung der wichtigsten Informationen?

Die wichtigsten Punkte aus dem gesamten Artikel — kurz und knapp:

• ACF ersetzt rohe Custom Fields durch eine grafische Oberfläche — ohne eigenes Plugin zu programmieren.
• Die Daten landen in wp_postmeta und bleiben auch nach der Deaktivierung des Plugins erhalten — kein Vendor-Lock-in.
• Installation: „Plugins > Installieren > Advanced Custom Fields” (Free) oder ZIP-Upload (PRO).
• Field Group + Field Name + Location sind die drei Säulen jeder ACF-Konfiguration.
• Im Theme: get_field() (für Logik) oder the_field() (für einfache Ausgabe), immer mit esc_html().
• PRO bietet Repeater, Flexible Content, Gallery, Options Pages und ACF Blocks — kaufen Sie es, wenn Sie modulare Layouts benötigen.
• Die häufigsten Fehler: Tippfehler im Field Name, falsche Location-Regel, Cache. Diagnose in dieser Reihenfolge: Name → Location → Cache.

Die vollständige ACF-Dokumentation finden Sie unter advancedcustomfields.com/resources. Für den Fork Secure Custom Fields gibt es einen eigenen Pfad: developer.wordpress.org/secure-custom-fields.

Was sind die häufig gestellten Fragen (FAQ)?