eCMS Software-Development-Kit (SDK)

Ob es eine Icon-Sammlung, eine eCMS-Funktionserweiterung oder das Kapseln von eigenen Site-Erweiterungen ist - mit eigenen Plugins ist dies alles auf einfache Art und Weise möglich. Dieser Artikel beschreibt, welche Vorüberlegungen zu machen sind und enthält Anleitungen und Tipps zum konkreten Erstellen von Plugins.

Einführung und Grundlagen

Mit Hilfe des Software-Development-Kits (SDK) ist es möglich eigene Plugins zu erstellen und zu verwalten. Die Entwicklung von Plugins wird dadurch wesentlich schneller, komfortabler und vor allem fehlersicherer.

Zum grundsätzlichen Verständnis, was sich hinter einem Plugin verbirgt, empfehlen wir zuerst den Artikel Plugins - Die Grundlagen zu lesen.

Short Facts

Das SDK kann ...

  • kann mehrere Plugins gleichzeitig "under development" haben.
  • die für Plugins typische (leere) Verzeichnis-Strukturen anlegen
  • notwendige Import-Files für Komponenten wie bspw. Pages, Layouts, usw. erzeugen
  • Klassen-Files auf Template-Basis erzeugen (siehe Plugin Types)
  • Files komfortabel zwischen Ausführungsverzeichnis und Plugin-Source-Directory hin- und herkopieren.
  • Plugins zum exportieren zippen
  • gezippte Plugins zum Stagen importieren

 

Installation

Die Installation lässt sich einfach über das Backend des eCMS unter  Administration > Plugins durchführen.

 

Workflow der SDK-Pluginerstellung

  • eCMS SDK im eCMS-Backend unter Extra > Software-Development-Kit (SDK) aufrufen
  • ggf. Plugin-Typen anlegen
  • ggf. unter Beachtung der Layer-Definition, ein neues Plugin zu einem Plugin-Typen anlegen (Name des Plugins sollte gut gewählt sein, da späteres Ändern teilweise recht aufwendig werden kann!)
  • Wenn nötig: Erstellen/Befüllen der Plugin-Klasse (mit eigenen Methoden) in eigener Entwicklungsumgebung
  • Erstellen der eCMS-Komponenten (Seiten, Layoute, Formate, Menüs, Mediabase-Inhalte, Content, usw.) über das eCMS Backend und Zuweisung zum eigenen Plugin
  • Mit dem SDK alle Datenbankseitigen Komponenten in das Plugin zurückspielen lassen (ReverseBuild).
  • Plugin als Zip packen und downloaden
  • ggf. gezipptes Plugin stagen / auf andere(s) eCMS-System(e) einspielen

 

Plugin-Typen

Mit Hilfe von Plugin-Typen lassen sich Plugins klassifizieren. Es ist als eine Art "Namespace" zu sehen. Ein Plugin-Typ wird als Prefix vor ein Plugin-Namen gesetzt. In einem Plugin-Typen können klassenspezifische Templates angegeben werden. Wenn über das SDK ein Plugin zum Plugin-Typen erstellt und eine Plugin-Klasse angelegt wird, so wird das Template in diese Plugin-Klasse eingefügt.

 

Layer-Definition

Dieser Abschnitt sollte grundlegend beachtet werden.

Im eCMS gibt es eine Layer-Definition, die wesentlich für das spätere Einspielen und Stagen von Plugins ist. Der einzelnen Layer sollte man sich daher schon bei der Pluginerstellung bewusst sein, vor allem wenn man Plugins in Entwicklungsumgebungen (Developmentservern) erstellt und auf Produktivsystemen installieren will (auf denen aber auch Änderungen im Livebetrieb stattfinden können).

Als praktikabel hat es sich erwiesen, die Komponenten der Layer-0 und Layer-1 in ein Plugin zusammenzufassen und die Layer-2 Komponenten in ein zusätzliches Erweiterung/Integration Plugin auszugliedern. Der Vorteil dieser Lösung ist, dass das Plugin mit den Layer-0 und Layer-1 Komponenten weiterhin gestaded werden kann, ohne durch die Layer-2 Komponenten blockiert zu werden.

Grundsätzlich werden drei Layer unterschieden:

Layer-0

Der Layer-0 umfasst in einem Plugin alle Komponenten, die bei jedem Einspielen/Stagen überschrieben und geupdated werden (unabhängig davon, ob tatsächlich eine Änderung vorgenommen wurde). Diese Komponenten umfassen im wesentlichen alle physischen Dateien, die auf der Festplatte gespeichert werden, also u.a.:

  • Core-Komponenten, wie PHP (Plugin)-Klasse(n)
  • Formate
  • Bilder/Icons
  • Javascript-Dateien
  • CSS-Dateien
  • LibSnippet Scripte
  • Frontend-Scripte z.B. aus dem im "bin"-Verzeichnis

