Plugins - Technische Details

Namenskonventionen

Plugins können prinzipiell beliebig benannt werden. Der Name sollte allerdings am besten nur aus den Buchstaben a-z, Ziffern 0-9 und Unterstrichen ("_") bestehen, damit es später bei Verzeichnissen und PHP-Klassen zu keinen Konflikten kommt.

Verzeichnisstruktur

Nachfolgend die Übersicht zur Sturktur/Hierarchie innerhalb eines Plugin-Verzeichnisses.

Ein Plugin wird unter seinen Namen im Plugin-Verzeichnis core/ecms_v3_plugins hinterlegt. Der Name des Plugin-Verzeichnis darf nur aus Kleinbuchstaben a-z, 0-9 und  Unterstrich "_" bestehen. Umlaute und andere Sonderzeichen sind nicht erlaubt.

Verzeichnis "core"

In diesen Verzeichnis können Komponenten für das core-Verzeichnis abgelegt werden. Alle Verzeichnisse und Dateien aus diesem Verzeichnis werden bei der Plugin-Installation (Recopy-Action) ins core-Verzeichnis der eCMS-Installation kopiert.

Es kann genutzt werden um neue Core-Komponenten, z.B. "mein_core_model_123.class.php"zu hinterlegen, welche durch den eCMS-Autoloader gefunden werden können. Oder um bestehende Core-Libraries um Adaptor-Classes, z.B. "eoscexport/eoscexport_json.export_class.php" zu erweitern.

Verzeichnis "installer"

In dem Verzeichnis können für das Installieren des Plugins Basis-Installer und Update-Scripte hinterlegt werden, mit denen z.B. benötigte Datenbank-Tabellen angelegt oder geändert werden können.

In den Basis-Installer/Update-Scripten ist über den Pointer $this->eCMS der Zugriff auf den eCMS-Admin und über den Pointer $this->eCMS->plugin_siteControl der Zugriff auf aktive Site möglich.

Das Basis-Installer-Script "base_install.inc.php" wird nur bei der Erst-Installation ausgeführt, nicht mehr bei Plugin-Upgrades.

Die Update-Scripte "update_YYYYMMDDHHMM.inc.php" müssen mit einem Datum (YYYYMMDD) oder mit einer Datum-Zeit-Angabe (YYYYMMDDHHMM) versehen werden. Das Datum / die Datum-Zeit-Angabe sollte der Zeitpunkt sein, an dem das Update-Script erstellt wurde. Im Package-Manager wird der Zeitpunkt des letzten Plugin-Upgrades gespeichert. Über dieses können die neuen hinzugekommen Update-Scripte ermittelt werden. Bei einer Erst-Installation werden alle Update-Scripte ausgeführt.

Verzeichnis "install_res"

Über das install_res-Verzeichnis können Formate, Javascript/CSS, Images und auch DB-Inhalte in verschiedene eCMS-Datenbanken installiert werden. Die Adressierung der eCMS-Datenbank wird dabei über die Unterverzeichnisse des  install_res-Verzeichnisses gesteuert.

Hierbei gibt es drei Standard-Verzeichnisse:

• site
  In diesem Verzeichnis können alle Komponente und Inhalte für die aktive Site, z.B. Apps oder Shop-Frontends, hinterlegt werden
• ecms_3_admin
  In diesem Verzeichnis können alle Komponente und Inhalte für den eCMS-Admin hinterlegt werden.
• dev
  In diesem Verzeichnis können Testkomponenten z.B. für automatische Tests hinterlegt werden.

Es gibt weitere Möglichkeiten der eCMS-Adressierung zur Verfügung. So ist beispielsweise erlaubt über den Applikationsnamen den Zugriff auf die eCMS-Datenbank der Applikation herzustellen. Mit dem Namen des  install_res-Unterverzeichnisses sucht der Package-Manager in den Applikationen. Für die Suche werde der Applikationsname an den Verzeichnisnamen angeglichen. Dies bedeutet, dass der Applikationsname in Kleinbuchstaben gewandelt wird und alle Leerzeichen durch Unterstriche ersetzt werden.

Mit Hilfe dieser Option auch über die Applikationen zuzugreifen, wird es möglich Plugin-Inhalte in andere Applikationen zu installieren. So kann ein eigenes Plugin Inhalte in das Shop-Frontend und in das Backend der eCommerceSuite installieren. Ohne diese Option müsste dafür zwei Packages erstellt werden - ein Frontend-Plugin, welches im eCMS Backend in den Shop-Frontend-eCMS installiert wird, und ein Backend-Plugin, welches im eCMS-Backend in das eCommerceSuite-Backend-eCMS installiert wird.

