(:redirect 'http://docs.studip.de/develop/Entwickler/PluginSchnittstelle':)

Plugin-Aktionen

Über die oben beschriebenen typspezifischen Fähigkeiten hinaus, d.h. insbesondere der Einbettung in vorhandene Seiten in Stud.IP, hat jedes Plugin die Möglichkeit, komplett eigene Seiten - inklusive einer eigenen Navigation - anzubieten. Dazu gibt es in der Plugin-Schnittstelle einen Mechanismus, der vom Nutzer aufgerufene URLs in Methodenaufrufe im Plugin übersetzt, in dieser Beschreibung als "Plugin-Aktionen" bezeichnet. Eine solche Plugin-Aktion ist eine normale (öffentliche) Methode in der Plugin-Klasse, deren Name auf "_action" endet:

class TestPlugin extends StudipPlugin implements SystemPlugin
{
    [...]
    public function delete_action($id)
    {
        [...]
    }
}

Eine Aktion kann Funktionsparameter haben (hier im Beispiel: $id), aber auch Request-Parameter verarbeiten (z.B. beim Absenden eines Formulars).

Das Erstellen von Navigationspunkten für Plugins ist an anderer Stelle beschrieben und funktioniert genauso wie im Stud.IP-Kernsystem. Die zugehörigen URLs führen in der Regel zu bestimmten Aktionen im Plugin, deren Erstellung im folgenden Abschnitt beschrieben ist.

Erstellen von URLs zu Plugin-Aktionen

Damit der Nutzer eine bestimmte Aktion aufrufen kann, muß natürlich das Plugin auch die zugehörige URL kennen. Um URLs zu diesen Plugin-Aktionen erstellen zu können, gibt es zwei Hilfsfunktionen in der Klasse PluginEngine:

getLink($plugin_action, $params = array())

Liefert die URL zu einer Aktion in einem Plugin. Die Aktion wird dabei durch den Klassennamen des Plugins, den Namen der Aktion sowie weitere Funktionsparameter spezifiziert, jeweils getrennt durch einen Schrägstrich ("/"). Der Name der Aktion darf fehlen, dann wird die Standardaktion mit dem Namen "show" in der angegebenen Plugin-Klasse verwendet. Als zweites Argument kann optional noch ein Array mit Request-Parametern (d.h. GET-Parametern) angegeben werden. Beispiel:
(:source lang=php:)

<a href="<?= PluginEngine::getLink("testplugin/delete/$id") ?>"> Eintrag löschen </a>

getURL($plugin_action, $params = array())

Diese Funktion arbeitet genau wie getLink(), liefert aber keinen entity-kodierten Wert zurück, sondern die unkodierte URL. Diese kann dann z.B. für Aufrufe über JavaScript oder Redirects verwendet werden. Beispiel:
(:source lang=php:)

header('Location: ' . $PluginEngine::getURL("testplugin/show"));

Interaktion mit anderen Plugins

Gelegentlich ist es auch wünschenswert, mit anderen Plugins interagieren zu können. Dazu bietet die Klasse PluginEngine ebenfalls eine Reihe von Hilfsfunktionen:

getPlugin($class)

Liefert das Plugin mit dem angegebenen Klassennamen. Falls ein solches Plugin nicht installiert ist oder der Nutzer nicht die notwendigen Rechte besitzt, bekommt man statt der Plugin-Instanz nur einen NULL-Wert.

getPlugins($type, $context = NULL)

Liefert alle Plugins des angegebenen Typs (Name eines Plugin-Interface) als Array. Auch hier werden natürlich nur solche Plugins gefunden, die der aktuelle Nutzer sehen darf.

sendMessage($type, $method, …)

Ruft die angegebene Methode bei allen Plugins eines bestimmten Typs (Name eines Plugin-Interface) auf. Auf den Namen folgende Argumente werden als Methodenparameter an jedes Plugin weitergereicht. Als Resultat bekommt man ein Array mit den Resultaten der einzelnen Methodenaufrufe.

sendMessageWithContext($type, $context, $method, …)

Ruft die angegebene Methode bei allen Plugins eines bestimmten Typs auf, die in einem bestimmten Kontext (z.B. die ID einer Veranstaltung oder Einrichtung) aktiviert sind. Auf den Namen folgende Argumente werden als Methodenparameter an jedes Plugin weitergereicht. Als Resultat bekommt man ein Array mit den Resultaten der einzelnen Methodenaufrufe.

System-Plugins werden auf jeder Seite in Stud.IP geladen (mit Ausnahme von Seiten, die eine komplett andere Darstellung verwenden wie z.B. Druckansichten). Sie können überall im System eigene Navigationspunkte einblenden.

deactivationWarning($context)

