Wer meinem Blog regelmäßig liest, wird sicher festgestellt haben, dass ich in vielen Projekten Gravity Forms verwende. Ich mag die große Vielfalt an Funktionen des Plugins (und seiner Erweiterungen) sehr, aber vielleicht noch sehr viel mehr die Möglichkeit, viele Dinge anzupassen. Ich habe auch dabei geholfen eine Erweiterung zu schreiben, mit er es möglich ist, alle Dateien eines Eintrags (oder mehrerer Einträge) auf einmal herunterzuladen. Diese Woche haben wir eine neue Version veröffentlicht, die eine kleine aber wichtige Neuerung enthält: die Möglichkeit, Hooks nur für bestimmte Formular zu verwenden.
Hooks in Gravity Forms verwenden
Wenn man Gravity Forms Funktionalitäten anpassen möchte, dann funktioniert das genau wie im Core oder in Plugins/Themes. Ihr verwendet die Funktionen add_action() oder add_filter() für euren eigenen Code. Und Gravity Forms hat sehr viele Actions und Filter.
Sehen wir uns als Beispiel die gform_pre_submission Action an. Ihr könnt diese verwenden, um einen Eintrag zu verändern, bevor Benachrichtigungen versendet wurden und vor der Speicherung des Eintrags in der Datenbank. Ein Anwendungsfall könnte wie folgt aussehen:
function my_gform_pre_submission( $form ) {
$_POST['input_1'] = strtolower( $_POST['input_1'] );
}
add_action( 'gform_pre_submission', 'my_gform_pre_submission' );
Dies würde den Wert vom Formularfeld mit der ID 1 (input_1) nehmen und den Textwert in Kleinbuchstaben ändern. Dies würde allerdings für jedes einzelne Formular angewendet werden. Wenn ihr es nur für ein Formular anwenden wollt, dann müsst ihr es für die Action so schreiben, dass sie nur für dieses eine Formular greift. Glücklicherweise ist bei Gravity Forms genau das möglich, denn ihr könnt Hook-Namen dynamisch verwenden. Ersetzt hierzu den add_action Aufruf wie folgt:
add_action( 'gform_pre_submission_5', 'my_gform_pre_submission' );
Dieser Action-Name hat einen Suffix _5 und wird daher nur für das Formular mit der ID 5 aufgerufen. Ich hatte das bereits im Blogbeitrag Dynamische Formular-Hooks für GravityForms Anfang des Jahres erklärt und dabei auch beschrieben, wie man mit diesen statischen Werten für die IDs der Formulare in den Hook-Namen umgehen kann.
Nachdem wir also in dieser kleinen Einführung noch einmal die Grundlagen wiederholt habe, können wir in das eigentliche Thema einsteigen und uns ansehen, wie ihr Hooks nur für bestimmte Formulare in eurem eigenen Code verwendet.
Hooks in eurem Code anbieten
Wenn ihr eine Veränderung von Teilen eures Codes erlauben möchtet, dann müsst ihr dazu eine diese beiden Funktionen verwenden:
Ihr könnt euch sicherlich schon denken, welche Funktion hier jeweils für welche Art von Hook verwendet wird. Der Unterschied besteht darin, dass ein Filter einen Wert zurückgibt, eine Action aber nicht. Wenn ihr also einen Filter verwenden möchtet, dann sieht es in etwa wie folgt aus:
$value = apply_filters( 'filter_name', $value, $arg1, $arg2 );
Ihr definiert also einen Namen für den Filter und übergebt die Variable, die verändert werden soll. Optional könnt ihr weitere Argumente übergeben, mit deren Hilfe ihr dann innerhalb der Callback-Funktion entschieden könnt, wie ihr den Wert verändert.
Für eine Action sieht es ziemlich ähnlich aus. Ihr speichert aber keinen Rückgabewert, da die Funktion auch nichts zurückgibt:
do_action( 'action_name', $arg1, $arg2 );
Und weil die Funktion keinen Wert verändert, müsst ihr auch nicht zwingend eine Variable übergeben, es sind also alle Argumente optional. Viele Actions bekommen gar keinen Wert übergeben, wie etwa die wp_head Action.
Den Hook formularspezifischen machen
Nachdem wir nun also gelernt haben, wie man Hooks zum eigenen Code hinzufügt, sehen wir uns jetzt an, wie man diese nur für bestimmte Formular ausführen lässt. In der offiziellen Dokumentation von Gravity Forms findet sich nur eine Seite zu Actions, aber leider ohne viel Erklärung. Die Veränderungen, die ihr machen müsst, sind aber für Actions und Filter identisch. Alles, was ihr tun müsst, ist die Funktionen mit einem gf_ Präfix zu versehen und als ersten Parameter ein Array mit dem Hook-Namen und der Formular-ID zu übergeben. Für einen Filter sieht es dann wie folgt aus:
$value = gf_apply_filters( array( 'filter_name' $form_id ), $value, $arg1, $arg2 );
In diesem Beispiel gehen wir davon aus, dass die Formular-ID in der Variablen $form_id gespeichert ist, sie könnte aber auch in $form['id'], $entry['form_id'] oder etwas Ähnlichem enthalten sein. Ihr müsst also nur sicherstellen, dass ihr sie an die Funktion übergebt. Für eine Action sieht der Funktionsaufruf dann wie folgt aus:
gf_do_action( array( 'action_name' $form_id ), $arg1, $arg2 )
Das war auch schon alles, was ihr tun müsst!
Fazit
Wenn ihr eine Erweiterung, ein Plugin oder eigenen Code für Gravity Forms schreibt, ist es immer gut, wenn ihr euch überlegt, an welchen Stellen jemand eventuell euren Code anpassen möchte. Hierfür dann Hooks zur Verfügung zu stellen, kann euren Code sehr viel besser nutzbar machen. Und wenn ihr diese Hooks hinzufügt, dann verwendet dabei immer die Gravity Forms Funktionen, damit sie spezifisch für individuelle Formulare verwendet werden können.
