Erstellung eines Plugins

Individuelle Funktionalit├Ąt durch individuelle Plugins

Visforms verf├╝gt ├╝ber ein umfangreiches eigenes Event-System. Es erm├Âglicht Visforms mit individuellem Code gezielt zu erweitern. Mehr dazu in: Event-System f├╝r den Workflow.

Eigener Submit Handler - Beispiel f├╝r die Entwicklung eines eigenen Visforms-Plugins

Beispielsweise k├Ânnen Sie allein durch die Verwendung eines Visforms-Plugins dem Formular einen eigenen Submit-Handler Update-sicher ├╝bergeben. Zwischen zwei Visforms-Nutzern sind die Anforderungen, was denn ein eigener Submit-Handler genau leisten soll, sehr unterschiedlich. Daher m├╝ssen Sie das, was Ihr Submit-Handler machen soll, selbst programmieren: Sie m├╝ssen ein individuelles Visforms-Plugin schreiben. Dies erfordert etwas Erfahrung in der Programmierung mit PHP und JavaScript oder zumindest die Bereitschaft sich in beides etwas 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 unsere Plugin-Vorlage f├╝r Ihre Bed├╝rfnisse anpassen m├╝ssen. Wir geben au├čerdem konkrete Code-Beispiele f├╝r die Implementierung einiger h├Ąufig nachgefragter Submit-Handler-Aktionen.

Anleitung zur Erstellung eines Plugins

Laden Sie die Plugin-Vorlage f├╝r Joomla 4 herunter und entpacken Sie die ZIP-Datei: Download Plugin Master. Dieses ZIP-Archiv enth├Ąlt drei Dateien:

  • eine index.html,
  • eine plgmaster.xml und
  • eine plgmaster.php.

Die index.html hat allein die Funktion, das Verzeichnis in dem das Plugin sp├Ąter installiert wird, vor fremder Einsicht zu sch├╝tzen. Mit der Existenz dieser Datei kann man nicht l├Ąnger von au├čen sehen, welche Dateien das Verzeichnis enth├Ąlt.
Diese Datei m├╝ssen Sie nicht ver├Ąndern.

Die plgmaster.xml ist die Vorlage f├╝r die sogenannte Manifest-Datei mit den sogenannten Manifest-Daten. Sie wird bei der Installation des Plugins unbedingt ben├Âtigt.

Sie enth├Ąlt wichtige Informationen f├╝r die Installation des Plugins wie

  • den Namen,
  • den Plugin-Typ,
  • die zu installierenden Dateien,
  • die Plugin-Version.

Sie enth├Ąlt auch sogenannte Metainformationen ├╝ber das Plugin wie

  • das Datum, wann es entwickelt wurde und
  • von wem es entwickelt wurde.

Die plgmaster.php enth├Ąlt den eigentlichen Code, der durch das Plugin ausgef├╝hrt wird.

Das Plugin mit einem Namen versehen

Als Erstes sollten Sie Ihr Plugin mit einem eigenen Namen versehen. Dieser sollte aus einem Wort in Kleinschreibung bestehen, etwa “meinvisformssubmithandler”. In der Vorlage ist der Name “plgmaster”. Um das Plugin mit einem eigenen Namen zu versehen, damit Joomla es unter diesem Namen installiert und verwenden kann, m├╝ssen Sie die Zeichenkette “plgmaster” an zahlreichen Stellen mit Ihrem eigenen Plugin-Namen ersetzen.

Benennen Sie zuerst die Dateien plgmaster.xml und plgmaster.php um, indem Sie die Zeichenkette “plgmaster” mit Ihrem eigenen Plugin-Namen ersetzen. Anschlie├čend ersetzen Sie die Zeichenkette “plgmaster” an folgenden Stellen innerhalb dieser beiden Dateien. ├ľffnen Sie hierzu jeweils die umbenannte Datei mit einem Editor-Programm Ihrer Wahl.

In der umbenannten plgmaster.xml Datei m├╝ssen Sie die Zeichenkette “plgmaster” 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 “Plgmaster” an 1 Stelle ersetzen:

  • im Namen der PHP Klasse class plgVisformsPlgmaster extends JPlugin.

