Individuelle Submit Handler - Beispiel für die Entwicklung eines individuellen Visforms Plugins
Seit Visforms 3.10.0 ist es möglich allein durch die Verwendung eines Visforms Plugins dem Formular einen eigenen Submithandler updatesicher zu übergeben. Bei früheren Versionen war es nötig ein Override der Datei validation.php anzulegen, das nach Visforms Updates häufig angepasst werden musste.
Da die Anforderungen, was ein eigener Submithandler tun soll, zwischen zwei Visformsnutzer fast nie gleich sind, müssen Sie das, was Ihr Submithandler machen soll, selbst programmieren, d.h. ein individuelles Visforms Plugin schreiben. Dies erfordert etwas Erfahrung in der Programmierung mit php und Javascript oder die Bereitschaft sich einzuarbeiten. Um Ihnen den Einstieg zu erleichtern haben wir eine Plugin-Vorlage erstellt. Im folgenden Beitrag versuchen wir, Schritt für Schritt zu erklären, wie Sie die Plugin-Vorlage für Ihre Bedürfnisse anpassen müssen und bringen konkrete Code-Beispiele für die Implementierung einiger besonders häufig nachgefragter Submithandler-Aktionen.
Anleitung zur Erstellung eines eigenen Plugins
Laden Sie die die Plugin-Vorlage für Joomla 4 bzw. Plugin-Vorlage für Joomla 3 herunter und entpacken Sie die zip Datei. Diese enthält drei Dateien. Eine index.html, eine plgmaster.xml und eine plgmaster.php. Bitte beachten Sie, dass Sie diese Vorlage nur mit Visforms 3.10.0 (oder höher) verwenden können. Wenn Sie das Plugin mit dem Content Plugin Visforms Form View zusammen verwenden wollen benötigen Sie mindestens die Version 3.0.0 des Content Plugin Visforms Form View!, das mit der Visforms Subscription ab Version 3.0.0 ausgeliefert wird.
Die index.html hat allein die Funktion, das Verzeichnis, in dem das Plugin später installiert wird, dahingehend zu schützen, dass man nicht von außen sehen kann, welche Dateien es enthält. Diese Datei müssen Sie überhaupt nicht anfassen.
Die plgmaster.xml ist die Vorlage für die Steuerdatei, die bei der Installation des Plugins benötigt wird. Sie enthält wichtige Informationen für die Installation des Plugins (wie den Namen, Typ, zu installierende Dateien, Version) und Metainformationen über das Plugin, wie z.B. das Datum, wann es entwickelt wurde und von wem.
Die plgmaster.php enthält den eigentlichen Code, der durch das Plugin ausgeführt wird.
Das eigene Plugin mit einem Namen versehen
Als erstes sollten Sie Ihr Plugin mit einem eigenen Namen versehen. Dieser sollte aus einem Wort in Kleinschreibung bestehen z.B. "meinvisformssubmithandler". In der Vorlage ist der Name "plgmaster". Um das Plugin mit einem eigenen Namen zu versehen, d.h. damit Joomla! es unter diesem Namen installiert und verwenden kann, müssen Sie die Zeichenkette "plgmaster" an zahlreichen Stellen mit Ihrem Pluginnamen ersetzen. Benennen Sie zuerst die Dateien plgmaster.xml und plgmaster.php um, indem Sie die Zeichenkette "plgmaster" mit Ihrem Pluginnamen ersetzen. Anschließend ersetzen Sie die Zeichenkette "plgmaster" an folgenden Stellen innerhalb dieser beiden Dateien. Öffnen Sie hierzu jeweils die umbenannte Datei mit einem Editorprogramm Ihrer Wahl.
In der umbenannten plgmaster.xml Datei müssen Sie die Zeichenkette an 3 Stellen ersetzen. In <name>plgmaster</name> und in <filename plugin="plgmaster">plgmaster.php</filename>
In der umbenannten plgmaster.php Datei müssen Sie die Zeichenkette an 1 Stelle ersetzen, nämlich im Namen der php Klasse. In class plgVisformsPlgmaster extends JPlugin. Für eine bessere Lesbarkeit sollten Sie hier Ihren Pluginnamen mit einem Großbuchstaben am Anfang verwenden. Der Code funktioniert aber auch, wenn der Klassenname nur Kleinbuchstaben enthält.
Metainformationen anpassen
Anschließend sollten Sie folgende Metainformationen in der umbenannte Datei plgmaster.xml anpassen, indem Sie den Wert im jeweiligen XML-Knoten entsprechend Ihren Voraussetzungen ändern. Ein XML-Knoten besteht immer aus einem öffnenden Element (z.B. <author>), einem schließenden Element (z.B. </author>)und einen Text dazwischen. Passen Sie die Texte in folgenden XML-Knoten an. Einige Informationen sind nicht zwingend notwendig und können auch ganz entfallen, indem Sie den kompletten XML-Knoten löschen.
<author>: Autor<creationDate>: Erstelldatum<copyright>: Copyright Information (kann auch entfallen)<license>: Lizenztyp (kann auch entfallen)<authorEmail>: E-Mail des Autors (kann auch entfallen)<authorUrl>: Url des Autors (kann auch entfallen)<description>: Text der in der Administration als Beschreibung des Plugins angezeigt wird
Alle anderen XML-Knoten lassen Sie unverändert.
Plugincode schreiben
Nachdem nun alle Rahmenbedingungen für die korrekte Installation des Plugins gesetzt sind, können Sie den eigentlichen Code für Ihren Submithandler schreiben. Öffnen Sie die umbenannte Datei plgmaster.php und schauen Sie sich kurz den Democode an.
Die Funktion onVisformsFormPrepare wird ausgeführt, bevor das Formular zur Anzeige gebracht wird
Code, den Sie in die public function onVisformsFormPrepare($context, $form, $menuparams) schreiben wird ausgeführt, bevor das Formular zur Anzeige gebracht wird. In dieser Funktion können Sie alle möglichen Manipulationen am Formular und den Feldern vornehmen und vor allem der Seite individuelles Javascript hinzufügen.
Mit individuellem Javascript können Sie z.B. dem Formular versteckte Steuerfelder hinzufügen, deren Wert dynamisch gesetzt wird und die mit dem Post übermittelt werden. Oder Sie können den Absenden-Vorgang blockieren.
Die Funktion onVisformsBeforeFormSave wird ausgeführt, bevor die Daten auf dem Server bearbeitet werden
Code, den Sie in die public function onVisformsBeforeFormSave($context, $form, $fields) schreiben wird ausgeführt, bevor die eigentliche Verarbeitung der mit dem Formular übertragenen Daten (wie Daten speichern, Mails schicken, PDF's erzeugen, Ergebnistext anzeigen) auf dem Server beginnt. Hier können Sie diesen Prozess manipulieren, indem Sie z.B. Formularparameter dynamisch umsetzen und serverseitige Sicherheitchecks durchführen.
Rumpfcode der onVisformsFormPrepare Funktion
public function onVisformsFormPrepare($context, $form, $menuparams)
{
// Skip plugin if context is wrong
$allowedContexts = array('com_visforms.form', 'mod_visforms.form', 'plg_vfformview.form');
if (!in_array($context, $allowedContexts)) {
return true;
}
$app = JFactory::getApplication();
// only perform action, if we are in front end
if ($app->isAdmin()) {
return true;
}
//if $form->parentFormId is not set, Visforms or Content Plugin Form View version is to old
if (!isset($form->parentFormId)) {
return true;
}
// get value of id attribute of the form which is going to be displayed for furhter use
$parentFormId = $form->parentFormId;
// add custom submit handler function to the form
$script = 'jQuery(document).ready(function () {
//add custom submit action function to form
window["' . $parentFormId . 'SubmitAction"] = function (form) {
// your code in here
//return false to prevent form from being submitted, return true, if submithandler performs another action but form should be send
return true;
};
});';
JFactory::getDocument()->addScriptDeclaration($script);
// End: add custom submit handler function to the form
}
Der Parameter $context
Der Parameter $context enthält Informationen darüber, von wo aus die Funktion onVisformsFormPrepare aufgerufen wurde, d.h. ob ein Visforms Formular über einen Menüeintrag vom Typ Visforms >> Formular, über ein Visforms Module oder das Content Plugin Visforms Form View (aus der Subscription) zur Anzeige gebracht wird. Mit Hilfe dieses Parameters ist es z.B. möglich zu steuern, dass ein individueller Submithandler nur zu Formularen hinzugefügt wird, die über ein Modul zur Anzeige gebracht werden.
- $context === 'com_visforms.form' : Formular wird über Menüeintrag vom Typ Visforms >> Formular angezeigt
- $context === 'mod_visforms.form' : Formular wird über ein Visforms Modul angezeigt
- $context === 'plg_vfformview.form' : Formular wird in einem Beitrag über das Content Plugin Form View angezeigt.
Prinzipiell sollten Sie sicherstellen, dass Ihr Plugin-Code nur abläuft, wenn er tatsächlich gebraucht wird. Über die Variable $allowedContexts können Sie steueren, in welchen Fällen der Plugincode ablaufen soll.
Der Parameter $form
Der Parameter $form enthält das komplette Formular. Mit $form->id können Sie auf die Id des Formulars, das gerade angezeigt wird zugreifen, mit $form->parentFormId auf das HTML id-Attribut des <form>-Elements.
Sie können z.B. die Bedingung if ($form->id !== 1) {return true;} verwenden um sicherzustellen, dass der Plugincode nur für das Formular mit der Id 1 ausgeführt wird. Oder Sie können die Formularid nutzen um für unterschiedliche Formulare unterschiedlichen Code ablaufen zu lassen.
if ($form->id === 1) {
// do stuff for form 1
}
if ($form->id === 2) {
// do stuff for form 2
}
Der Parameter $menuparams
Dieser Parameter wird für ein Plugin, dass einen individuellen Submithandler implementiert in der Regel nicht benötigt. Über diesen Parameter könnten Sie z.B. dynamisch festlegen, ob der Formulartitel angezeigt wird oder nicht.
Die Javascript Submithandler Funktion
Wenn ein Benutzer versucht das Formular abzusenden, werden zuerst die Benutzereingaben browserseitig mit Javascript validiert. Dann prüft der Visforms Code zuerst, ob es eine formularspezifische Javascriptfunktion mit eine speziellen Namen gibt. Der Funktionsnamen setzt sich aus der id des HTML-form Elements ($parentFormId) und dem Wort SubmitAction zusammen. Ist eine solche Javascriptfunktion vorhanden, dann wird diese nun ausgeführt und kann genutzt werden, um spezielle Aktionen auszuführen. Abhängig vom Rückgabewert der Funktion wird das Formular anschließend normal abgeschickt (Rückgabewert ist true) oder das Abschicken unterbunden (Rückgabewert ist false). Bitte stellen Sie also immer sicher, dass Ihre Funktion den korrekten Rückgabewert hat.
Der Rumpfcode der function onVisformsBeforeFormSave
public function onVisformsBeforeFormSave($context, $form, $fields)
{
// Skip plugin if context is wrong
$allowedContexts = array('com_visforms.form', 'mod_visforms.form', 'plg_vfformview.form');
if (!in_array($context, $allowedContexts)) {
return true;
}
$app = JFactory::getApplication();
// only perform action, if we are in front end
if ($app->isAdmin()) {
return true;
}
// your code in here
return true;
}
Zu den Parametern siehe weiter oben in der Beschreibung der Funktion onVisformsFormPrepare. Der Parameter $form->parentFormId, der nur im Frontend benötigt wird, ist hier nicht vorhanden.
Beispielcode 1 - Submit durch nicht angemeldet Benutzer verhindern
onVisformsFormPrepare anpassen
Ersetzen Sie den Rumpfcode im umbenannten plgmaster.php der zwischen // add custom submit handler function to the form und // End: add custom submit handler function to the form steht mit untenstehendem Code. Dieser Code prüft, ob der Benutzer, der das Formular ausfüllt, angemeldet ist. Wenn nicht, wird dem Formular eine Javascriptfunktion hinzugefügt, der eine Nachricht ausgibt und das Absenden des Formulars unterbindet.
// add custom submit handler function to the form
$user = JFactory::getUser();
// user is not logged on. Add Javascript that prevent form from being send
if (!$user->id) {
$script = 'jQuery(document).ready(function () {
//add custom submit action function to form
window["' . $parentFormId . 'SubmitAction"] = function (form) {
alert("Please log in first");
return false;
};
});';
JFactory::getDocument()->addScriptDeclaration($script);
}
onVisformsBeforeFormSave anpassen
Ersetzen Sie // your code in here mit folgendem Code
$user = JFactory::getUser();
if (!$user->id) {
$message = 'Please log in first';
$app = JFactory::getApplication();
$input = $app->input;
$return = $input->post->get('return', null, 'cmd');
$url = (!empty($return)) ? base64_decode(strtr($return, '-_,', '+/=')) : 'index.php';
$app->redirect(JRoute::_($url, false), $message, 'warning');
$app->close();
}
Beispielcode 2 - Dem Formular ein verstecktes Feld hinzufügen und dessen Wert dynamisch setzen
Das Beispiel geht davon aus, dass es unter dem Formular 2 unterschiedliche Submit-Button gibt. Je nachdem welchen Button der Benutzer verwendet wird ein Wert in einem dynamisch hinzugefügten versteckten Feld dynamisch gesetzt. Dieser Wert kann dann im php-Code ausgewertet werden. In unserem Beispiel werden Mail geschickt, wenn der Benutzer auf den 2 Button geklickt hat. Ersetzen Sie hierzu den Rumpfcode im umbenannten plgmaster.php der zwischen // add custom submit handler function to the form und // End: add custom submit handler function to the form steht mit untenstehendem Code.
Der Vorteil der Verwendung eines dynamisch erzeugen versteckten Feldes ist, dass dieses Visforms nicht bekannt ist und auch nicht in der Datenbank gespeichert oder mit Mails übertragen wird. Der 2. Submitbutton erhält die Klasse "formready".
onVisformsFormPrepare anpassen
$script = 'jQuery(document).ready(function () {jQuery("<input/>",
{"id" : "'. $parentFormId .'myhiddenfield",
"type" : "hidden",
"value" : "0",
"name" : "myhiddenfield"}).appendTo("#'.$parentFormId.'");
//add custom submit action function to form
window["'.$parentFormId.'SubmitAction"] = function (form) {if (jQuery(form.submitButton).hasClass("formready"))
{
jQuery("#'.$parentFormId.'myhiddenfield").val("1");
}};
});';
JFactory::getDocument()->addScriptDeclaration($script);
onVisformsBeforeFormSave anpassen
Ersetzen Sie // your code in here mit folgendem Code
$formisready = $app->input->post->get('myhiddenfield', "0", 'STRING');
if (!empty($formisready)) {
$form->emailresult = 1;
$form->emailreceipt = 1;
}
Fertigstellung und Installation
- Erzeugen Sie vom Verzeichnis mit den geänderten Dateienein ein zip
- Installieren Sie die Erweiterung über den Joomla! Erweiterungen Manager
- Veröffentlichen Sie die Erweiterungen im Joomla! Erweiterungen Mananger
- Testen Sie das Plugin