Liefert einen Warntext, der ausgegeben wird, bevor das Plugin im angegebenen Kontext deaktiviert wird. Hier kann man z.B. auf eventuellen Datenverlust hinweisen. Die Implementierung der Basisklasse muß dafür überschrieben werden.

Um an bestimmten Stellen in Stud.IP aktiv werden zu können, muss ein Plugin noch eines oder mehrere der Plugin-Interfaces implementieren. In der Version 1.11 stehen dafür die folgenden Schnittstellen bereit:

isActivated($context = NULL)

Prüft, ob das Plugin im angegebenen Kontext (z.B. der aktuellen Veranstaltung) aktiviert ist oder nicht. Falls kein Kontext übergeben wird, ist die aktuell gewählte Veranstaltung gemeint.

Portal-Plugins werden auf der Startseite geladen, auch wenn der Benutzer (noch) nicht angemeldet ist. Sie können eigene Navigationspunkte auf der Login- und Startseite einblenden und einen Informationsblock auf der Startseite anzeigen.

getModuleTitle($module_id, $semester_id = null)

Gibt die Bezeichnung für ein Modul zurück.

getModuleDescription($module_id, $semester_id = null)

Gibt die Kurzbeschreibung für ein Modul zurück.

getModuleInfoNavigation($module_id, $semester_id = null)

Gibt ein Objekt vom Typ Navigation zurück, das Titel, Link und Icon für ein Modul enthalten kann, z.B. zur Darstellung eines Info-Icons.

Dieses Interface enthält die folgenden Methoden:

getInfoTemplate($course_id)

Liefert ein Template, das auf der Kurzinfoseite der Veranstaltung bzw. Einrichtung angezeigt wird. Wenn das Plugin dort nicht angezeigt werden soll, sollte die Methode NULL liefern. Zur Konfiguration des Anzeigebereichs kann das Plugin im Template neben den eigenen Platzhaltern noch einige spezielle Werte setzen (Voreinstellungen in eckigen Klammern):

• title – Anzeigetitel [Name des Plugins]
• icon_url – Plugin-Icon [kein Icon]
• admin_url – Administrations-Link [kein Link]
• admin_title – Beschriftung für den Administrations-Link [Administration]

Das StudienmodulManagementPlugin wird in der Anzeige von Studienbereichen verwendet, um weitere modulespezifische Informationen anzeigen zu können.

getModuleTitle($module_id, $semester_id = null)

TODO

getModuleDescription($module_id, $semester_id = null)

TODO

getModuleInfoNavigation($module_id, $semester_id = null)

TODO

Über die oben beschriebenen typspezifischen Fähigkeiten hinaus hat jedes Plugin die Möglichkeit, eigene Seiten - inklusive einer eigenen Navigation - anzubieten. Das Erstellen von Navigationspunkten für Plugins ist an anderer Stelle beschrieben und funktioniert genauso wie im Stud.IP-Kernsystem.

description (optional)

Eine Kurzbeschreibung des Plugins. Diese wird im System den Nutzern angezeigt, wenn das Plugin zur Aktivierung angeboten wird.

homepage (optional)

Eine URL zur Homepage des Plugins, die weitere Informationen über dieses Plugin enthält. Das kann z.B. die entsprechende Seite über das Plugin im offiziellen Plugin-Repository von Stud.IP sein.

HomepagePlugin: Homepage eines Nutzers

PortalPlugin: Startseite (Portalseite)

StandardPlugin: Veranstaltungen und Einrichtungen

StudienmodulManagementPlugin: Studienmodulsuche

SystemPlugin: systemweite Erweiterungen

Navigation im Plugin

Über die oben beschriebenen typspezifischen Fähigkeiten hinaus hat jedes Plugin die Möglichkeit, eigene Seiten - inklusive einer eigenen Navigation - anzubieten. Das Erstellen von Navigationspunkten für Plugins ist an anderer Stelle beschrieben und funktioniert genauso wie im Stud.IP-Kernsystem.

Frage: Wie bindet man Trails in ein Plugin ein?

Standard-Methoden eines Plugins

HomepagePlugin – Homepage eines Nutzers

Homepage-Plugins werden nur im Homepage-Kontext geladen. Sie können auf der Homepage eigene Navigationspunkte einblenden und einen Informationsblock auf der Übersichtsseite der Homepage anzeigen.

Dieses Interface enthält die folgende Methode:

getHomepageTemplate($user_id)

Liefert ein Template, das auf der Übersichtsseite des Benutzers angezeigt wird. Wenn das Plugin dort nicht angezeigt werden soll, sollte die Methode NULL liefern. Zur Konfiguration des Anzeigebereichs kann das Plugin im Template neben den eigenen Platzhaltern noch einige spezielle Werte setzen (Voreinstellungen in eckigen Klammern):

