Code-Korrektur eigener Plugins

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 Datei
    administrator/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