Vollständige Referenz zum Hinzufügen erweiterter benutzerdefinierter Feldgruppen und Felder nach Code

Das Plugin Advanced Custom Fields (ACF) unterstützt die vollständige Einrichtung von Feldern und Gruppen per PHP-Code in Ihrem Design oder Plugin. Der Vorteil dabei ist, dass alle Ihre Felder verfügbar sind, unabhängig davon, an welcher WordPress-Instanz Sie arbeiten (z. B. wenn Sie zwischen lokal, Testserver und Live-Server wechseln müssen). Sie können alle Felder im Adminbereich von ACF einrichten und das Exporttool verwenden, um sie nach PHP zu exportieren.

Wenn Sie dies jedoch häufig tun, werden Sie möglicherweise feststellen, dass der PHP-Export von ACF eine Menge Code enthält, wodurch Ihre PHP-Dateien unnötig lang werden. In einigen Fällen ist es besser, den Code selbst zu schreiben, mit dem Nötigsten, um einen saubereren Code in Ihrem Design oder Plugin zu erhalten. Dieses Handbuch soll Ihnen eine vollständige Referenz zum manuellen Hinzufügen von ACF-Feldern und -Gruppen in PHP bieten. Bitte beachten Sie, dass nicht detailliert auf jeden Feldtyp eingegangen wird, da davon ausgegangen wird, dass Sie bereits mit den verschiedenen Feldern vertraut sind, die in ACF möglich sind.

Aber zuerst; einige Vorsichtsmaßnahmen

Um gute Code-Standards aufrechtzuerhalten und sicherzustellen, dass Ihre WordPress-Site nicht abstürzt, sollten Sie immer überprüfen, ob die Funktionen oder Klassen, die Ihr Code verwendet, tatsächlich existieren. Gerade bei Plugins, die einfach deaktiviert oder gar nicht erst auf einer Seite installiert werden können, sollten Sie Ihren Plugin-spezifischen Code immer in einen If-Test packen, der prüft, ob die von Ihnen genutzten Funktionen existieren, bevor Sie diese nutzen.

Wie bei ACF können Sie dies tun, indem Sie überprüfen, ob die Klasse 'acf'vorhanden ist oder ob die Funktion zum Hinzufügen von Feldern und Gruppen, 'acf_add_local_field_group', vorhanden ist. Wickeln Sie eines davon um den folgenden Code.

if (function_exists('acf_add_local_field_group')) {
    // Your ACF specific code here
}
// OR:
if (class_exists('acf')) {
    // Your ACF specific code here
}

Skeleton-Code

Zum Hinzufügen von Metaboxen (Gruppen) und Feldern verwenden wir den Hook namens acf/init. Innerhalb der Funktion rufen wir die Funktion acf_add_local_field_group()mit einem Array als Parameter auf. Innerhalb dieses Arrays befindet sich das vollständige Setup für die Gruppe und alle ihre Felder. Die wichtigsten sind die Array-Schlüssel 'fields'und 'location'. Für den Array-Schlüssel 'fields'geben Sie das Array für alle Felder an, und für den Schlüssel 'location'geben Sie die Einstellungen an, wo die Metabox erscheinen soll. In diesem Beitrag wird detailliert beschrieben, welche möglichen Optionen Sie für jede der folgenden Optionen haben.

Dies ist das absolute Minimum, um eine Gruppe hinzuzufügen, abgesehen von den Feldern und dem Standort:

Jede Gruppe benötigt einen eindeutigen Schlüssel, aber der eigentliche Name selbst spielt (für uns) keine große Rolle. Wenn Sie weitere Gruppen hinzufügen, vergessen Sie nicht, das 'key'Feld zu ändern. Der Titel der Metabox kann im Schlüsselelement des Arrays festgelegt werden, Sie haben es erraten, 'title'. Wenn Sie mehrere Metaboxen an derselben Stelle hinzufügen (z. B. in der Nachbearbeitung), können Sie steuern, welche zuerst kommt, indem Sie verschiedene Zahlen in eingeben 'menu_order'.