F├╝r eine bessere Lesbarkeit sollten Sie hier Ihren Plugin-Namen 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 umbenannten Datei plgmaster.xml anpassen. Das machen Sie, indem Sie den Wert im jeweiligen XML-Knoten entsprechend Ihren Voraussetzungen ├Ąndern.

Ein sogenannter XML-Knoten besteht immer aus

  • einem ├Âffnenden Element (z.B. <author>),
  • einem schlie├čenden Element (z.B. </author>) und
  • einem 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 einfach 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.

Den Plugin-Code schreiben

Nachdem nun alle Rahmenbedingungen f├╝r die korrekte Installation des Plugins gesetzt sind, k├Ânnen Sie den eigentlichen Code f├╝r Ihren Submit-Handler schreiben. ├ľffnen Sie die umbenannte Datei plgmaster.php und schauen Sie sich kurz den Democode an.

Die Funktion onVisformsFormPrepare()

Code in der public function onVisformsFormPrepare($context, $form, $menu_params) Funktion 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. Hier k├Ânnen Sie der Seite auch individuelles JavaScript hinzuf├╝gen.

Mit individuellem JavaScript k├Ânnen Sie etwa dem Formular zus├Ątzliche versteckte Steuerfelder hinzuf├╝gen. Die Werte eins versteckten Steuerfeldes k├Ânnen durch Ihren JavaScript-Code dynamisch gesetzt und mit dem Post ├╝bermittelt werden. Oder Sie k├Ânnen den Absenden-Vorgang blockieren.

Die Funktion onVisformsBeforeFormSave()

Code in der public function onVisformsBeforeFormSave($context, $form, $fields) Funktion wird ausgef├╝hrt, bevor die eigentliche Verarbeitung der mit dem Formular ├╝bertragenen Daten auf dem Server beginnt.

Zu der sp├Ąter beginnenden Verarbeitung geh├Âren etwa

  • Daten speichern,
  • Mails schicken,
  • PDFs erzeugen und
  • Ergebnistext anzeigen.

Hier k├Ânnen Sie diesen Prozess manipulieren. Etwa indem Sie etwa die Formular-Parameter dynamisch ├Ąndern oder eigene serverseitige Sicherheitschecks durchf├╝hren.

Rumpfcode der Funktion onVisformsFormPrepare()

