Anleitung zur Korrektur des Codes eigener Plugins
Anleitung zur Adaption individueller Plugins für Visforms 5
Diese Anleitung beschreibt die notwendigen Schritte für die Anpassung eines einfaches individuelles Plugin mit dem Namen myplugin.
Dieses fiktive Plugin implementiert einen Event-Handler für das Visforms Event onVisformsAfterFormSave.
Es sind Änderungen in den folgenden Bereichen notwendig:
- Verzeichnis-Struktur,
- Datei-Struktur,
- Codeanpassung in den betroffenen Dateien.
Die Anpassungen müssen auf einer Joomla 5 Installation mit Visforms 5 durchgeführt werden. Eine eventuelle Visforms Subscription muss ebenfalls die Version 5 besitzen.
Verzeichnisstruktur unter Joomla 4
Auf Joomla 4 liegt das Plugin myplugin im Verzeichnis
plugins/visforms/myplugin
und hat folgende Dateistruktur
plugins/visforms/myplugin
plugins/visforms/myplugin/index.html
plugins/visforms/myplugin/myplugin.php
plugins/visforms/myplugin/myplugin.xml
Verzeichnisstruktur unter Joomla 5
Auf Joomla 5 liegt das Plugin myplugin ebenfalls im Verzeichnis
plugins/visforms/myplugin
und hat folgende Verzeichnis- und Dateistruktur
plugins/visforms/myplugin
plugins/visforms/myplugin/index.html
plugins/visforms/myplugin/myplugin.xml
plugins/visforms/myplugin/services
plugins/visforms/myplugin/services/provider.php
plugins/visforms/myplugin/src
plugins/visforms/myplugin/src/Extension
plugins/visforms/myplugin/src/Extension/Myplugin.php
Das Vorgehen
Verzeichnisse anlegen
Legen Sie in einem ersten Schritt die neuen Verzeichnisse an.
plugins/visforms/myplugin/services/provider.php
plugins/visforms/myplugin/src
plugins/visforms/myplugin/src/Extension
Hinweis: Achten Sie auf Groß- und Kleinschreibung.
Anpassungen an den Dateien
Kopieren der Datei provider.php
von
plugins/visforms/vfcustomplugin/services
zu
plugins/visforms/myplugin/services
Verschieben der Datei myplugin.php
von
plugins/visforms/myplugin
zu
plugins/visforms/myplugin/src/Extension
Umbenennung Datei myplugin.php
in Myplugin.php
plugins/visforms/myplugin/src/Extension/Myplugin.php
Anpassungen an der Datei provider.php
Zeile 24:
alt: use Visolutions\Plugin\Visforms\Vfcustomplugin\Extension\Vfcustomplugin;
neu: Visolutions\Plugin\Visforms\Myplugin\Extension\Myplugin
Zeile 35:
alt: $plugin = new Vfcustomplugin(
neu: $plugin = new Myplugin(
Zeile 37:
alt: (array) PluginHelper::getPlugin('visforms', 'vfcustomplugin')
neu: (array) PluginHelper::getPlugin('visforms', 'myplugin')
Anpassungen an der Datei Myplugin.php
Namespace hinzufügen (erste Codezeile direkt nach dem öffnendem php-Tag)
namespace Visolutions\Plugin\Visforms\Myplugin\Extension;
Allgemeine use-Statements
Fügen Sie die allgemeinen use-Statements hinzu.
use Joomla\CMS\MVC\Factory\MVCFactoryAwareTrait;
use Joomla\Database\DatabaseAwareTrait;
use Joomla\Event\SubscriberInterface;
Event-spezifische use-Statements
Fügen Sie ein Event-spezifisches use-Statement hinzu.
Für jedes Visforms-Event, für das ein Event-Handler implementiert ist, muss ein entsprechendes use-Statement hinzugefügt werden.
Weiter unten steht, wo Sie eine Liste aller Visforms Events und ihrer use-Statements finden:
Liste aller Visforms Events und ihrer use-Statements.
Das fiktive Plugin implementiert einen Event-Handler für das Event onVisformsAfterFormSave.
Es kommt also das folgende use-Statement für dieses spezifische Event hinzu:
use Visolutions\Component\Visforms\Site\Event\Visforms\VisformsAfterFormSaveEvent;
Anpassung der Klassendefinition
alt:
class plgVisformsMyplugin extends CMSPlugin {
neu:
class Myplugin extends CMSPlugin implements SubscriberInterface {
use MVCFactoryAwareTrait;
use DatabaseAwareTrait;
Events und deren Handler anmelden
Hinzufügen der getSubscribedEvents() Funktion:
public static function getSubscribedEvents(): array {
return [
'onVisformsAfterFormSave' => 'onVisformsAfterFormSave',
];
}
Sie müssen für jedes unterstütze Event und seinen Event-Handler, dem zurückgegebenen Array dieser Funktion jeweils einen Eintrag hinzufügen.
Beispiel mit mehreren Event-Handler
In der folgenden Datei finden Sie ein Beispiel, das gleich mehrere Events und deren jeweilger Event-Handler enthält:
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php
Anpassungen an der Event-Handler Funktion onVisformsAfterFormSave()
alt:
public function onVisformsAfterFormSave($context, $form, $fields): bool {
// context = 'com_visforms.form'
return true;
}
neu:
public function onVisformsAfterFormSave(VisformsAfterFormSaveEvent $event): void {
// context = 'com_visforms.form'
$context = $event->getContext();
$form = $event->getForm();
$fields = $event->getFields();
}
Das Event-Objekt als einziger Parameter
Statt einer Liste von Funktionsparametern gibt es nur das Event-Objekt als einzigen Parameter. Das Event-Objekt enthält alle alten Funktionsparameter. Auf diese können Sie mit den entsprechenden Member-Funktionen des Event-Objektes zugreifen.
Beispiel mit allen Visforms Event-Objekten
In der folgenden Datei finden Beispiele für alle von Visforms unterstützten Events sowie die zu verwendenden Funktionen. Die Auflistung in diesem Beispiel-Code ist vollständig.:
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php
Rückgabewerte: Parameter
Ein Parameter, den der Plugin-Code zur direkten Steuerung von Visforms geändert hat, muss zur Rückgabe an Visforms in das Event zurückgeschrieben werden. In einigen Fälle ist dies sogar zwingend notwendig. Wie das vor sich geht, geht ebenfalls aus dem Beispiel-Code hervor. Im Event-Handler gibt es dann einen folgenden Aufruf:
$event->setArgument();
Rückgabewerte: Ergebnis
Manche Events können zusätzlich ein Ergebnis (true/false) zurückgeben, etwa das Event onVisformsBeforeEditSave. In Visforms 4 war das z.B.:
return true;
return false;
In Visforms 5 verwenden Sie dazu die folgende Funktion:
$event->addResult(true);
$event->addResult(false);
Für alle Events, die einen Booleschen Return-Wert tatsächlich auswerten, ist die Funktion $event->addResult() im folgenden Beispielcode im Event-Handler explizit mit aufgeführt.
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php
Konstruktor anpassen bei sehr alten Plugins
Falls Sie ein sehr altes Plugin haben, ist es eventuell zusätzlich nötig den Konstruktor anzupassen.
Die korrekte Signatur lautet:
public function __construct(DispatcherInterface $subject, array $config)
Rufen Sie im Konstruktor ein parent::__construct() auf, so lautet die Codezeile:
parent::__construct($subject, $config);
Anpassungen an der Datei myplugin.xml
An der Manifest-Datei des Plugins sind ebenfalls Anpassungen notwendig.
Den Namespace dem extension Knoten hinzufügen:
<namespace path="src">Visolutions\Plugin\Visforms\Myplugin</namespace>
Anpassung des files Knoten:
alt:
<files>
<filename plugin="myplugin">myplugin.php</filename>
<filename>index.html</filename>
</files>
neu:
<files>
<folder plugin="myplugin">services</folder>
<folder>src</folder>
<filename>index.html</filename>
</files>
Hinweis: Das Plugin muss entweder neu installiert werden oder Sie registrieren den Namespace manuell.
Da das Plugin nun unter einem Namespace registriert wird, müssen Sie entweder:
- Das Plugin explizit neu installieren.
- Das Verzeichnis zippen.
- Die Zip-Datei über den Joomla Installer installieren.
- Den Namespace manuell registrieren.
Dies geschieht in der Dateiadministrator/cache/autoload_psr4.php.Fügen Sie einfach die folgende Zeile hinzu:
'Visolutions\\Plugin\\Visforms\\Myplugin\\' => [JPATH_PLUGINS . '/visforms/myplugin/src'],
Liste aller Visforms Events und deren use Statements:
In der folgenden Datei finden Sie eine vollständige Liste aller Visforms Events und ihrer use Statements:
plugins/visforms/myplugin/src/Extension/vfcustomplugin.php