ACF: So erstellst du eigene Custom Field Typen

Knowledge-Base • Development • ACF: So erstellst du eigene Custom Field Typen
Lesezeit ca: 14 min

Advanced Custom Fields (ACF) ist zweifellos eines der mächtigsten und beliebtesten Plugins im WordPress-Ökosystem. Es ermöglicht Entwicklern und Seitenbetreibern, WordPress-Seiten und -Beiträge mit maßgeschneiderten Datenfeldern anzureichern. Von einfachen Textfeldern bis hin zu komplexen Repeatern und Relationship-Feldern – ACF bietet eine riesige Auswahl.

Aber was passiert, wenn die eingebauten Feldtypen nicht ausreichen? Vielleicht benötigst du eine ganz spezielle Benutzeroberfläche für die Dateneingabe, musst eine externe API integrieren oder einfach nur eine einzigartige Datenstruktur abbilden. Genau hier kommt die wahre Stärke von ACF zum Vorschein: seine Erweiterbarkeit.

In diesem Artikel zeige ich dir Schritt für Schritt, wie du ACF erweitern kannst, indem du eigenen, benutzerdefinierten Feldtypen erstellst.

Warum einen eigenen ACF Feldtypen erstellen?

Bevor wir eintauchen, lass uns kurz überlegen, warum du das überhaupt tun solltest:

  1. Einzigartige Benutzeroberfläche (UI):
    Du möchtest Felder, die anders aussehen oder sich anders verhalten als die Standardfelder (z.B. ein spezieller Farbwähler, ein Schieberegler mit zwei Griffen, eine interaktive Karte).
  2. Datenvalidierung & -verarbeitung:
    Du benötigst eine sehr spezifische Logik zur Validierung oder Speicherung von Daten, die über die Standardoptionen hinausgeht.
  3. Integration von Drittanbieter-Diensten:
    Du möchtest Daten direkt aus einer externen API abrufen oder dorthin senden (z.B. ein Feld zur Auswahl eines YouTube-Videos mit Vorschau).
  4. Komplexe Datenstrukturen:
    Du musst Daten speichern, die nicht einfach in die vorhandenen Feldtypen passen.

Voraussetzungen

  • Grundlegende PHP-Kenntnisse.
  • Eine funktionierende WordPress-Installation (lokal oder auf einem Staging-Server).
  • Das ACF-Plugin (die kostenlose Version reicht für den Anfang) installiert und aktiviert.
  • Ein Code-Editor Deiner Wahl.

Für dieses Tutorial erstellen wir ein eigenes kleines WordPress-Plugin. Die Verwendung eines Plugin ist sauber, wiederverwendbar, Theme-unabhängig und beliebig erweiterbar.

Schritt-für-Schritt: Erstellung eines einfachen
Präfix-Text-Feldes

Als Beispiel erstellen wir ein einfaches Feld: ein Textfeld, bei dem wir in den Feldeinstellungen ein Präfix definieren können, das dem gespeicherten Wert automatisch vorangestellt wird (z.B. für eine Bestellnummer oder einen speziellen Code).

Schritt 1: Plugin-Grundgerüst erstellen

  1. Erstelle einen neuen Ordner in Deinem wp-content/plugins/acf-extend-my-custom-fields
  2. Erstelle in diesem Ordner eine Haupt-PHP-Datei, z.B. my-acf-feld.php.
  3. Füge den grundlegenden Plugin-Header hinzu
  4. Aktiviere das Plugin im WordPress-Adminbereich.