Die Verzeichnisse können kombiniert (Trenner ist "__") werden.

• site__ecs_5_admin
  Verzeichnis-Inhalte werden in aktive Site und eCommerceSuite Backend installiert
• site__ecms_3_admin__ecs_5_admin
  Verzeichnis-Inhalte werden neben aktiver Site und eCommerceSuite Backend auch in das Backend des eCMS installiert

In den Ziel eCMS-Verzeichnissen können drei Unterverzeichnisse hinterlegt werden, die aber auch beim der Erstellung über das SDK angelegt werden:

• data_content
  In diesem Verzeichnis werden alle DB-Inhalte (z.B. Seiten, Layouts, Textbausteine) in Importdateien hinterlegt. Diese werden im Normalfall beim ReverseBuild erzeugt.
• dir_inc
  Alle Include-Komponente, wie Formate oder Service-Classes, werden hier hinterlegt. Das Ziel-Verzeichnis ist in der Site-Konfiguration ( $eCMS->config['site_dir_inc']) definiert. Dieses Verzeichnis enthält wiederum Unterverzeichnisse (z.B.  lib_formatobject - für die Formate), die bei der Pluginerstellung angelegt werden.
• dir_www
  Das Verzeichnis erhält alle WWW-Komponente, wie Image, Icon, CSS- oder Javascript-Dateien. Das Ziel-Verzeichnis ist in der Site-Konfiguration ( $eCMS->config['site_dir_www']) definiert. Dieses Verzeichnis enthält wiederum Unterverzeichnisse (z.B. files - für die Medibase-Inhalte), die bei der Pluginerstellung angelegt werden.

Benutzerrechte

Ein Plugin kann seine eigene Benutzerrechte für Applikationen (z.B. eCMS 3 Admin) mitbringen. Die Benutzerrechte werden in einer CSV Datei direkt im Plugin-Verzeichnis hinterlegt. Der Name der Importdateien muss aus dem Applikation-Namen und der Endung "_apprights.csv" zusammengesetzt werden. Für das eCMS 3 Admin wäre der Dateiname "ecms_3_admin_apprights.csv".

In der CSV-Datei werden die Benutzerrechte in der Spalte "appright" hinterlegt. Alle Benutzerrechte eines Plugin sollten mit "PLUGIN_<NAME>_" beginnen.

Beispiel:

appright
	PLUGIN_EXAMPLE_MYMODEL_READ
	PLUGIN_EXAMPLE_MYMODEL_CREATE
	...

Die Benutzerrechte-Dateien werden am Ende der Plugin-Installation/-Update importiert. Neue Benutzerrechte werden zur Applikation angelegt und dem Profile "superuser" zugewiesen. Bestehende Rechte werden im Import übersprungen. Das Löschen von Rechten ist nur im Basis-Installer und Update-Scripten möglich.

Plugin - Klassen

Nutzung des eCMS Software-Development-Kit (SDK)

Eigene Plugins können mit den wesentlichen Dateien und Verzeichnissen mit Hilfe des eCMS SDK Plugins erstellt werden.

Eine eigene Plugin Klasse

Um eine eigene Plugin Klasse zu erstellen, muss der Konstruktor die eCMS Instanz als einzigen Parameter akzeptieren. Für eine einfache Instanziierung als eCMS Plugin kann die Service-Methode ecms_pluginConfigBridge::plugin_init() genutzt werden.

Der Clou hierbei ist, dass die eigene Plugin-Klasse von beliebigen eigenen Klassen (optional) abgleitet sein kann. Die eCMS-Bridge-Funktionalität fügt dynamisch zur Run-Time Member-Variablen etc. (s.u.) hinzu, die für eine eCMS-Klasse benötigt werden.

class ecms_plugin_beispiel
	{
	    public function __construct($eCMS)
	    {
	        // Objekt init als eCMS Plugin 
	        ecms_pluginConfigBridge::plugin_init($this, $eCMS);        
	    }
	}

Die Methode ecms_pluginConfigBridge::plugin_init() erweitert die Plugin Klassen Instanz um folgende Instanzvariablen:

// eCMS Pointer
	// Egal, ob die Plugin-Class innerhalb einer eCMS-Site oder über das eCMS-Admin
	// aufgerufen wird, ist dies IMMER das "richtige" Site-eCMS-Object!
	$this->eCMS = object;
 
	// Pluginnamen
	$this->pluginname = string;
 
	// Plugin-Config
	$this->Config = array;
 
	// Session-Pointer
	$this->Session = array;
	$this->SessionPmt = array;