• title – Anzeigetitel [Name des Plugins]
• icon_url – Plugin-Icon [kein Icon]
• admin_url – Administrations-Link [kein Link]
• admin_title – Beschriftung für den Administrations-Link [Administration]

PortalPlugin – Startseite (Portalseite)

Portal-Plugins werden auf der Startseite geladen, auch wenn der Benutzer (noch) nicht angemeldet ist. Sie können eigene Navigationsseite auf der Login- und Startseite einblenden und einen Informationsblock auf der Startseite anzeigen.

Dieses Interface enthält die folgende Methode:

getPortalTemplate()

Liefert ein Template, das auf der Startseite des Systems angezeigt wird. Wenn das Plugin dort nicht angezeigt werden soll, sollte die Methode NULL liefern. Zur Konfiguration des Anzeigebereichs kann das Plugin im Template neben den eigenen Platzhaltern noch einige spezielle Werte setzen (Voreinstellungen in eckigen Klammern):

• title – Anzeigetitel [Name des Plugins]
• icon_url – Plugin-Icon [kein Icon]
• admin_url – Administrations-Link [kein Link]
• admin_title – Beschriftung für den Administrations-Link [Administration]

StandardPlugin – Veranstaltungen und Einrichtungen

Standard-Plugins werden nur im Veranstaltungs- und Einrichtungs-Kontext geladen (allerdings zur Zeit nicht im Admin-Bereich). Sie können in der Veranstaltung bzw. Einrichtung eigene Navigationspunkte einblenden und ein Icon mit einem Link zum Plugin auf der Seite "Meine Veranstaltungen" anzeigen.

Dieses Interface enthält die folgende Methode:

getIconNavigation($course_id, $last_visit)

Liefert ein Navigationsobjekt für das Icon des Plugins auf der Seite "Meine Veranstaltungen". Wenn das Plugin dort nicht angezeigt werden soll, sollte die Methode NULL liefern. $last_visit ist der Zeitpunkt des letzten Besuchs des Nutzers in der Veranstaltung (bzw. des Plugins). Wenn es seit diesem Zeitpunkt neue oder geänderte Inhalte gibt, sollte dies über ein spezielles Icon dem Nutzer kenntlich gemacht werden.

StudienmodulManagementPlugin – Studienmodulsuche

TODO

Dieses Interface enthält die folgenden Methoden:

TODO

SystemPlugin – systemweite Erweiterungen

System-Plugins werden auf jeder Seite in Stud.IP geladen (mit Ausnahme von Seiten, die eine komplett andere Darstellung verwenden wie z.B. Druckansichten). Sie können überall im System eignene Navigationspunkte einblenden.

Dieses Interface enthält keine Methoden.

• HomepagePlugin – Homepage eines Nutzers

  Dieses Interface enthält die folgende Methode:

  :getHomepageTemplate($user_id): Liefert ein Template, das auf der Übersichtsseite des Benutzers angezeigt wird. Wenn das Plugin dort nicht angezeigt werden soll, sollte die Methode NULL liefern. Zur Konfiguration des Anzeigebereichs kann das Plugin im Template neben den eigenen Platzhaltern noch einige spezielle Werte setzen (Voreinstellungen in eckigen Klammern):

  * title – Anzeigetitel [Name des Plugins]
  * icon_url – Plugin-Icon [kein Icon]
  * admin_url – Administrations-Link [kein Link]
  * admin_title – Beschriftung für den Administrations-Link [Administration]

• PortalPlugin – Startseite (Portalseite)

  Dieses Interface enthält die folgende Methode:

  :getPortalTemplate(): Liefert ein Template, das auf der Startseite des Systems angezeigt wird. Wenn das Plugin dort nicht angezeigt werden soll, sollte die Methode NULL liefern. Zur Konfiguration des Anzeigebereichs kann das Plugin im Template neben den eigenen Platzhaltern noch einige spezielle Werte setzen (Voreinstellungen in eckigen Klammern):

  * title – Anzeigetitel [Name des Plugins]
  * icon_url – Plugin-Icon [kein Icon]
  * admin_url – Administrations-Link [kein Link]
  * admin_title – Beschriftung für den Administrations-Link [Administration]