<?php
/**
 * Plugin Name: ACF - Extend my Custom Fields
 * Description: Fügt einen benutzerdefinierten 'Präfix-Text'-Feldtyp zu ACF hinzu.
 * Version: 1.0
 * Author: Dein Name
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
    exit;  
}

// Hier kommt unser Code hin...

Schritt 2: Die Feld-Klasse erstellen

Jeder ACF-Feldtyp wird durch eine PHP-Klasse definiert, die von der Basisklasse acf_field erbt.

  1. Erstelle einen Unterordner in Deinem Plugin-Ordner, z.B. fields.
  2. Erstelle darin eine neue PHP-Datei, z.B. class-acf-field-praefix-text.php.
  3. Definiere die Klasse:
<?php

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
    exit;
}

class ACF_Field_Praefix_Text extends acf_field {

    /**
     * Constructor.
     */
    public function __construct() {
        /**
         * Field type identifier.
         * Muss eindeutig sein und darf nur Kleinbuchstaben, Zahlen und Unterstriche enthalten.
         */
        $this->name = 'praefix_text';

        /**
         * Field type label.
         * Angezeigt im Dropdown zur Feldauswahl.
         */
        $this->label = __( 'Präfix Text', 'mein-acf-feld' );

        /**
         * Field category.
         * Gruppiert Felder im Dropdown (z.B. 'basic', 'content', 'choice', 'jquery', 'layout').
         */
        $this->category = 'basic'; // Oder 'custom', 'content', etc.

        /**
         * Default field settings.
         * Wird verwendet, wenn keine spezifischen Einstellungen für ein Feld vorhanden sind.
         */
        $this->defaults = array(
            'praefix' => '', // Unser benutzerdefiniertes Setting
        );

        // Actions & filters hier hinzufügen, falls nötig

        // Do not delete!
        parent::__construct();
    }

    /**
     * Hier definieren wir die Einstellungen für unser Feld.
     * Diese werden im Field Group Editor angezeigt.
     *
     * @param array $field Das Feld-Array.
     */
    public function render_field_settings( $field ) {

        // Einstellung für das Präfix
        acf_render_field_setting( $field, array(
            'label'        => __( 'Präfix', 'mein-acf-feld' ),
            'instructions' => __( 'Text, der dem Wert vorangestellt wird.', 'mein-acf-feld' ),
            'type'         => 'text',
            'name'         => 'praefix', // Name muss mit dem Key in $this->defaults übereinstimmen
            'placeholder'  => 'z.B. BEST-',
        ));
    }

    /**
     * Hier definieren wir, wie das Feld im Admin-Bereich (beim Bearbeiten eines Posts) aussieht.
     *
     * @param array $field Das Feld-Array mit allen Einstellungen und dem aktuellen Wert.
     */
    public function render_field( $field ) {
        // Hole das gespeicherte Präfix aus den Feldeinstellungen
        $praefix = isset( $field['praefix'] ) ? esc_attr( $field['praefix'] ) : '';
        ?>
        <div class="acf-input-wrap">
            <?php if ( $praefix ) : ?>
                <span class="acf-praefix-text-prefix" style="margin-right: 5px; color: #777;"><?php echo $praefix; ?></span>
            <?php endif; ?>
            <input
                type="text"
                name="<?php echo esc_attr( $field['name'] ); ?>"
                value="<?php echo esc_attr( $field['value'] ); ?>"
            />
        </div>
        <?php
    }


    /**
     * (Optional) Hier formatieren wir den Wert, bevor er über get_field() / the_field() ausgegeben wird.
     *
     * @param mixed $value   Der im Post Meta gespeicherte Wert.
     * @param int   $post_id Die Post-ID.
     * @param array $field   Das Feld-Array.
     * @return mixed Der formatierte Wert.
     */
    public function format_value( $value, $post_id, $field ) {
        // Wenn der Wert leer ist, nichts tun
        if ( empty( $value ) ) {
            return $value;
        }

        // Hole das Präfix aus den Feldeinstellungen
        $praefix = isset( $field['praefix'] ) ? $field['praefix'] : '';

        // Stelle das Präfix dem Wert voran
        $formatted_value = $praefix . $value;

        return $formatted_value;
    }

    /**
     * (Optional Validierungsregeln hinzufügen.
     *
     * @param bool  $valid Ob das Feld bisher gültig ist.
     * @param mixed $value Der Wert des Feldes.
     * @param array $field Das Feld-Array.
     * @param array $input Das $_POST-Array für dieses Feld.
     * @return bool|string True wenn gültig, Fehlermeldung (String) wenn ungültig.
     */
     /*
    public function validate_value( $valid, $value, $field, $input ){
        // Beispiel: Wert darf nicht 'ungueltig' sein
        if( $value === 'ungueltig' ) {
            $valid = __('Dieser Wert ist nicht erlaubt.', 'mein-acf-feld');
        }
        return $valid;
    }
    */

    /**
     * (Optional) Hier können Admin-spezifische Skripte oder Stile enqueued werden.
     */
     /*
    public function input_admin_enqueue_scripts() {
        // Beispiel:
        // wp_register_script( 'mein-acf-field-script', plugin_dir_url( __FILE__ ) . '../js/mein-script.js', array('acf-input'), '1.0' );
        // wp_enqueue_script( 'mein-acf-field-script' );

        // wp_register_style( 'mein-acf-field-style', plugin_dir_url( __FILE__ ) . '../css/mein-style.css', array('acf-input'), '1.0' );
        // wp_enqueue_style( 'mein-acf-field-style' );
    }
    */

}

// WICHTIG: Die Klasse direkt hier instanziieren, um sie ACF bekannt zu machen.
// Dies geschieht über den Hook in Schritt 3, aber das ist eine gängige Praxis in der Klassendatei selbst.
// new ACF_Field_Praefix_Text(); // Siehe Schritt 3 - besser dort registrieren!

?>

Erklärung der wichtigsten Methoden in der Klasse:

  • __construct(): Initialisiert das Feld, setzt Name, Label und Kategorie.
  • render_field_settings($field): Definiert die Einstellungen, die im Feldgruppen-Editor für dieses spezifische Feld verfügbar sind (hier: das Präfix-Textfeld). Wir verwenden acf_render_field_setting, eine Hilfsfunktion von ACF.
  • render_field($field): Erzeugt das HTML für das Feld, wie es beim Bearbeiten eines Beitrags oder einer Seite im WordPress-Admin angezeigt wird. Hier greifen wir auf $field['value'] (den aktuellen Wert) und $field['name'] (wichtig für das Speichern) sowie auf unsere benutzerdefinierte Einstellung $field['praefix'] zu.
  • format_value($value, $post_id, $field): Modifiziert den Wert, nachdem er aus der Datenbank geholt wurde, aber bevor er von get_field() oder the_field() zurückgegeben wird. Hier fügen wir das Präfix hinzu.
  • validate_value(...) (auskommentiert): Logik hinzufügen, um den eingegebenen Wert zu prüfen, bevor er gespeichert wird.
  • input_admin_enqueue_scripts() (auskommentiert): JavaScript oder CSS laden, das nur für Dein Feld im Admin-Bereich benötigt wird (z.B. für einen komplexen UI-Picker).

