Plugins¶

b1gMail bietet eine umfangreiche Modul-Schnittstelle, die Eingriff in viele Prozesse und Abläufe von b1gMail gestattet und dabei sicherstellt, dass Ihr Plugin auch mit kommenden b1gMail-Versionen bestmöglich kompatibel bleibt. Plugin-Code wird dabei in ein eigenes Plugin-Paket ausgelagert, sodass keine Code-Modifikationen seitens des Benutzers zur Installation des Plugins nötig sind.

Dieses SDK enthält neben dieser Einleitung und Referenz auch Plugin-Beispiele und den b1gMail Plugin Builder (BMPluginBuilder), der die Erstellung von Plugin-Paketen erlaubt, die der Benutzer einfach aus dem Admin-Bereich heraus installieren kann, ohne sein FTP-Programm nutzen zu müssen.

Einführung¶

b1gMail-Plugins bestehen generell aus mindestens einer PHP-Datei, die den Plugin-Code enthält, sowie optional aus Template-Dateien, Grafiken und CSS-/JS-Dateien, die zur Benutzer-/Administrator-Interaktion dienen.

Verzeichnis-Struktur¶

Jede b1gMail-Installation enthält folgende Verzeichnisse, die für die Plugin-Entwicklung relevant sind:

plugins/ - Enthält die PHP-Dateien der Plugins. Bei jedem Aufruf von b1gMail werden alle Plugins aus diesem im b1gMail-Kontext geladen („include“).
plugins/templates/ - Enthält alle mit Plugins ausgelieferten Templates. Das Plugin selbst kann durch von b1gMail zur Verfügung gestellte Funktionen auf diese Templates zugreifen.
plugins/templates/images/ - Enthält alle mit Plugins ausgelieferten Grafik-Ressourcen (i.d.R. PNG-, GIF- und/oder JPG-Dateien).

Ab b1gMail 7.2 stehen die folgenden zusätzlichen Verzeichnisse bereit:

plugins/css/ - Enthält alle mit Plugins ausgelieferten Stylesheets (CSS-Dateien).
plugins/js/ - Enthält alle mit Plugins ausgelieferten JavaScript-Dateien (JS).

Regeln zur Datei-Benennung¶

Um Konflikte zu vermeiden, die durch gleiche Dateinamen zwischen verschiedenen Modulen entstehen, beachten Sie bitte folgende einfache Benennungs-Regeln:

Legen Sie eine interne, eindeutige Abkürzung für Ihr Plugin fest (das PremiumAccount-Modul verwendet z.B. „pacc“ als interne Abkürzung)
Beginnen Sie den Dateinamen jedes Templates Ihres Plugins mit seiner internen Abkürzung, gefolgt von einem Punkt („.“) – verwenden Sie also z.B. „pacc.prefs.tpl“ statt einfach „prefs.tpl“
Beginnen Sie den Dateinamen jeder Bild-, CSS- und JS-Datei Ihres Plugins mit seiner internen Abkürzung, gefolgt von einem Unterstrich („_“) – verwenden Sie also z.B. „pacc_packages.png“ statt einfach „packages.png“

Die Plugin-PHP-Datei¶

Eine Plugin-PHP-Datei kann einen beliebigen Aufbau und beliebige Bestandteile haben, muss aber mindestens eine Plugin-Klasse enthalten, die die durch b1gMail zur Verfügung gestellte Plugin-Basisklasse BMPlugin erweitert. Am Ende der Datei müssen alle Plugin-Klassen, die b1gMail nutzen soll, mit dem Plugin-System registriert werden. Je nachdem, ob das Plugin durch den Administrator aktiviert oder deaktiviert ist, entscheidet b1gMail bei Registrierung der Plugin-Klasse, ob das Plugin verwendet wird oder nicht.

Plugin-Klassen¶

Jede Plugin-Klasse repräsentiert ein eigenes Plugin. Somit kann eine einzige Plugin-PHP-Datei mehrere Plugins enthalten, die auch als mehrere einzelne Plugins im Admin-Bereich von b1gMail angezeigt werden.

Plugin-Klassen sind gewöhnliche PHP-Klassen, die jedoch die Plugin-Basisklasse BMPlugin, die durch b1gMail zur Verfügung gestellt wird, erweitert.

Im Konstruktor einer Plugin-Klasse muss die Plugin-Klasse Meta-Informationen wie Name, Version und Hersteller setzen. Diese Informationen werden z.B. in der Plugin-Verwaltung im Admin-Bereich angezeigt.

Neben dem Konstruktor kann die Plugin-Klasse so genannte Ereignis-Handler enthalten. Ein Ereignis-Handler ist eine Funktion in der Plugin-Klasse, die durch b1gMail aufgerufen wird, sobald ein bestimmtes Ereignis eintritt. In diesem Ereignis-Handler kann das Plugin dann eigenen Code ausführen und so in Prozesse und Abläufe von b1gMail eingreifen und oft auch deren Ausgang beeinflussen. Eine Liste aller Ereignis-Handler, die b1gMail kennt, finden Sie im Kapitel Referenz.