• StandardPlugin – Veranstaltungen und Einrichtungen
  Standard-Plugins werden nur im Veranstaltungs- und Einrichtungs-Kontext geladen (allerdings zur Zeit nicht im Admin-Bereich). Sie können in der Veranstaltung bzw. Einrichtung eigene Navigationspunkte einblenden und ein Icon mit einem Link zum Plugin auf der Seite "Meine Veranstaltungen" anzeigen.
  Dieses Interface enthält die folgende Methode:

  getIconNavigation($course_id, $last_visit)

  Liefert ein Navigationsobjekt für das Icon des Plugins auf der Seite "Meine Veranstaltungen". Wenn das Plugin dort nicht angezeigt werden soll, sollte die Methode NULL liefern. $last_visit ist der Zeitpunkt des letzten Besuchs des Nutzers in der Veranstaltung (bzw. des Plugins). Wenn es seit diesem Zeitpunkt neue oder geänderte Inhalte gibt, sollte dies über ein spezielles Icon dem Nutzer kenntlich gemacht werden.
• StudienmodulManagementPlugin – Studienmodulsuche
  TODO
  Dieses Interface enthält die folgenden Methoden:
  TODO
• SystemPlugin – systemweite Erweiterungen

  Dieses Interface enthält keine Methoden.

  Homepage-Plugins werden nur im Homepage-Kontext geladen. Sie können auf der Homepage eigene Navigationspunkte einblenden und einen Informationsblock auf der Übersichtsseite der Homepage anzeigen.

  Portal-Plugins werden auf der Startseite geladen, auch wenn der Benutzer (noch) nicht angemeldet ist. Sie können eigene Navigationsseite auf der Login- und Startseite einblenden und einen Informationsblock auf der Startseite anzeigen.

  System-Plugins werden auf jeder Seite in Stud.IP geladen (mit Ausnahme von Seiten, die eine komplett andere Darstellung verwenden wie z.B. Druckansichten). Sie können überall im System eignene Navigationspunkte einblenden.

Darüber hinaus hat jedes Plugin die Möglichkeit, eigene Seiten - inklusive eigener Navigation - anzubieten.

Plugin-Interfaces

Plugin-Klasse

Jedes Plugin muß mindestens eine Klasse enthalten, die die für die Einbettung in die Stud.IP-Umgebung erforderlichen Funktionen des Plugins implementiert. Natürlich können daneben beliebig viele weitere Klassen im Plugin-Paket enthalten sein.

Die Plugin-Klasse muß den im Manifest unter pluginclassname angegebenen Namen haben und von der Klasse StudIPPlugin abgeleitet sein. Außerdem sollte die Klasse mindestens ein Interface implementieren, um sich an bestimmten Stellen in ein bestehendes Stud.IP-System einklinken zu können.

Durch das Ableiten von der Klasse StudIPPlugin besitzt jedes Plugin automatisch eine Reihe von Methoden:

getPluginId()

Liefert die ID des Plugins. Die ID wird intern zur Verwaltung des Plugins verwendet.

getPluginName()

Liefert den im Manifest definierten Namen des Plugins.

getPluginPath()

Liefert einen Dateisystempfad zum Verzeichnis des Plugins. Dies kann z.B. verwendet werden, um Ausgabe-Templates zu laden.

getPluginURL()

Liefert eine (absolute) URL zum Installationsort des Plugins. Wenn man im Plugin auf Style-Sheets oder Bilder verweisen möchte, sollte man diese URL verwenden.

isActivated($context)

Prüft, ob das Plugin im angegebenen Kontext (z.B. der aktuellen Veranstaltung) aktiviert ist oder nicht.

deactivationWarning($context)

Liefert einen Warntext, wenn der ausgegeben wird, bevor das Plugin im angegebenen Kontext deaktiviert wird. Hier kann man z.B. auf eventuellen Datenverlust hinweisen. Die Implementierung der Basisklasse muß dafür überschrieben werden.

perform($unconsumed_path)

Zeigt eine Seite des Plugins an. TODO: Das muß noch genauer beschrieben werden.

Um an bestimmten Stellen in Stud.IP aktiv werden zu können, muß ein Plugin noch eines oder mehrere der Plugin-Interfaces implementieren. In der Version 1.11 stehen dafür die folgenden Schnittstellen bereit:

• HomepagePlugin? – Homepage eines Nutzers
• PortalPlugin? – Startseite (Portalseite)
• StandardPlugin? – Veranstaltungen und Einrichtungen
• StudienmodulManagementPlugin? – Studienmodulsuche
• SystemPlugin? – systemweite Erweiterungen

SQL-Skript zur Erzeugung des Datenbankschemas

Innerhalb eines Plugin-Pakets kann sich ein SQL-Skript befinden, welches mit Semikolon abgeschlossene SQL-Befehle enthält. Dieses SQL-Skript dient dem initialen Anlegen einer oder mehrerer Datenbank-Tabellen für das Plugin. Es wird während der Installation des Plugins von Stud.IP ausgeführt.

SQL-Skript zum Löschen des Datenbankschemas