Schritt 3: Den neuen Feldtypen bei ACF registrieren

Damit ACF Deinen neuen Feldtypen kennt, musst du ihn über einen Hook registrieren. Füge diesen Code in Deine Haupt-Plugin-Datei (my-acf-feld.php) ein:

<?php
/**
 * Plugin Name: ACF - Extend my Custom Fields
 * Description: Fügt einen benutzerdefinierten 'Präfix-Text'-Feldtyp zu ACF hinzu.
 * Version: 1.0
 * Author: Dein Name
 */

// Exit if accessed directly.
if ( ! defined( 'ABSPATH' ) ) {
    exit;  
}

/**
 * ACF Hook zum Registrieren von Feldtypen.
 * Version 5+ verwendet acf/include_field_types
 * Version 4 verwendet acf/register_fields
 */
add_action('acf/include_field_types', 'mein_acf_register_praefix_text_field');
// add_action('acf/register_fields', 'mein_acf_register_praefix_text_field'); // Für ACF v4

function mein_acf_register_praefix_text_field( $version = false ) {
    // Überprüfen, ob die Klasse existiert, bevor wir sie einbinden
    if ( ! class_exists('ACF_Field_Praefix_Text') ) {
        require_once plugin_dir_path( __FILE__ ) . 'fields/class-acf-field-praefix-text.php';
    }

    // Instanziiere die Feld-Klasse, um sie zu registrieren
    // Der Konstruktor der Klasse kümmert sich um den Rest.
    new ACF_Field_Praefix_Text();
}

?> // Wenn dies das Ende der Datei ist, ist das schließende ?> optional und oft besser wegzulassen.

Schritt 4: Den neuen Feldtypen verwenden

  1. Gehe im WordPress-Admin zu «Custom Fields» -> «Feldgruppen».
  2. Erstelle eine neue Feldgruppe oder bearbeite eine bestehende.
  3. Klicke auf «Feld hinzufügen».
  4. Im Dropdown «Feldtyp» solltest du nun unter der Kategorie «Basic» den neuen Feldtypen «Präfix Text» finden. Wähle ihn aus.
  5. Gib dem Feld ein Label (z.B. «Bestellnummer») und einen Namen (z.B. bestellnummer).
  6. Du siehst nun Deine benutzerdefinierte Einstellung «Präfix». Gib dort etwas ein, z.B. ORD-.
  7. Speichere die Feldgruppe und weise sie einem Beitragstyp zu (z.B. «Beiträge»).
  8. Erstelle oder bearbeite nun einen Beitrag dieses Typs. Du solltest Dein neues Feld sehen, inklusive des (nur visuell im Admin) dargestellten Präfixes. Gib einen Wert ein (z.B. 12345) und speichere den Beitrag.

Schritt 5: Den Wert im Frontend ausgeben

Verwende die Standard-ACF-Funktionen, um den Wert im Template Deines Themes auszugeben:

<?php
// Hole den Wert (formatiert durch unsere format_value Methode)
$bestellnummer = get_field('bestellnummer'); // Feldname verwenden

if ( $bestellnummer ) {
    echo '<p>Bestellnummer: ' . esc_html( $bestellnummer ) . '</p>';
    // Erwartete Ausgabe: <p>Bestellnummer: ORD-12345</p>
}

// Oder direkt ausgeben:
// the_field('bestellnummer');
?>

Dank unserer format_value-Methode wird das Präfix automatisch vor den gespeicherten Wert gesetzt, wenn get_field() oder the_field() verwendet wird.

Fazit

Das Erstellen eigener ACF-Feldtypen eröffnet eine Welt voller Möglichkeiten zur Anpassung Deiner WordPress-Websites. Auch wenn dieses Beispiel einfach war, zeigt es die grundlegende Struktur und die wichtigsten Methoden, die du benötigst.

Von hier aus kannst du nun komplexere Felder bauen:

  • Felder mit JavaScript-Interaktionen (Slider, Karten, spezielle Picker).
  • Felder, die Daten aus externen Quellen laden.
  • Felder mit aufwändiger Validierung oder Datenverarbeitung beim Speichern.

Die offizielle ACF-Dokumentation zum Erstellen von Feldtypen (https://www.advancedcustomfields.com/resources/creating-a-new-field-type/) ist eine hervorragende Ressource für tiefere Einblicke und fortgeschrittenere Techniken.

Experimentiere, baue auf diesem Beispiel auf und mach ACF noch mächtiger für Deine Projekte! Viel Erfolg!

Expand Your Knowledge