Damit dies möglich ist, dürfen die Instanzvariablen nicht als private oder protected deklariert sein.

In der Instanzvariable $this->Config kann auf die Konfiguration des Plugin zugegriffen werden.

In $this->eCMS ist der Pointer auf die eCMS-Instanz vorhanden. An dieser Stelle ein Hinweis zu Plugin SiteControl. Innerhalb eines Plugin sollte es keine Prüfung auf das Plugin SiteControl ( $this->eCMS->plugin_siteControl) geben. Alle Zugriff auf das eCMS sollte über die eCMS-Instanzvariable gehen. Eine Prüfung wie

if (is_object($this->eCMS->plugin_siteControl)==true){
	    // DIES IST SCHLECHT / FALSCH...
	    $this->eCMS->plugin_siteControl->DB->query('SELECT ...');
	} else {
	    $this->eCMS->DB->query('SELECT ...');
	}

ist im Normalfall ein Zeichen für einen falschen Aufruf des Plugin im eCMS-Admin. Im eCMS-Admin (PHC) müsste der Aufruf des Plugin über das Plugin SiteControl gehen, damit im Plugin immer nur die eCMS-Instanzvariable genutzt werden kann.

Die Instanzvariablen "Session" und "SessionPmt" sind Pointer auf einen Unterbreich der Session-Daten, welcher für das Plugin reserviert ist.

Wenn in der Plugin Klasse eine Overload-Methode __get() genutzt wird, gibt es ein Problem mit den Session-Pointer die in ecms_pluginConfigBridge::plugin_init() gesetzt werden, weil Overload-Variablen nicht mit einer Reference überschrieben werden können. Um das Problem zu lösen, müssen die Session-Pointer als Instanzvariablen deklariert werden.

class ecms_plugin_beispiel
	{
	    public $Session;
	    public $SessionPmt;
 
	    public function __construct($eCMS) { }
	}

Plugin Klasse um Konfiguration-Funktion erweitern

Damit ein Plugin durch den eCMS-Package-Manager installiert und konfiguriert kann, muss es folgende Methoden implementieren:

public static function plugin_config_factory($eCMS) { ... }
	public function plugin_config_get($params=null) { ... }
	public function plugin_config_save($params) { ... }
	public function plugin_config_getDialogInfo($params=null) { ... }
	public function plugin_config_validate($params=null) { ... }

Für ein einfach Integration der Methoden stellt das eCMS die Klasse ecms_pluginConfigBridge bereit. In dieser sind die Methoden als Standard-Implementierung vorhanden. Um diese für ein Plugin zu nutzen muss Methode plugin_config_factory() wie folgt im Plugin eingefügt werden.

class ecms_plugin_beispiel
	{
	    public function __construct($eCMS) {  }
 
	    public static function plugin_config_factory ($eCMS)
	    {
	        return ecms_pluginConfigBridge::plugin_config_factory($eCMS, __CLASS__);
	    }
	}

Wird in der Plugin Klasse anschliessend ein Konfigurationsdialog (Methoden plugin_config_getDialogInfo) eingefügt, wird dieser durch die Plugin-Config-Bridge angesteuert. Die restlichen plugin_config-Methoden werden weiter aus der Klasse ecms_pluginConfigBridge bereitgestellt.

Erweiterte Plugin Features

eCMS Events nutzen

Plugins bzw. deren PHP-Klassen-Methoden können sich für andere eCMS-Events registrieren und sich somit indirekt aufrufen lassen.

Plugin-eigener PHP-Class-Autoloader

Es besteht die Möglichkeit einen eigenen PHP-Autoloader für ein Plugin zu definieren, der im Zusammenhang mit diesem immer aufgerufen werden.

Plugin Konfiguration

Plugins, die eine eigene Plugin-Klasse haben, können im eCMS ein eigenes Konfigurations-Array speichern lassen. Für Plugins, die keine eigene Plugin-Klasse haben, gibt es aktuell keine generelle Möglichkeit über das eCMS Konfigurationen verwalten zu lassen.

Lesender Zugriff

Ein installiertes Plugin kann optional eigene Konfigurationen im eCMS pro Site speichern. Auf diese Konfigurationsdaten können zur Run-Time alle Komponenten darauf zugreifen, mit:

$eCMS->plugin_beispiel->Config['<field>']

In dieser Member-Variable Config kann ein beliebiges Array gespeichert werden.

Konfiguration schreiben