public function onVisformsFormPrepare($context, $form, $menu_params)	{
    // 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 further 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) {
        
        // place 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.
Die unterschiedlichen Aufrufstellen um ein Visforms Formular zur Anzeige zu bringen, k├Ânnen sein:

Mithilfe dieses Parameters kann unter anderem gesteuert werden, dass ein individueller Submit-Handler nur den 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 - Visforms Form View angezeigt.

Prinzipiell sollten Sie immer sicherstellen, dass Ihr Plugin-Code nur dann abl├Ąuft, wenn er auch tats├Ąchlich gebraucht wird.
├ťber die Variable $allowedContexts k├Ânnen Sie steuern, in welchen F├Ąllen der Plugin-Code ablaufen soll.

Der Parameter $form

Der Parameter $form enth├Ąlt das komplette Formular.
Mit $form->id k├Ânnen Sie auf die ID des gerade angezeigten Formulars zugreifen.
Mit dem Wert aus $form->parentFormId kennen Sie das HTML id-Attribut des <form> Elements.
Das <form> Element ist die ├Ąu├čerste HTML-H├╝lle des eigentlichen Formulars.

Sie k├Ânnen z.B. die Bedingung if ($form->id !== 1) {return true;} verwenden.
Damit stellen Sie sicher, dass der Plugin-Code nur f├╝r das Formular mit der ID 1 ausgef├╝hrt wird.
Oder nutzen die Formular-ID nutzen, um f├╝r unterschiedliche Formulare unterschiedlichen Code ablaufen zu lassen.

if ($form->id === 1) {
    // your actions for form 1 ...
}
if ($form->id === 2) {
    // your actions for form 2 ...
}

Der Parameter $menu_params

Der Parameter enth├Ąlt alle administrativen Einstellungen des Men├╝s, mit dem das Formular aufgerufen wurde. Er wird f├╝r ein Plugin, dass einen individuellen Submit-Handler implementiert nicht genutzt. ├ťber diesen Parameter k├Ânnten Sie unter anderem beeinflussen, ob der Formulartitel angezeigt wird oder nicht.

Die JavaScript Submit-Handler Funktion

Wenn ein Benutzer versucht das Formular abzusenden, werden zuerst die Benutzereingaben browserseitig mit JavaScript validiert. Anschlie├čend pr├╝ft der Visforms-Code, ob es eine zus├Ątzliche Submit-Handler Funktion gibt. Die Pr├╝fung sucht dabei nach einer Formular-spezifischen JavaScript-Funktion mit einem speziellen Namen.

Der gesuchte Funktionsname setzt sich aus der ID des HTML-form Elements $parentFormId und dem Wort SubmitAction zusammen. Ist eine solche JavaScript-Funktion vorhanden, wird diese nun ausgef├╝hrt. Sie kann genutzt werden, um spezielle Aktionen auszuf├╝hren.

Abh├Ąngig vom R├╝ckgabewert der Funktion wird das Formular abgeschickt oder nicht.

  • Ist der R├╝ckgabewert true, wird das Formular normal abgeschickt.
  • Ist der R├╝ckgabewert false, wird das Abschicken unterbunden.

Bitte stellen Sie also immer sicher, dass Ihre Funktion den korrekten R├╝ckgabewert hat.

Der Template-Code der Funktion 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 wird nur im Frontend ben├Âtigt. Er ist hier nicht vorhanden.

Beispiel-Code 1: Submit durch nicht angemeldete Benutzer verhindern

Funktion onVisformsFormPrepare() anpassen

Ersetzen Sie den Template-Code im umbenannten plgmaster.php
zwischen
// add custom submit handler function to the form
und
// End: add custom submit handler function to the form
mit dem untenstehendem Code.

Dieser Code pr├╝ft, ob der Benutzer, der das Formular ausf├╝llt, angemeldet ist. Ist der Benutzer nicht angemeldet, wird dem Formular eine JavaScript-Funktion hinzugef├╝gt. Die Funktion aus unserem Beispiel gibt eine Nachricht aus und unterbindet das Absenden des Formulars.

// 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);
}

Funktion onVisformsBeforeFormSave() anpassen

Ersetzen Sie // your code in here mit dem folgenden 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();
    }

Beispiel-Code 2: Ein verstecktes Feld hinzuf├╝gen und dessen Wert dynamisch setzen

Das Beispiel geht davon aus, dass es unter dem Formular 2 unterschiedliche Submit-Buttons gibt. Je nachdem welchen der beiden Buttons der Benutzer verwendet, wird ein unterschiedlicher Wert in dem dynamisch hinzugef├╝gten versteckten Feld gesetzt. Dieser Wert kann dann sp├Ąter im PHP-Code ausgewertet werden.

In unserem Beispiel werden Mails verschickt, wenn der Benutzer auf den 2. Button geklickt hat.

Ersetzen Sie hierzu den Rumpfcode im umbenannten plgmaster.php
zwischen
// add custom submit handler function to the form
und
// End: add custom submit handler function to the form
mit dem untenstehendem Code.

Der Vorteil der Verwendung eines dynamisch erzeugen versteckten Feldes ist, dass es Visforms nicht bekannt ist. Daher wird es auch nicht in der Datenbank gespeichert oder mit Mails ├╝bertragen. Der 2. Submit-Button erh├Ąlt die Klasse “formready”.

Funktion onVisformsFormPrepare() anpassen

$script = 'jQuery(document).ready(function () {jQuery("&lt;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);

Funktion onVisformsBeforeFormSave() anpassen

Ersetzen Sie // your code in here mit dem folgenden Code:

$formisready = $app->input->post->get('myhiddenfield', "0", 'STRING');
if (!empty($formisready)) {
    $form->emailresult = 1;
    $form->emailreceipt = 1;
}

Fertigstellung und Installation

Abschlie├čend m├╝ssen Sie Ihr neues Plugin packen, auf der Joomla Instanz installieren und testen.

  • Erzeugen Sie vom Verzeichnis mit den ge├Ąnderten Dateien ein zip.
  • Installieren Sie die Erweiterung ├╝ber den Joomla Erweiterungen Manager.
  • Ver├Âffentlichen Sie die Erweiterungen im Joomla Erweiterungen Manager.
  • Testen Sie das Plugin.