Layer-1

Der Layer-1 umfasst einige datenbankseitig gespeicherten Komponenten, die beim Einspielen/Stagen so lange überschrieben/geupdated werden, wie sie auf dem Zielserver nicht manuell geändert wurden. Dabei wird meist eine Installationszeit mitgespeichert, um die Update-Prüfung zu gewährleisten. Dies betrifft:

  • Inhaltstypen
  • Attribute
  • Artikel des Redaktionssystems (Textbausteine, Produktdaten, sonstige Artikel von anderen Inhaltstypen)
  • Layoute
  • Mediabase-Datensätze (hierbei nur die in der Datenbank gespeicherten Daten, die Dateien selbst fallen in Layer-0)
  • Daemon-Jobs
  • LibKomponenten-Datensätze (hierbei nur die in der Datenbank gespeicherten Daten, die Dateien (Formate, PHP Klassen, etc.) selbst fallen in Layer-0)

Layer-2

Als Layer-2 werden alle datenbankseitig gespeicherten Komponenten betrachten, die sich schlecht oder gar nicht aktualisieren lassen. Da die meisten dieser Komponenten zumeist auch immer auf Produktivsystem angepasst und verändert werden können, sollten Komponenten des Layer-2 meistens nur einmal installiert werden und nicht geupdated werden. Jedes Update würde die Daten entsprechend überschreiben. Komponten dieses Layers sind:

  • Macro-Layoute
  • Macro-Formate
  • Seiten
  • Platzhalterkonfigurationen
  • Menüs
  • Seiten-Aliase
  • Kataloge und Kategorien des Redaktionssystems

 

Plugin anlegen

Für die Erstellung eines Plugins über das SDK gibt es einige Optionen

Typ und Name des Plugins

Bei der Neuanlage eines Plugins muss zunächst der Plugin-Typ ausgewählt werden und ein Name vergeben werden. Dieser sollte klein geschrieben werden und keine Sonderzeichen und Umlaute aufweisen. Der Name sollte so gewählt werden, dass aus ihm ungefähr abzulesen ist, was das Plugin eigentlich tut.

Beispiel:
Wenn zum Beispiel eine einfache Icon-Sammlung als Plugin zu einer Website-X erzeugt werden soll, könnte der Plugin-Name beispielsweise lib_icons_websitex heißen. Das Plugin zur Website-X mit den eCMS-Komponenten könnte dann z.B. einfach als plugin_websitex benannt werden.
Tipp:
Bei der Pluginerstellung sollte man auch die Layer-Definition berücksichtigen. Es empfiehlt sich daher, verschiedene Plugins anzulegen, die den Layern gerecht wird. Layer-0 und Layer-1 Komponenten können daher zumeist innerhalb eines Plugins gespeichert werden. Layer-2 Komponenten sollten in ein eigenes Plugin integriert werden, um Update-Überschreibungen z.B. auf Produktivsystemen zu verhindern.

Plugin-Klasse

Nach der Namensvergabe kann definiert werden, ob im dem Plugin eine PHP Plugin-Klasse und ein Basis-Installer angelegt werden soll. Die Plugin-Klasse nutzt dabei ggf. das hinterlegte Template aus der Plugin-Typ Definition. Diese ist notwendig, wenn eigene Methoden z.B. zu Datenbank-Abfragen erstellt werden sollen oder das Plugin später über Parameter konfiguriert werden kann.

Der Name der Plugin-Klasse ist immer identisch zum Namen des Plugins und seines Plugin-Types - also nach folgendem Schema:

  1. <Plugin-Typ>_<Plugin-Name>.class.php

Base-Installer

Der Basis-Installer ist ein PHP-Script welches beim erstmaligen Installationsprozess des Plugins aufgerufen wird. In ihm sollten dabei dann z.B. Datenbankspalten erzeugt werden. Für spätere Updates des Plugins können auch Update-Scripte hinterlegt werden. Der Basis-Installer wird im Verzeichnis installer abgelegt.

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

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

Zukünftige Update-Scripte, nach dem Schema 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.

Beim späteren Einspielen/Update eines Plugins 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 vorhandenen Update-Scripte, nach dem Basis-Installer ausgeführt.

Ressource-Verzeichnisse

Nun sollten die Verzeichnisse definiert werden, die für das Plugin relevant sind. Dabei gilt, dass nur die Inhalte in die entsprechenden Verzeichnisse später auch im ReverseBuild zurückgespielt werden, die über das SDK angelegt wurden. Bei den Verzeichnissen unterscheidet man in:

  • core
  • site
  • ecms_3_admin
  • dev
  • weitere App Verzeichnisse