Das eCMS stellt grundsätzlich Methoden zum Auslesen und Schreiben von Plugin-Konfigurationsdaten für bereits installierte Plugins zur Verfügung:

$ConfigArray = ecms_plugin_beispiel::plugin_config_factory($eCMS)->plugin_config_get( );
 
	// Das Ergebnis ist ein Array, wie folgt:
	//   $ConfigArray['status'] = true/false;
	//                        ['data'] = Actual Config-Data/-Array.

ecms_plugin_beispiel::plugin_config_factory($eCMS)->plugin_config_save( $ConfigArray );

Konfigurations - Oberflächen

Es gibt zwei Varianten, um eine Plugin-Konfigurations-Oberfläche zu ermöglichen:

1. Die integrierte eCMS-Standard Plugin-Konfigurationsmaske
   Diese eignet sich für einfache Konfigurationsmasken, die auf einer Seite und wenig interaktiv sind. Das eCMS kann darin enthaltene Formularfelder automatisch erzeugen, sofern diese in der Plugin-Klasse als Methode "plugin_config_getDialogInfo" zur Verfügung stehen. Die Eingabe-Validierung ist mit der Methode "plugin_config_validate" möglich.
    
2. Plugin-eigene Konfigurations-GUI
   Plugins können auch komplett eigene Konfigurationsmasken in Form von eigenen eCMS-Admin-Pages usw. zur Verfügung stellen.

Plugin Installation

Plugins können über zwei Wege installiert werden.

Installation über den eFDS-Client

Jede eCMS Installation erhält Zugriff auf verschiedene Plugins über den eFDS-Client. Das eFDS (e-matters File-Distribution-System) ermöglichst die Bereitstellung von Plugins je nach Kundenlizenz.

Im eCMS Backend unter Administration > Plugins > Plugin Liste können alle verfügbaren Plugin eingesehen und zur Installation ausgewählt werden. Über die Liste erhält man außerdem die Möglichkeit die Plugin-Konfiguration aufzurufen. Über die Detailseite des Plugins ist schließlich die Installation des Plugins möglich.

Installation über ZIP-Upload

Wenn Plugins über das eCMS Software-Development-Kit (SDK) erstellt wurden, können diese als ZIP-Datei gepackt und heruntergeladen werden. Im eCMS Backend unter Administration > Plugins > Plugin Uploads erhält man eine Liste aller manuell durchgeführten ZIP-Uploads und kann dort auch weitere (neue) Plugin-ZIP-Dateien hochladen und installieren.

Funktionsweise & Ablauf einer Installation

Wenn ein Plugin in das eCMS-System kopiert wurde, muss das eCMS es erst installieren, um es nutzen zu können. Dies übernimmt der folgend beschriebene eCMS Installer.

Der Installer führt folgende Dinge aus, für jedes Verzeichnis (und damit jede adressierte Site bzw. Applikation):

• eFDS-Client speichert sich die aktuell installierte Plugin-Version.
• Kopiert die gefundenen Dateien in die korrespondierenden eCMS "live"-Verzeichnis.
• Legt einen Plugin-Konfigurations-Array in den eCMS-Einstellungen an
• Installiert datenbankbasierte Komponenten aus dem data_content-Verzeichnis
• Ruft ggfs. ein Basis-Installer auf und führt das PHP darin aus, sofern vorhanden.
• Ruft ggfs. weitere Installer Update-Scripte auf, sofern vorhanden.
• Importiert Benutzerrechte aus Appright Dateien

Plugin-Funktionen aufrufen

Um die Methoden, die in der eigenen Plugin-Klasse definiert wurden, aufzurufen stehen folgende Arten zur Verfügung.

PHC: Als Funktion im Placeholder-Config

In der PHC-Schreibweise werden die Objekt-Pointer "->" durch doppelte Unterstriche "__" ersetzt.

ecms_plugin_newsletter__receiver_getList

Wie immer, wenn über das eCMS-Object des eCMS-Admins irgendetwas aufgerufen werden soll (innerhalb der aktuell administrierten Site), muss wieder das plugin_siteControl-Objekt vorangestellt werden.

plugin_siteControl__ecms_plugin_newsletter__receiver_getList

PHP: Innerhalb des Source-Codes

Überall, wo das $eCMS-Objekt zur Verfügung steht, kann direkt auf das Plugin zugegriffen werden:

$eCMS-><PLUGIN-NAME>-><METHODE>(...);
 
	// Beispiel (Site / Frontend):
	$eCMS->ecms_plugin_newsletter->receiver_getList( );