Sie können das Metabox-Design steuern, indem Sie entweder defaulteller seamlessin angeben 'style'. Beim neuen Gutenberg-Editor hat dies jedoch eine viel geringere Bedeutung. Das Gleiche gilt für den Schlüssel 'position', bei dem Sie früher die Metabox unter dem Beitragsinhalt ('normal'), an der Seite ('side') oder direkt nach dem Beitragstitel ('acf_after_title') platzieren konnten.

In Ordnung! Lassen Sie uns in die beiden interessanteren Elemente des Arrays eintauchen; beginnend mit dem Ort – der definiert, wo die Metabox erscheint.

Ort

Hier dreht sich alles um das, was Sie in den Schlüssel eingeben 'location'. Aber bevor wir uns mit den möglichen Optionen befassen, müssen wir die Array-Struktur verstehen.

'location'akzeptiert ein Array mit einem Array von Elementen in einem Array! Halten. Ja, weil es möglich ist, UND- und ODER-Logik vor Ort bereitzustellen und zu kombinieren (z. B. „in Post-Bearbeitung anzeigen, aber nicht, wenn der Post-Typ „Buch” ist”, oder „in Benutzerbearbeitungsbildschirm anzeigen und auch neuen Benutzerbildschirm erstellen, aber für beide Fälle not if current role is author"). Die Art und Weise, wie Sie angeben, ob es sich um ein AND oder ein OR handelt, besteht darin, die Arrays zu strukturieren. Es ist viel einfacher zu zeigen als mit Worten zu erklären:

So kombinieren Sie zwei Ortselemente mit UND-Logik (beide müssen wahr sein):

Und dies dient zum Kombinieren von Standorten mit ODER-Logik (nur einer muss wahr sein):

Sieh den Unterschied?

Okay, machen wir weiter. Jede Standortoption besteht aus einem Array von drei Elementen; 'param'Hier fügen wir all die verschiedenen Orte hinzu, 'operator', und 'value'. Der Operator gibt an, wie der Wert verglichen wird, und er kann '=='gleich oder '!='ungleich sein.

Gehen wir die möglichen Optionen nacheinander durch.

Standort nach Beitragstyp

Stellen Sie Ihren gewünschten Beitragstyp ein 'value'. Denken Sie daran, dass Sie kein Array mit mehreren Post-Typen bereitstellen können, Sie müssen mehrere dieser Arrays in einer UND-Konfiguration kombinieren.

Standort nach Poststatus

Setzen Sie Ihren gewünschten Beitragsstatus auf 'value'. Denken Sie auch hier daran, dass Sie kein Array mit mehreren Post-Status angeben können. Sie müssen jeden gewünschten Wert in einer AND- oder OR-Konfiguration angeben.

Standort nach Seitenvorlage

Dies wird nur angezeigt, wenn die ausgewählte Seite (oder der benutzerdefinierte Beitragstyp mit Seitenvorlagenunterstützung) den angegebenen Seitenvorlagennamen ausgewählt hat.

Ort nach zugewiesenem Taxonomiebegriff

Dieser Ort ist dafür vorgesehen, wenn einem Beitrag ein bestimmter Begriff zugeordnet ist. Sie müssen den Taxonomienamen, einen Doppelpunkt und den Slug des Begriffs als Wert angeben.

Standort nach Seitentyp

ACF gruppiert spezielle Eigenschaften für Seiten als „Seitentyp”. Es betrifft hauptsächlich, ob die aktuelle Seite eine übergeordnete oder untergeordnete Seite ist oder nicht, aber auch für das Targeting von Seiten, die als WordPress-Startseite oder Blog-Seite festgelegt sind.

Standort: Taxonomie

Ein Ort für das Bearbeiten oder Hinzufügen eines Begriffs in einer Taxonomie.

Geben Sie den Taxonomienamen als 'value'. Denken Sie daran, dass Sie kein Array mit mehreren Taxonomien bereitstellen können, aber Sie können 'all'alle Taxonomien als Ziel angeben.

Ort: Benutzer

Dieser Ort dient zum Hinzufügen oder Bearbeiten eines Benutzerprofils.

Geben Sie 'edit‘ an, um nur auf den Bildschirm zum Bearbeiten vorhandener Benutzer abzuzielen, 'register'um nur auf das Formular abzuzielen, wenn Sie einen neuen Benutzer registrieren, oder ‘ all'für beides.

Ort: Menüpunkt

Seit ACF 5.6 können Sie auch Feldgruppen zu Menüpunkten hinzufügen.

Sie können festlegen value, alldass die Gruppe auf alle Menüpunkte angewendet wird, oder Sie können Menüs entweder nach Ort (registrierte Orte in Ihrem Thema) oder nach Menü-ID angeben. Für Standortverwendung 'location/<name>'– also können Sie für einen Standort mit dem Namen „ primary” den Wert auf setzen 'location/primary', um Ihre Gruppe nur auf ein Menü anzuwenden, das diesem Standort zugewiesen ist. Wenn Sie auf eine bestimmte Menü-ID abzielen möchten, legen Sie den Wert auf eine Zeichenfolge dieser ID fest.

Ort: Widget

ACF bietet Ihnen sogar einen Ort innerhalb der Widget-Einstellungen, ohne den Kern-Widget-Code zu ändern.

Sie können alle Widgets mit 'all'as 'value'ansprechen oder auf ein bestimmtes Widget abzielen. Sie müssen die „interne ID” des Widgets kennen, bei dem sie registriert sind.

Speicherort: ACF-Optionsseite (nur Pro)

Mit ACF Pro können Sie ACF verwenden, um benutzerdefinierte Admin-Seiten einzurichten.

Geben Sie den Namen ein, den Sie in acf_add_options_page‘s menu_slugas festgelegt haben 'value'.

Ort: Block (nur Pro 5.8+)

ACF Pro (5.8+) verfügt über eine Funktion zum Hinzufügen von Gutenberg-Blöcken mit Feldern aus ACF und zum Steuern der Ausgabe mit PHP. Ziemlich raffiniert für diejenigen, die noch nicht in das Hinzufügen von benutzerdefinierten Gutenberg-Blöcken und dem erforderlichen Javascript eingetaucht sind.

Felder

Jetzt kommen wir zum interessanteren Teil; die Felder selbst. ACF bietet eine (wirklich) große Auswahl an Feldtypen, und ich wiederhole es; Diese Anleitung zeigt Ihnen nicht, was die einzelnen Felder sind und wie sie funktionieren oder aussehen.

In dem Kernarray, das Sie bereitstellen, stellen Sie ein Array bereit, 'fields'in acf_add_local_field_group()dem jedes Feld ein eigenes Array ist.

Das absolute Minimum, das für jedes Feld erforderlich ist, ist wie folgt: ein Unikat 'key', das alles sein kann, was Sie wollen, und Sie werden wahrscheinlich nie darauf verweisen müssen. Sie benötigen auch 'name'den Metaschlüssel (post, user, term), in dem der Wert des Felds gespeichert ist – und auf diesen beziehen Sie sich, wenn Sie den Wert der Felder abrufen. Sie sollten ein 'label'und schließlich das Entscheidende angeben 'type', das definiert, um welchen Feldtyp es sich handelt. Der Rest der Felder hängt davon ab, 'type'wie wir sehen werden, wenn wir die einzelnen Feldtypen unten durchgehen.

Dies ist der Skelettcode zum Hinzufügen eines Felds.

Denken Sie daran, dass Sie das obige für jedes Feld benötigen, aber um denselben Code nicht zu wiederholen, enthält jeder Feldtyp unten nur 'type'und alle anderen Elemente, die für diesen Feldtyp benötigt werden.

Feld: Texteingabe

Das einfachste Feld von allen. Alles, was wir wirklich brauchen, ist:

Aber um Ihre Texteingabe weiter anzupassen, können Sie auch Folgendes bereitstellen:

Feld: Zahleneingabe

Feld: Textbereich

Feld: Bereichsschieberegler

Feld: Passwort

Dasselbe wie bei der Texteingabe, außer dass alles, was Sie eingeben, mit * überdeckt wird, wie Sie es in einem Passwortfeld erwarten würden.

Feld: Bild

Einzelbild auswählen.

Feld: Datei

Ähnlich wie im obigen Bild, außer dass die Datei nicht in der Vorschau angezeigt wird.

Sie können es auch angeben 'mime_types' => '',und einstellen, um zB 'pdf,docx'nur PDF- und DOCX-Dateien zuzulassen.

Feld: WYSIWYG-Editor

WYSIWYG ist ein „What You See Is What You Get”-Editor – der, mit dem wir vertraut waren, bevor Gutenberg kam (TinyMCE).

Der Parameter 'media_upload'und 'delay'kann 1 (wahr) oder 0 (falsch) sein.

Feld: Auswählen

Feld: Kontrollkästchen

Beachten Sie, dass 'default_value'es sich um ein Array mit mehreren Auswahlmöglichkeiten handeln kann.

Feld: Optionsfeld

Die Einstellung 'other_choice'auf true fügt ein zusätzliches Optionsfeld mit der Bezeichnung „Other” mit einer Texteingabe hinzu, in die der Benutzer etwas eingeben kann.

Feld: Wahr/Falsch (umschalten)

Das 'ui_on_text'und 'ui_off_text'ist nur gültig, wenn 'ui'es 1 ist, da es definiert, was auf dem speziellen UI-Umschalter erscheinen soll.

Feld: Verknüpfung

Gibt Ihnen eine Schaltfläche zum Eingeben eines Links, entweder durch Eingabe oder Auswahl aus Inhalten auf Ihrer WordPress-Site (sollte vom Hinzufügen eines Links im normalen WordPress-Editor bekannt sein).

Feld: Post-Objekt

Bietet ein Auswahlfeld, in dem Sie aus WordPress-Inhalten auswählen können. Die Auswahl ermöglicht Ihnen die Suche durch Eingabe und der gesamte Inhalt ist nach Beitragstyp unterteilt. Sie können zulassen, dass mehrere Beiträge ausgewählt werden oder nur einer.

Feld: Beziehung

Feld: Wählen Sie Begriffe in einer Taxonomie aus

Die Taxonomie-Begriffsauswahl hat vier verschiedene „Modi” oder Typen, von denen zwei eine Mehrfachauswahl ermöglichen.

Feld: Benutzer auswählen

Feld: Google Maps

Denken Sie daran, dass Sie ACF einen gültigen GoogleMaps-API-Schlüssel zur Verfügung stellen müssen, damit dieses Feld wie folgt funktioniert:

add_filter('acf/fields/google_map/api', function($api) {
    $api['key'] = 'YOURAPIKEY';
    return $api;
});

Feld: Datumsauswahl

Feld: Datums- und Uhrzeitauswahl

Feld: Zeitauswahl

Feld: Farbwähler

Feld: Galerie (nur ACF Pro)

Spezielle Arten von Feldern

ACF bietet auch einige Feldtypen an, die per se keinen Wert speichern, die aber eher organisatorischen Zwecken dienen. Für alle diese 'name'auf eine leere Zeichenfolge setzen.

HTML-Nachricht

Wenn Sie einfach etwas HTML ausdrucken müssen, ohne dass tatsächlich ein Wert gespeichert wird, können Sie type verwenden 'message'.

Repeater (nur ACF Pro)

Ein Repeater enthält ein Array von Feldern, die wiederholt werden können.

Das Element sub_fieldserwartet ein Array von Feldern, genau wie Sie oben Felder eingerichtet haben.

Fazit

Dies ist keineswegs eine erschöpfende Anleitung, da ACF eine so große Auswahl an Optionen und Anpassungen bietet. Aber es sollte die am häufigsten verwendeten Optionen und benutzerdefinierten Anwendungsfälle abdecken. Persönlich beziehe ich mich oft darauf, wenn ich ACF-Felder für Clients hinzufüge. Und selbst für die seltsamsten Optionen reicht diese Anleitung aus, sodass ich meine PHP-Dateien nicht mit dem Exportcode von ACF aufblähen muss. Ich hoffe, dies war auch für Sie nützlich!