Im Core-Verzeichnis werden alle PHP Klassen gespeichert, die grundlegende Methoden und Core-Logik enthalten - hierzu zählt z.B. die Plugin-Klasse. Wird diese bereits im Schritt davor aktiviert, so wird das Core-Verzeichnis automatisch angelegt. Alle Verzeichnisse und Dateien aus diesem Verzeichnis werden bei der Plugin-Installation (oder Recopy-Action) ins core-Verzeichnis kopiert.

Es kann genutzt werden um neue Core-Komponenten, z.B. "my_core_lib/my_core_lib.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.

Die anderen Angaben beziehen sich auf Verzeichnisse im install_res-Verzeichnis eines Plugins. Hier 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.

Zusätzlich steht die Option weitere App-Verzeichnisse erstellen zur Verfügung. Hierüber können weitere Verzeichnisse für die Applikationen angelegt werden, wofür folgende Informationen nützlich sein können:

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.

Beispiele:
  • ecs_5_admin
    Dieses Verzeichnis erlaubt den Zugriff auf den eCommerceSuite 5 Admin (Applikation "eCS 5 admin") - also das Backend der eCommerceSuite.

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.

Plugin Verzeichnisstruktur

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

  • <plugin-typ>_<plugin-name>
    • core

      Die core-Komponenten des Plugins.

      • my_namespace
        • my_model_abc.class.php
      • <plugin-typ>_<plugin-name>.class.php
    • install_res
      • site

        Die Inhalte für die aktive Site bei der Plugin Installation.

        • data_content
          • ecms_cdb_ctrecords__site_i18n_content__DE.csv
          • ecms_layout_cdb_example_box.json
        • dir_inc
          • lib_class
            • my_plugin_static_format_service.class.php
          • lib_formatobject
            • my_plugin_product_list_slim.class.php
        • dir_www
          • files/

            Mediabase-Inhalte und Website-Assets.

            • css
              • plugin_myplug.css
            • js
              • plugin_myplug.js
            • ico
              • plugin_myicon.png
      • ecms_3_admin

        Die Inhalte für den eCMS-Admin (Backend Seiten, Menüs, etc.).

        • data_content/
        • dir_inc/
        • dir_www/
  • installer/
    • base_install.inc.php
    • update_201406011200.inc.php

      Update vom 1.6.2014, 12:00 Uhr.

  • ecms_3_admin_apprights.csv

    Benutzerrechte des Plugins für den eCMS 3 Admin.

 

Übersicht der SDK-Plugins

Die mit dem SDK angelegten Plugins können im SDK über die Liste der Plugins verwaltet werden. Diese erreichen Sie im eCMS Backend unter Extra > Software-Development-Kit (SDK) > Projekt Liste. Jedes Plugin kann über die Liste zum Bearbeiten geöffnet werden (Bearbeiten-Icon), falls vorhanden kann die Plugin-Konfiguration geöffnet werden (Icon für Plugin-Konfiguration-Bearbeiten). Über den Namen des Plugins gelangt man via Klick auf die Aktionen-Übersicht, die zu einem Plugin zur Verfügung stehen.

 

Plugin-Aktionen im SDK

Auf der Seite mit den Plugin-Aktionen im SDK stehen vielfältige Optionen bereit, die für die Entwicklung eines Plugins hilfreich und teilweise essentiell sind.

Recopy

Mit der Recopy-Aktion werden alle dateibasierten Komponenten (wie PHP-Klassen (Core, Formate, etc.), Javascript-Libraries, CSS-Dateien oder Mediabase-Inhalte) des Plugins in die entsprechend hinterlegten eCMS Verzeichnisse kopiert. Dabei werden im Normalfall nur alle Dateien kopiert, die neuer sind als die Zieldatei (also vermutlich verändert wurden).

Die Recopy-Aktion ist auch der 1. Schritt einer Plugin-Installation. Mehr zum Thema Plugin-Installation erfahren Sie unter Plugins - Technische Details.

Bei der Recopy-Aktion gibt es zwei Optionen:

  • Force Recopy
    Hierbei werden alle dateibasierten Komponenten aus dem Plugin kopiert und nicht bloß die neuen (vermmutlich veränderten Dateien)
  • Development Option
    Alle Dateien des core-Verzeichnisses werden nicht direkt kopiert, sondern nur mit Hilfe einer php include-Anweisung auf die Datei im Plugin-Verzeichnis eingebunden. Dies erlaubt auf Entwicklungssystemen, die Veränderung einer Core-Komponente im Plugin-Verzeichnis des Entwicklungssystem (z.B. Eclipse) und die direkte Nutzung im eCMS ohne für jede Änderung der Core-Komponente die Recopy-Option des SDK ausführen zu müssen