Analog zu den Regeln für ein SQL-Skript zur Erzeugung des Datenschemas für das Plugin läßt sich auch ein Skript definieren, welches unmittelbar vor dem Entfernen des Plugins aus Stud.IP ausgeführt wird.

In der folgenden Abschnitten werden die verschiedenen Bestandteile eines Plugin-Pakets der Reihe nach erklärt:

Plugin-Manifest

Jedes Plugin-Paket muß ein sogenanntes "Plugin-Manifest" enthalten, in dem wichtige Informationen über das Plugin für die Installation und Verwaltung des Plugins enthalten sind. Das Plugin-Manifest liegt immer im Wurzelverzeichnis des Plugins und hat den Namen plugin.manifest. Es ist eine Textdatei und kann bzw. muß folgende Einträge enthalten:

pluginname

Der Name des Plugins. Dieser dient zur eindeutigen Identifizierung im System (d.h. es können nicht zwei Plugins gleichen Namens installiert werden). Für die Anzeige innerhalb des Systems kann das Plugin selbst auch noch einen anderen Namen liefern.

pluginclassname

Der Name der Plugin-Klasse, also der PHP-Klasse, die von einer der Basisklassen der Pluginschnittstelle abgeleitet wurde. Im Manifest dürfen mehrere solcher Plugin-Klassen angegeben werden, wobei die "Hauptklasse" als erste aufgeführt werden muß. Dies dient dazu, in einem Plugin-Paket mehrere Plugin-Einstiegspunkte zu definieren, z.B. könnte das Plugin einen Einstiegspunkt über die Startseite und auch über die Veranstaltungen definieren.

origin

Der Ursprung des Plugins, üblicherweise der Name des Programmierers oder der Institution oder Gruppe, zu der dieser gehört.

version

Die Version des Plugins. Die Version sollte so gewählt werden, daß ein Vergleich mit der PHP-Funktion version_compare() sinnvoll möglich ist.

dbscheme (optional)

Verweis auf eine Datei mit einem SQL-Skript, die sich innerhalb des Plugin-Pakets befindet. Dieses wird bei der Installation des Plugins ausgeführt (nicht aber bei Updates). Hier können Tabellen und Tabelleninhalte angelegt werden, die das Plugin benötigt. Der Dateiname ist dabei relativ anzugeben.

uninstalldbscheme (optional)

Verweis auf eine Datei mit einem SQL-Skript, die sich innerhalb des Plugin-Pakets befindet. Dieses wird unmittelbar vor dem Entfernen des Plugins ausgeführt. Hier können Tabellen und Tabelleninhalte wieder gelöscht werden, die das Plugin angelegt hat. Der Dateiname ist dabei relativ anzugeben.

updateURL (optional)

Verweis auf eine URL mit Update-Informationen zu diesem Plugin. Wenn dieser Eintrag vorhanden ist, kann das Plugin über die Update-Funktion der Plugin-Verwaltung aktualisiert werden. Fehlt der Eintrag, ist ein automatisches Update nur dann möglich, wenn die zentrale Meta-Datei des Plugin-Repositories Update-Informationen zu diesem Plugin enthält. Wenn der Eintrag updateURL gesetzt ist, muß er auf eine XML-Datei von der folgenden Struktur verweisen:

@]

studipMinVersion (optional)

Angabe der minimalen Stud.IP-Version, mit der dieses Plugin kompatibel ist. Versucht man, es in einer älteren Version zu installieren, erhält man eine entsprechende Fehlermeldung und die Installation schlägt fehlt.

studipMaxVersion (optional)

Angabe der maximalen Stud.IP-Version, mit der dieses Plugin noch lauffähig ist. Versucht man, es in einer neueren Version zu installieren, erhält man eine entsprechende Fehlermeldung und die Installation schlägt fehlt.

Ein Beispiel für ein vollständiges Manifest:

pluginname=Demo
pluginclassname=DemoPlugin
origin=virtUOS
version=1.2
dbscheme=sql/install.sql
uninstalldbscheme=sql/uninstall.sql
updateURL=http://plugins.studip.de/svn/plugins/plugins.xml
studipMinVersion=1.6.0
studipMaxVersion=1.8.5

Die Stud.IP-Plugin-Schnittstelle

(:toc:)

Einleitung

Da jeder Standort, an dem Stud.IP eingesetzt wird, ganz eigene Anforderungen oder Einschränkungen hat, wird mit der Plugin-Schnittstelle ein Mechanismus angeboten, über den man eigene Funktionen zu Stud.IP hinzufügen kann, ohne dabei das Kernsystem anfassen zu müssen. Das Aktualisieren, Entfernen oder Hinzufügen von Komponenten ist dabei im laufenden Betrieb möglich.