Die Plugin-Basisklasse stellt weiterhin einige Hilf-Funktionen bereit, die Sie aus Ihrem Plugin heraus aufrufen können. Eine Dokumentation zu diesen Funktionen finden Sie ebenfalls im Kapitel Referenz.

Plugin-Klassen-Registrierung¶

Die Registrierung der Plugin-Klassen findet meist am Ende der Plugin-PHP-Datei statt, vor dem abschließenden PHP-End-Tag „?>“.

Zur Registrierung wird die Funktion „registerPlugin“ des Plugin-Managers ($plugins im globalen Variablenraum) aufgerufen, wobei als Parameter der Name der zu registrierenden Plugin-Klasse übergeben wird. Die Instantiierung der Klasse erfolgt durch den Plugin-Manager.

Der folgende Beispiel-Code registriert die Plugin-Klasse „TestPlugin“:

$plugins->registerPlugin('TestPlugin');

Hinweise und Tipps zur Entwicklung¶

Aktivieren Sie während der Plugin-Entwicklung den Debug-Modus von b1gMail, um erweiterte Hinweise bei Fehlern und alle PHP-Fehlermeldungen (auch Notices) zu erhalten. Informationen zur Aktivierung des Debug-Modus finden Sie im Anhang.
Lagern Sie möglichst allen Plugin-PHP-Code in die Plugin-PHP-Datei aus und jeglichen HTML- und JavaScript-Code in die Plugin-Templates.
Versuchen Sie, Ihre Ziele ohne Modifikation von b1gMail-Code zu erreichen. In vielen Fällen ist dies sehr einfach möglich, in anderen Fällen ist ein tieferer Griff in die Trick-Kiste nötig ;-)
Achten Sie darauf, am Ende Ihrer Plugin-Datei nach dem PHP-End-Tag „?>“ keine Leerzeichen oder –zeilen einzufügen, um keine unerwünschte Ausgabe zu erzeugen. Sie können den PHP-End-Tag „?>“ auch weglassen, um das Problem zu vermeiden.
Speichern Sie Ihr Plugin, sofern möglich, im ISO-889-15-Zeichensatz und lassen Sie Ihre Sprachvariablen dann mit dem Code aus dem vorherigen Kapitel in das von b1gMail verwendete Charset konvertieren, um Kompatibilität mit älteren b1gMail-Versionen zu erhalten.
Verteilen Sie Ihr Plugin als b1gMail-Plugin-Paket, um eine einfache und vertraute Installation zu ermöglichen. So reduzieren Sie auch Ihren Support-Aufwand.

Plugin-Verteilung¶

Die Verteilung von Plugins kann auf zwei verschiedene Versionen erfolgen:

Durch Weitergabe aller Plugin-Dateien, z.B. in einem ZIP-Archiv. Der Benutzer benötigt zur Installation dann jedoch Zugriff auf seinen Webspace (z.B. per FTP) und die Deinstallation gestaltet sich recht kompliziert.
Durch Erstellung eines b1gMail-Plugin-Pakets (.bmplugin-Datei). Ein solches Paket enthält alle Dateien Ihres Plugins und kann mit einem Klick im b1gMail-Adminbereich installiert werden, ohne dass dazu Zugriff auf den Webspace nötig ist. Das Plugin-Paket kann genau so einfach wieder deinstalliert werden.

Zur Erstellung von b1gMail-Plugin-Paketen lesen Sie bitte das folgende Kapitel.

Erstellung von b1gMail-Plugin-Paketen¶

Zur Erstellung von b1gMail-Plugin-Paketen (.bmplugin-Dateien) benötigen Sie das Tool „BMPluginBuilder“, das im b1gMail-Plugin-SDK enthalten ist.

Das Hauptfenster besteht aus zwei Register-Karten: „Meta-Informationen“ enthält alle Informationen, die während der Installation des Plugins angezeigt werden sowie eine Liste aller Plugin-Klassen, die automatisch aktiviert werden sollen; „Dateien“ enthält die Plugin-Dateien, die installiert werden sollen.

Meta-Informationen¶

Die Register-Karte „Meta-Informationen“ enthält folgende Einstellungs-Möglichkeiten:

Plugin-Paket-Name – Der Name/Titel des Plugin-Pakets
Plugin-Paket-Version – Die Versionsnummer des Plugin-Pakets
Entwickelt für b1gMail-Version – Die b1gMail-Version, für die das Plugin entwickelt wurde, z.B. „7.0.0-Beta3“ oder „7.0.0“
Hersteller – Der Name des Plugin-Herstellers
Hersteller-Webseite – URL der Webseite des Plugin-Herstellers, z.B. „http://www.example.com/“
Hersteller-E-Mail – E-Mail-Adresse des Plugin-Herstellers
Plugin-Klassen – Eine Liste der Namen aller Plugin-Klassen, die mit dem Plugin-Paket installiert und aktiviert werden sollen