Data-Content importieren

Der Data-Content-Import importiert die datenbankbasierten Komponenten (wie Seiten, Layoute, Textbausteine, etc.) eines Plugin in die eCMS Datenbank. Diese Komponenten sind in den "data_content" Verzeichnissen hinterlegt. Für Layer-1 Komponenten gilt dabei im Normalfall, dass diese nicht überschrieben werden, sollten sie bereits manuell geändert worden sein.

Die Data-Content-Import ist der 2. Schritt einer Plugin-Installation. Mehr zum Thema Plugin-Installation erfahren Sie unter Plugins - Technische Details.

Bei der Data-Content importieren Aktion gibt es eine zusätzliche Option:

  • Force Data-Content-Import
    Hierbei wird beim Import immer ein "Create-Update" ausgeführt. Das bedeutet, dass sämtliche manuelle Änderungen (auch von Layer-1 Komponenten) überschrieben werden.

Installation ausführen

Die Installation auszuführen ist auch der 3. Schritt einer Plugin-Installation. Mehr zum Thema Plugin-Installation erfahren Sie unter Plugins - Technische Details.

Bei dieser Aktion gibt es zwei Optionen:

  • Base-Installer und alle Update-Scripte ausführen
    Hierbei werden - wie der Name der Options schon sagt - sowohl der Basis-Installer als auch alle verfügbaren Update-Scripte installiert.
  • Update-Installer nach Installationszeit ausführen
    Hierüber können Update-Scripte gezielt ausgeführt werden. Entweder alle nach der - vorbelegten - Installationszeit oder durch Angabe einer "eigenen" Installationszeit, um z.B. gezielt nur das letzte Update-Script auszuführen.

ReverseBuild

Das ReverseBuild erlaubt das zurückspielen aller datenbankseitigen Komponenten in das eigentlich Plugin. Diese Option wird im Normalfall ausgeführt, wenn Änderungen über das eCMS Backend gemacht wurden - beispielsweise Änderungen an Platzhalterkonfigurationen, Artikeln des Redaktionssystems wie Textbausteinen oder Menüeinträge. Dabei werden für die datenbankbasierten Komponenten die Installationsdateien (hauptsächlich json-Dateien) erzeugt und im data_content - Unterverzeichnis, des entsprechenden Applikationsverzeichnisses abgelegt.

Auch wenn Änderungen eines Plugins in unterschiedlichen Applikationen vorgenommen wurden, reicht ein ReverseBuild um alle Inhalte zurückspielen zu können. Dabei ist die im eCMS Backend ausgewählte Site entscheidend.

Beispiel:
Es gibt ein Plugin, welche grundlegend im Shop-Frontend benötigt wird, aber auch Textbausteine im eCMS Backend hinterlegen muss (z.B. für Textbausteine eines Format-Konfigurationsdialoges). Dafür wurden im Plugin selbst die Verzeichnisse ecms_3_admin und site angelegt. Für das ReverseBuild muss nun im eCMS Backend auf die Shop-Frontend-Site gewechselt werden. Beim nun durchgeführten ReverseBuild werden nun nicht nur Komponenten der Shop-Frontend-Site (die dem Plugin zugeordnet wurden) zurückgespielt ( und im data_content-Unterverzeichnis des site-Verzeichnisses abgelegt), sondern auch die dem Plugin zugeordneten Textbausteine der eCMS Backend-Site erkannt und im data_content-Unterverzeichnis des Verzeichnisses ecms_3_admin abgelegt.

Zip erstellen

Mit dieser Aktionen kann das fertige (durch ReverseBuild zurückgespielte) Plugin als ZIP-Datei gepackt und heruntergeladen werden. Mit diesen ZIP kann das Plugin in anderen eCMS-Installationen installiert werden.

Mehr zum Thema Plugin-Installation erfahren Sie unter Plugins - Technische Details.

 

Formate scannen und als LibKomponenten speichern

Damit Formate über das eCMS Backend editierbar und auch beispielsweise in einer Shop-Frontend Platzhalterkonfiguration über den Formate-Finder auffindbar sind, müssen sie als sogenannte LibKomponente gespeichert werden. Damit werden wichtige Formatinformationen in einer Datenbank abgelegt, was das Durchsuchen (im Formate-Finder oder über Vorschlagssuchen) erleichtert.

Im SDK ist von der Seite der Plugin-Aktionen auch separat der Formate-Scan aufrufbar. Auf dieser Seite werden alle Formate(-Dateien) die sich physisch im Plugin-Verzeichnis befinden aufgelistet und können über die Schaltflächen am Ende der Liste in die LibKomponenten gespeichert werden.