Plugins können eigene Seiten im Stud.IP-System anbieten, die an bestimmten Stellen in die Navigationsstruktur eingebunden werden können, z.B. als neuer Reiter in einer Veranstaltung. Darüber hinaus verfügen bestimmte Plugin-Typen auch über die Möglichkeit, auf bestehende Seiten Einfluß zu nehmen und damit z.B. einen eigenen Block auf der Stud.IP-Startseite anzuzeigen.

Was ist ein Stud.IP-Plugin?

Ein Plugin ist eine ZIP-Datei, die eine Beschreibung des Pugins (Name, Version, usw.), den Programmcode und ggf. von Plugin mitgebrachte Ressourcen (Bilder, Stylesheets usw.) enthält. Im einzelnen kann ein Plugin-Paket die folgenden Komponenten enthalten:

• eine Manifest-Datei mit dem Namen plugin.manifest
• mindestens eine PHP-Klasse mit dem Programmcode des Plugins
• optional weitere Dateien mit statischen Inhalten (Bilder, CSS-Stylesheets, JavaScript-Dateien) oder PHP-Bibliotheken
• optional ein SQL-Skript zur Erzeugung des Datenbankschemas für das Plugin
• optional ein SQL-Skript zum Löschen des Datenbankschemas für das Plugin
• optional ein Unterverzeichnis mit dem Namen migrations, welches Migrations-Dateien enthält
• optional ein Unterverzeichnis mit dem Namen locale, das Übersetzungsdateien enthält
• optional ein Unterverzeichnis mit dem Namen templates mit Templates zur Darstellung

Ein Beispiel für die Verzeichnisstruktur in einem Plugin-Paket:

  MyPlugin.class.php
  plugin.manifest
  images/
    icon.png
  migrations/
    1_test.php
    2_foobar.php
  sql/
    install.sql
    uninstall.sql
  stylesheets/
    grid.css
  templates/
    page.php

Bestandteile eines Plugins

Plugin-Update

TODO

<?xml version="1.0" encoding="UTF-8"?>
<plugins>
  <plugin name="Demo">
    <release
      version="1.2"
      url="http://plugins.studip.de/uploads/Plugins/demo-1.2.zip"
      studipMinVersion="1.6.0"
      studipMaxVersion="1.8.5" />
    <release
      version="2.0"
      url="http://plugins.studip.de/uploads/Plugins/demo-2.0.zip"
      studipMinVersion="1.8.0" />
  </plugin>
</plugins>

Stud.IP-Plugin-Schnittstelle

• Materialen aus einem Vortrag über die Plugin-Schnittstelle
• mehr…

• Materialen aus einem Vortrag über die Plugin-Schnittstelle

Als Icon für diese Übersicht wird das Pluginicon (setPluginIconName('iconname')) oder aber, wenn sich im Plugin etwas geändert hat (z.Bsp. neue Wikiseite..) das Icon, das durch setChangeIndicatorIconName('iconname') festgelegt wurde. Ob sich etwas geändert hat, kann das Plugin durch Überschreiben der folgenden Methode festlegen:

Als Icon für diese Übersicht wird das Pluginicon (setPluginiconname('iconname')) oder aber, wenn sich im Plugin etwas geändert hat (z.Bsp. neue Wikiseite..) das Icon, das durch setChangeIndicatorIconName('iconname') festgelegt wurde. Ob sich etwas geändert hat, kann das Plugin durch Überschreiben der folgenden Methode festlegen:

Als Icon für diese Übersicht wird das Pluginicon (setPluginiconname('iconname')) oder aber, wenn sich im Plugin etwas geändert hat (z.Bsp. neue Wikiseite..) das Icon, das durch setChangeIndicatoriconName('iconname') festgelegt wurde. Ob sich etwas geändert hat, kann das Plugin durch Überschreiben der folgenden Methode festlegen:

Portalplugins können je nach Rechtesetzung? auf der Loginseite (Hook #1) und auf der Übersichtsseite (Hook #2) erscheinen.

Jedes Plugin bedient dabei bestimmte Hooks, die in Stud.IP integriert sind. Prinzipiell kann das Hook-Konzept so so zusammengefasst werden: In Stud.IP werden an bestimmten Stellen in bestimmten Seiten Einsprungspunkte definiert. An zentraler Stelle ("Verwaltung von Plugins") kann man Plugins aktivieren, die dann an den entsprechenden Einsprungspunkten instanziiert und aufgerufen werden. Eine Liste der gegenwärtigen Hooks zeigt die entsprechenden Screenshots.

Implementation eines Plugins

Grundsätzlich stehen sechs verschiedene Typen von Plugins zur Verfügung:

• Administrationsplugin
• Coreplugin
• Homepageplugin
• Portalplugin
• Standardplugin
• Systemplugin

Jedes Plugin bedient dabei bestimmte StudipEntwicklung.PluginHooks?, die in Stud.IP integriert sind. Prinzipiell kann das Hook-Konzept so so zusammengefasst werden: In Stud.IP werden an bestimmten Stellen in bestimmten Seiten Einsprungspunkte definiert. An zentraler Stelle ("Verwaltung von Plugins") kann man Plugins aktivieren, die dann an den entsprechenden Einsprungspunkten instanziiert und aufgerufen werden. Eine Liste der gegenwärtigen StudipEntwicklung.PluginHooks? zeigt die entsprechenden Screenshots.

Die Zuordnung von Plugins zu Hooks liefert folgende Tabelle:

Generelle Pluginimplementation

Generell kann und sollte jedes Plugin folgende Methoden überschreiben:

# Diese Methode wird jedesmal aufgerufen,
# wenn ein Plugin instanziiert wird.
void function initialize();

# Diese Methode gibt den lesbaren Namen des Plugins wieder.
String function getPluginname();

# Das Plugin sollte in jedem Fall über eine show-Methode verfügen,
# da diese der Haupteinstiegspunkt für die Plugin-Engine ist.
# Innerhalb dieser show-Methode sollte das Plugin den Request verarbeiten und eine Ausgabe liefern.
void function show();

Ein Beispiel für diese Methoden:

  function initialize() {
    printf("in %s:%s\n", __CLASS__, __FUNCTION__);
  }


  function getPluginname() {
    return _("MyCorePlugin Name");
  }


  function show() {
    printf("in %s:%s\n", __CLASS__, __FUNCTION__);
  }

Zusätzlich sollten im Konstruktor das Plugin-Icon und die Plugin-Navigation gesetzt werden. Ein Beispiel:

  function MyCorePlugin() {
    parent::AbstractStudIPCorePlugin();

    # this plugin wants an own icon
    $this->setPluginiconname("img/plugin.png");

    # navigation
    $navigation =& new PluginNavigation();
    $navigation->setDisplayname(_("MyCorePlugin Navigation"));
    $this->setNavigation($navigation);
  }

Zu jedem Plugin darf auch die Methode showAdministrationPage() überschrieben werden. Leider wird diese nur für Homepage- und Portalplugins tatsächlich verwendet.

Abhängig von der Pluginklasse müssen weitere Anpassungen getätigt werden. Diese werden im folgenden aufgeführt.

Administrationsplugin

Wenn das Administrationsplugin auf der Übersichtsseite als Menüpunkt erscheinen soll (Hook #3), muss im Konstruktor die sogenannte Topnavigation gesetzt werden:

  function MyAdministrationPlugin() {

   [...]

    ## AbstractStudIPAdministrationPlugin specifics

    # top navigation
    $top_navigation =& new PluginNavigation();
    $top_navigation->setDisplayname(_("MyAdministrationPlugin Topnavigation"));

    $top_navigation_submenu_1 =& new PluginNavigation();
    $top_navigation_submenu_1->setDisplayname(_("Submenu 1"));
    $top_navigation_submenu_1->setLinkParam('submenu_1');
    $top_navigation->addSubMenu($top_navigation_submenu_1);

    $top_navigation_submenu_2 =& new PluginNavigation();
    $top_navigation_submenu_2->setDisplayname(_("Submenu 2"));
    $top_navigation_submenu_2->setLinkParam('submenu_2');
    $top_navigation->addSubMenu($top_navigation_submenu_2);

    $this->setTopnavigation($top_navigation);
  }

Für die Anzeige in der Administrationslinkleiste (Hook #4) wird die oben erwähnte Navigation recycelt. Es reicht damit ein entsprechender Aufruf von $this->setNavigation(..);

Coreplugin

Da die Coreplugins keinerlei Hooks bedienen, braucht hier nichts getan werden. Es stellt sich die Frage, warum es überhaupt diese Pluginklasse gibt, da dieselbe Funktionalität ebenso über einfache Bibliotheksdateien gegeben wäre.

Homepageplugin

Das Homepageplugin kann auf der Homepage eines jeden Stud.IP-Benutzers angezeigt werden (Hook #08). Zum einen besteht die Möglichkeit, einen Kasten anzeigen zu lassen, und zum anderen kann ein Reiter auf der eigenen Seite gezeigt werden.

Wichtig ist an dieser Stelle das Setzen einer Navigation (siehe oben $this->setNavigation(..); ! Ohne Navigation wird auch der Kasten nicht angezeigt. Selbiger wird durch Aufruf der zu überschreibenden Methode showOverview() dargestellt. Ein Beispiel:

  function showOverview() {
    printf("in %s:%s\n", __CLASS__, __FUNCTION__);
  }

Interessant ist auch das Überschreiben der Methode showAdministrationPage(), die angezeigt wird, wenn man auf den "Doppelpfeil nach rechts" rechts oben im Kasten des Plugins klickt, während man sich auf der eigenen Homepage befindet.

  function showAdministrationPage() {
    printf("in %s:%s\n", __CLASS__, __FUNCTION__);
  }

Portalplugin

Portalplugins können je nach Rechtesetzung (siehe StudipEntwicklung.PluginRechte?) auf der Loginseite (Hook #1) und auf der Übersichtsseite (Hook #2) erscheinen.

Angezeigt wird der Kasten mit der Methode showOverview, die einen boolschen Parameter besitzt, um anzuzeigen, ob es sich nun um Hook Nº 1 oder Nº 2 handelt. (Dieses Verhalten hätte eigentlich auf zwei Methoden verteilt werden sollen, wie auch die weiteren Ausführungen glaubhaft machen.) Ein Beispiel:

  function showOverview($authorizedview = TRUE) {
    printf("in %s:%s (authorized: %s)\n", __CLASS__, __FUNCTION__,
           (int)$authorizedview);
  }

Um diese Methode aber überhaupt aufgerufen zu bekommen, MÜSSEN folgende Methoden __überschrieben__ werden. Für Hook Nº1 wäre das:

  function hasUnauthorizedView() {
    return TRUE;
  }

und für Hook Nº2:

  function hasAuthorizedView() {
    return TRUE;
  }

Standardmässig liefert die erste Methode FALSE und die zweite TRUE.

Darüber hinaus kann man ebenso wie bei den Homepageplugis noch die Methode showAdministrationPage(), die aufgerufen wird, wenn man eingeloggt auf der Übersichtsseite (Hook Nº2) ist, und dort auf den Doppelpfeil oben rechts im Pluginkasten klickt.

Standardplugin

Das Standardplugin wird bei Einrichtungen und/oder Veranstaltungen angezeigt, wenn das Plugin für diese aktiviert ist (Hook Nº7). Nach der Aktivierung können die notwendigen Änderungen für die Hooks Nº 5, 6 und 9 vorgenommen werden.

Um einen Reiter in der Veranstaltung zu zeigen (Hook Nº 5), ist es notwendig, eine Navigation zu setzen. Um auf der Seite "Meine Veranstaltungen" angzeigt zu werden (Hook Nº 6), muss im Konstruktor folgender Aufruf geschehen: $this->setShownInOverview(TRUE);.

Als Icon für diese Übersicht wird das Pluginicon (setPluginiconname('iconname')) oder aber, wenn sich im Plugin etwas geändert hat (z.Bsp. neue Wikiseite..) das Icon, das durch setChangeindicatoriconname('iconname') festgelegt wurde. Ob sich etwas geändert hat, kann das Plugin durch Überschreiben der folgenden Methode festlegen:

  function hasChanged($lastlogin) {
    return TRUE;
  }

Für den Hook Nº 9 (Score) reicht es, die folgende Methode zu überschreiben:

  function getScore() {
    return 200000;
  }

Theoretisch könnte ein Standardplugin auch eine Liste von Änderungen zurückgeben, aufgerufen wird die folgende Methode leider nie:

  # not used
  function getChangeMessages($lastlogin, $ids) {
    return array();
  }

Systemplugin

Auch Systemplugins können zum Score (Hook Nº 9) beitragen; auch dort muss dieselbe Methode überschrieben werden:

  function getScore() {
    return 200000;
  }

Außerdem dürfen Systemplugins im "Hintergrund" Sachen ausführen (Hook Nº 11). Dabei sind zwei Sachen zu beachten:

1. Die definierten Tasks werden natürlich nicht im Hintergrund ausgeführt. PHP kann das einfach nicht. 2. Die Tasks werden erst relativ spät (nämlich mitten während des Renderns der obersten Iconleiste) ausgeführt. Das schränkt den Nutzen dieses Hooks sehr ein.

Um dennoch Tasks ausführen zu lassen, müssen zwei Methoden überschrieben werden:

  function hasBackgroundTasks() {
    return TRUE;
  }


  function doBackgroundTasks() {
    printf('<script>alert("in %s:%s");</script>', __CLASS__, __FUNCTION__);
  }

Zu guter Letzt dürfen Systemplugins Icons in der obersten Iconleiste hinzufügen (Hook Nº 10). Verwendet wird entweder das Pluginicon oder falls definiert das Icon der Navigation. Ohne Navigation wird allerdings kein Icon angezeigt.