Tipp: Nachdem Sie Plugin-PHP-Dateien unter „Dateien“ hinzugefügt haben, können Sie die Plugin-Klassen-Namen per Klick auf das Lupen-Symbol unten rechts neben der Plugin-Klassen-Liste auch automatisch vom Plugin-Builder erkennen lassen.

Dateien¶

Die Register-Karte „Dateien“ enthält eine Liste aller Dateien, die mit dem Plugin-Paket installiert werden sollen.

Folgende Datei-Typen können zur Liste hinzugefügt werden:

PHP-Dateien (*.php) werden in das Verzeichnis plugins/ installiert
Template-Dateien (*.tpl) werden in das Verzeichnis plugins/templates/ installiert
Bild-Dateien (*.gif, *.jpg, *.png) werden in das Verzeichnis plugins/templates/images/ installiert
Stylesheets (*.css) werden in das Verzeichnis plugins/templates/css/ installiert
JavaScripts (*.js) werden in das Verzeichnis plugins/templates/js/ installiert

Per Klick auf den Button „+“ können Sie Dateien hinzufügen, ein Klick auf den Button „-“ entfernt alle in der Liste markierten Dateien.

Tipp: Sie können Dateien auch per Drag&Drop aus dem Explorer/Finder direkt in die Datei-Liste ziehen.

Erstellen¶

Nach Angabe aller benötigen Informationen können Sie das Plugin-Paket per Klick auf „Erstellen“ in der Symbolleiste erstellen lassen. Sie können daraufhin auswählen, wo das Plugin-Paket gespeichert werden soll.

Das generierte Plugin-Paket kann dann verteilt werden und mit Hilfe der Register-Karte „Installieren“ im b1gMail-Adminbereich unter „Plugins“ installiert werden.

Projekte¶

Der Plugin-Builder bietet Ihnen die Möglichkeit, Ihre Eingaben als Projekt-Datei zu speichern. Diese können Sie dann später erneut öffnen, um einfach neue Versionen Ihres Plugins in eine .bmplugin-Datei zu verpacken.

Über die Schaltflächen „Neu“, „Öffnen“ und „Speichern“ können Sie Ihre Projekte verwalten.

In der .bmproj-Projektdatei werden neben den Meta-Informationen auch die Verweise auf im Projekt enthaltene Dateien gespeichert. Dabei speichert der Plugin-Builder nur den Ort und nicht den Inhalt der Datei, sodass Sie die Dateien nach Änderungen nicht erneut hinzufügen müssen.

Referenz¶

Eigenschaften¶

Der Konstruktor einer Plugin-Klasse kann und sollte die folgenden Eigenschaften setzen:

titel – Titel des Plugins
autor – Autor des Plugins
web – Web-Seite des Autors bzw. des Plugins, z.B. http://www.firma.xy
mail – E-Mail-Adresse des Autors
version – Versionsnummer des Plugins
designedfor – Versionsnummer der für das Plugin empfohlenen b1gMail-Version
type – BMPLUGIN_DEFAULT (Konstante) für ein Plugin ohne Widget-Funktionalitäten, BMPLUGIN_WIDGET (Konstante) für ein Plugin mit Widget-Funktionalitäten

Folgende Eigenschaften können gesetzt werden, um die Funktionen bzw. Fähigkeiten des Plugins zu kennzeichnen:

admin_pages – „true“, wenn das Plugin im Adminbereich konfigurierbar sein soll
admin_page_title – Titel des Plugins im Menü des Adminbereichs
widgetTitle – Titel des Widgets (nur bei Widgets)
widgetTemplate – Template-Datei des Widgets innerhalb des plugins/templates/-Ordners (nur bei Widgets)
widgetIcon – Symbol des Widgets (16x16) innerhalb des Verzeichnisses plugins/templates/images/ (nur bei Widgets, verfügbar ab b1gMail 7.2)
widgetPrefs – Gibt an, ob das Widget eine Einstellungs-Seite (true) hat, oder nicht (false) (nur bei Widgets, verfügbar ab b1gMail 7.2)
widgetPrefsWidth – Gibt die Breite der Widget-Einstellungs-Seite in Pixel an (nur bei Widgets mit Einstellungs-Seite, verfügbar ab b1gMail 7.2)
widgetPrefsHeight – Gibt die Höhe der Widget-Einstellungs-Seite in Pixel an (nur bei Widgets mit Einstellungs-Seite, verfügbar ab b1gMail 7.2)
update_url – URL zu einem Update-Service, bei dem auf neue Versionen des Plugins geprüft werden kann. Bei auf my.b1gMail.com veröffentlichten Plugins kann hier der my.b1gMail.com-Update-Service angegeben werden, um den Benutzer auf neue Updates aufmerksam zu machen: http://my.b1gmail.com/update_service/ Hinweis: Eine Prüfung auf Updates funktioniert dann erst, sobald das Plugin auf my.b1gMail.com veröffentlicht und freigeschaltet wurde.

Folgende Eigenschaften sollten nur gelesen werden:

internal_name – Internet Name des Plugins, d.h. der Name des Plugin-Klasse
installed – „true“, falls das Plugin installiert und aktiviert ist

[...]