Die API

Beitragsseiten

Wir sind sehr dazu bemüht, die Galerie so zu gestalten, dass sie universell einsetzbar ist. Dazu gehört auch die Möglichkeit der Integration von anderen Komponenten, Modulen und Plugins, die nicht von uns stammen (wie zum Beispiel dem Community Builder, AlphaUserPoints oder JComments, um nur sehr wenige zu nennen).
Für einige haben wir bereits zusätzliche Add-Ons geschrieben, die eine Verbindung zwischen der jeweiligen 3rd-Party Erweiterung und der JoomGallery herstellen. Ihr findet sie in unseren Downloads und außerdem hier eine kleine Übersichtsseite dazu.

Da wir aber selbstverständlich nicht für sämtliche Erweiterungen, die es gibt, Add-Ons für die JoomGallery anbieten können oder jemand von euch ein ganz spezielles Vorhaben hat, bietet die JoomGallery eine riesige API, die Ihr verwenden könnt. Dieser Artikel ist also vor allem für die Entwickler unter Euch interessant.

Falls Ihr euch dazu entschlossen habt, eine eigene Erweiterung für die JoomGallery zu schreiben, findet Ihr im Folgenden eine ausführliche Beschreibung der Galerie-API.
Das Studieren bereits existierender Erweiterungen kann Euch bei Eurer eigenen Entwicklung ebenfalls sehr weiterhelfen.

Die API der JoomGallery lässt sich in 3 große Bereiche einteilen:

  • Das Interface
    Das Interface stellt - einmal in Eure Erweiterung inkludiert - viele nützliche Funktionen zur Verfügung, um mit der Galerie zu "kommunizieren" und vor allem Informationen abzufragen oder Bilder auszugeben.
  • Die Modulpositionen
    Innerhalb der Galerie sind bereits mehrere Modulpositionen eingebaut, die Ihr verwendet könnt wie die Modulpositionen Eures Templates. Zusätzlich können sie sehr individuell geladen werden.
  • Die Plugin-Events
    Bei den verschiedenen Aufgaben, die die Galerie erledigt oder während der Ausgabe der Ansichten werden unterschiedliche Events ausgelöst, auf die Eure Plugins reagieren und die Galerie beeinflussen können.

Das Interface

Um das Interface verwenden zu können, muss es zuvor in eure Erweiterung eingebunden und instanziert werden. Dies geschieht durch folgenden Codeabschnitt:

$file = JPATH_ROOT.DS.'components'.DS.'com_joomgallery'.DS.'interface.php';
if(!file_exists($file))
{
JError::raiseError(500, 'JoomGallery seems not to be installed');
}
else
{
require_once $file;
$interface = new JoomInterface();
}

Die Variable '$interface' enthält nun das Interface-Objekt der Galerie (sofern die JoomGallery installiert ist).

Jetzt könnt Ihr die Funktionen, die das Interface zur Verfügung stellt, in Eurer Erweiterung verwenden.
Ein Aufruf sieht zum Beispiel so aus:

$interface->getPageHeader();

oder falls etwas von der Funktion zurückgegeben wird, so:

$images = $interface->getPicsOfUser($userid);

Die Funktion 'getPageHeader' ist wichtig, falls Eure Erweiterung Bilder oder ähnliches ausgeben soll und ihr die Styledefinitionen der Galerie verwenden wollt, da sie die CSS-Dateien der JoomGallery einbindet.

Am besten Ihr seht euch die Interface-Datei einmal selbst an ('components/com_joomgallery/interface.php'), zu jeder Funktion darin sind Erklärungen im jeweiligen Header dazu vorhanden, was die Funktion macht, was sie eventuell zurückgibt und welche Parameter ihr übergeben werden müssen.

Hier sei nur noch die Funktion 'addConfig()' erwähnt, mit der Ihr Einstellungen des Interfaces vornehmen könnt, wie zum Beispiel mit welcher Art ein Bild geöffnet werden soll:

$interface->addConfig('openimage', 6);

Die Zahl 6 steht hier für die Slimbox, weitere Zuordnungen findet Ihr in folgender Liste:

0 => Normale Ansicht
1 => Neues Fenster
2 => JavaScript Fenster
3 => DHTML - Container
5 => Thickbox3
6 => Slimbox
12 => zusätzlich installierte Plugins

Falls 'openimage' nicht gesetzt wird, verwendet das Interface die entsprechende Einstellung des Konfigurationsmanagers der Galerie ('Öffnen der Detailansicht' im Tab 'Kategorie-Ansicht' -> 'Generelle Einstellungen').

Weitere Optionen sind zum Beispiel 'group', 'limit' oder 'type'.


Die Modulpositionen

Für die Modulpositionen der Galerie gibt es einen eigenen Artikel in der Dokumentation. Ihr findet ihn hier: Die Modulpositionen.

Ihr könnt mit Hilfe von Template-Overrides an beliebigen Stellen innerhalb der Galerie auch eigene Modulpositionen einfügen. Verwendet dafür bitte folgenden Code:

<?php $this->loadModules('positionsname'); ?>


Dabei könnt ihr die Modulpositionen dann wie die in der Galerie bereits integrierten Positionen mit Suffixen verwenden. Beachtet bitte, dass ihr das Präfix 'jg_' im Modulmanager auch bei diesen Positionen mit eingeben müsst.


Die Plugin-Events

Entwickler unter Euch wissen, dass es in Joomla verschiedene Plugin-Typen gibt, wie zum Beispiel Content-Plugins, User-Plugins oder System-Plugins.

Für diese Typen könnt ihr natürlich auch JoomGallery-bezogene Plugins schreiben, die zum Beispiel das Interface verwenden, wie es beim Content-Plugin 'JoomPlu' der Fall ist.

In diesem Abschnitt der API-Dokumentation soll es aber um die Plugin-Events gehen, die ausschließlich von der JoomGallery und eventuell deren Erweiterungen ausgelöst werden. Die JoomGallery greift nämlich zusätzlich noch auf einen weiteren Plugin-Typ zu, der sich 'joomgallery' nennt.

Falls Ihr also ein Plugin entwickeln wollt, das die JoomGallery beeinflussen kann, würde das 'install'-Element der entsprechenden XML-Installationsdatei folgendermaßen aussehen:

<install version="1.5" type="plugin" group="joomgallery" method="upgrade" />

Für den allgemeinen Aufbau eines Plugins seht Ihr Euch am besten mal eines der Example-Plugins an, die mit Joomla mitgeliefert werden.

Es folgt eine Liste mit allen derzeitig in die Galerie eingebauten Plugin-Events:

onJoomBeforeComment

Beschreibung:

  • Dieses Event wird ausgelöst, kurz bevor ein übermittelter Kommentar abgespeichert wird (nur wenn das JoomGallery-eigene Kommentarsystem verwendet wird).

Parameter:

  • Objekt mit den Informationen des übermittelten Kommentars (dieses Objekt kann verändert werden, da eine Referenz übergeben wird):
    $comment->cmtpic    => 'Die ID des Bildes, das kommentiert wird'
    $comment->cmtip => 'Die IP des Besuchers, der den Kommentar abgegeben hat'
    $comment->userid => 'Die ID des eingeloggten Benutzers (0 falls Gast)'
    $comment->cmtname => 'Der Name des Benutzers (nur falls Gast)'
    $comment->cmttext => 'Der Text des Kommentars'
    $comment->cmtdate => 'Der aktuelle Zeitpunkt'
    $comment->published => '1 falls der Kommentar veröffentlicht ist, ansonsten 0'
    $comment->approved => '0 falls der Kommentar noch freigegeben werden muss'

Rückgabewert:

  • Indem der Boolean-Wert false zurückgegeben wird, wird das Abspeichern des Kommentars verhindert. Ansonsten bitte true zurückgegeben.

onJoomAfterComment

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem ein übermittelter Kommentar abgespeichert wurde (nur wenn das JoomGallery-eigene Kommentarsystem verwendet wird).

Parameter:

  • Objekt mit den Informationen des abgespeicherten Kommentars:
    $comment->cmtpic    => 'Die ID des Bildes, das kommentiert wird'
    $comment->cmtip => 'Die IP des Besuchers, der den Kommentar abgegeben hat'
    $comment->userid => 'Die ID des eingeloggten Benutzers (0 falls Gast)'
    $comment->cmtname => 'Der Name des Benutzers (nur falls Gast)'
    $comment->cmttext => 'Der Text des Kommentars'
    $comment->cmtdate => 'Der aktuelle Zeitpunkt'
    $comment->published => '1 falls der Kommentar veröffentlicht ist, ansonsten 0'
    $comment->approved => '0 falls der Kommentar noch freigegeben werden muss'

onJoomBeforeUpload

Beschreibung:

  • Dieses Event wird ausgelöst, kurz bevor über das Frontend ein neues Bild hochgeladen wird.

Parameter:

  • keine

Rückgabewert:

  • Indem der Boolean-Wert false zurückgegeben wird, wird das Hochladen des Bildes gestoppt. Ansonsten bitte true zurückgegeben.

onJoomAfterUpload

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem über das Frontend ein neues Bild hochgeladen und erfolgreich gespeichert wurde.

Parameter:

  • Objekt mit den Daten des neuen Bildes:
    $image->id          => 'Die ID des Bildes'
    $image->imgtitle => 'Der Titel des Bildes'
    $image->imgtext => 'Der Beschreibungstext des Bildes'
    $image->owner => 'Die ID des eingeloggten Benutzers (also des Uploaders)'
    $image->cmtdate => 'Der aktuelle Zeitpunkt'
    $image->published => '1 falls das Bild veröffentlicht ist, ansonsten 0'
    $image->approved => '0 falls das Bild noch freigegeben werden muss'
    $image->imgfilename => 'Der neue Dateiname des Bildes'
    $image->ordering => 'Die Ordnungsnummer des Bildes'

onJoomBeforeVote

Beschreibung:

  • Dieses Event wird ausgelöst, kurz bevor die Bewertung zu einem Bild gespeichert wird.

Parameter:

  • Objekt mit den Daten der Bewertung:
    $vote->picid     => 'Die ID des bewerteten Bildes'
    $vote->userid => 'Die ID des eingeloggten Benutzers (0 falls Gast)'
    $vote->userip => 'Die IP des Besuchers, der den Kommentar abgegeben hat'
    $vote->datevoted => 'Der aktuelle Zeitpunkt'
    $vote->vote => 'Höhe der Bewertung (Zahl)'
    [Der Inhalt dieses Objekts wird wahrscheinlich bald geändert]
  • Höhe der Bewertung (Zahl) [Dieser Parameter wird wahrscheinlich bald entfernt]

Rückgabewert:

  • Indem der Boolean-Wert false zurückgegeben wird, wird das Speichern der Bewertung verhindert. Ansonsten bitte true zurückgegeben.

onJoomAfterVote

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem die Bewertung zu einem Bild gespeichert wurde.

Parameter:

  • Objekt mit den Daten der Bewertung:
    $vote->picid     => 'Die ID des bewerteten Bildes'
    $vote->userid => 'Die ID des eingeloggten Benutzers (0 falls Gast)'
    $vote->userip => 'Die IP des Besuchers, der den Kommentar abgegeben hat'
    $vote->datevoted => 'Der aktuelle Zeitpunkt'
    $vote->vote => 'Höhe der Bewertung (Zahl)'
    [Der Inhalt dieses Objekts wird wahrscheinlich bald geändert]
  • Höhe der Bewertung (Zahl) [Dieser Parameter wird wahrscheinlich bald entfernt]

onJoomBeforeSendMessage

Beschreibung:

  • Dieses Event wird ausgelöst, kurz bevor von der Galerie eine Mitteilung verschickt wird (keine E-Mail).

Parameter:

  • Array, mit Informationen über die gesendete Nachricht:
    $message['from']      => 'E-Mail-Adresse des Absenders'
    $message['fromname'] => 'Name des Absenders'
    $message['recipient'] => 'ID des Empfängers'
    $message['subject'] => 'Betreff der Nachricht'
    $message['body'] => 'Text der Nachricht'
    $message['mode'] => 'Der vom Messenger verwendete Modus'

Rückgabewert:

  • Indem der Boolean-Wert false zurückgegeben wird, wird das Versenden der Nachricht verhindert. So kann zum Beispiel eine 3rd-Party-Erweiterung zum Versenden der Nachricht verwendet werden. Ansonsten bitte true zurückgegeben.

onJoomAfterAddFavourite

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem ein Benutzer sich ein Bild zu seinen Favoriten hinzugefügt hat.

Parameter:

  • Die ID des hinzugefügten Bildes.

onJoomAfterRemoveFavourite

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem ein Benutzer ein Bild aus seinen Favoriten entfernt hat.

Parameter:

  • Die ID des entfernten Bildes.

onJoomAfterClearFavourites

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem ein Benutzer die Liste seiner Favoriten geleert hat.

Parameter:

  • keine

onJoomAfterDisplayThumb

Beschreibung:

  • Dieses Event wird vom View ausgelöst. Der Rückgabewert (sollte ein String sein) wird bei einem Thumbnail innerhalb von ul-Tags ausgegeben.

Parameter:

  • Die ID des Bildes, zu dem das Thumbnail gehört.

Rückgabewert:

  • Ein String, der bei einem Thumbnail innerhalb von ul-Tags ausgegeben wird.

onJoomAfterDisplayCatThumb

Beschreibung:

  • Dieses Event wird vom View ausgelöst. Der Rückgabewert (sollte ein String sein) wird beim Thumbnail einer Unterkategorie innerhalb von ul-Tags ausgegeben.

Parameter:

  • Die ID der Kategorie, zu dem das Thumbnail gehört.

Rückgabewert:

  • Ein String, der bei einem Thumbnail innerhalb von ul-Tags ausgegeben wird.

onJoomAfterSend2Friend

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem über die Send2Friend-Funktion der Detailansicht eine E-Mail verschickt wurde.

Parameter:

  • Array mit Informationen über die gesendete Nachricht:
    $message['from']      => 'Name des Absenders'
    $message['fromname'] => 'E-Mail-Adresse des Absenders'
    $message['recipient'] => 'E-Mail-Adresse des Empfängers'
    $message['subject'] => 'Betreff der E-Mail'
    $message['body'] => 'Text der E-Mail'
    $message['mode'] => 'Der vom Messenger verwendete Modus'

onJoomAfterTag

Beschreibung:

  • Dieses Event wird ausgelöst, nachdem ein Namensschild auf einem Bild gespeichert wurde.

Parameter:

  • Objekt mit den Daten des Namensschildes:
    $tag->npicid  => 'Die ID des Bildes, zu dem ein Namensschild hinzugefügt wurde'
    $tag->nuserid => 'Die ID des Benutzers, für den ein Namensschild angelegt wurde'
    $tag->by => 'Die ID des Benutzers, der das Namensschild angelegt hat'
    $tag->nuserip => 'Die IP des Besuchers, der das Namensschild angelegt hat'
    $tag->ndate => 'Der aktuelle Zeitpunkt'
    $tag->nxvalue => 'Die x-Koordinate des Namenschildes'
    $tag->nyvalue => 'Die y-Koordinate des Namenschildes'
    $tag->nzindex => 'Der z-index des Namensschildes (für Überlappungen)'

onJoomDisplayIcons

Beschreibung:

  • Dieses Event wird vom View ausgelöst. Der Rückgabewert (sollte ein String sein) wird je nach Inhalt von des ersten Parameters beim Thumbnail oder in der Detailansicht eines Bildes im Bereich der Icons ausgegeben.

Parameter:

  • Der Context des Bildes (im Moment nur 'category.image' und 'detail.image', also ob es gerade um die Kategorie- oder die Detailansicht geht).
  • Die ID des Bildes, zu dem das Thumbnail oder die Detailansicht gehört.

Rückgabewert:

  • Ein String, der beim Thumbnail und in der Detailansicht eines Bildes im Bereich der Icons (wie zum Beispiel der Stern der Favoriten oder die Diskette für den Download) ausgegeben wird.

onJoomDisplayUser

Beschreibung:

  • Dieses Event wird ausgelöst, immer wenn in der Galerie ein Benutzername ausgegeben wird. Mit Hilfe eines Plugins kann erreicht werden, dass die Benutzernamen zum Beispiel mit einem Profil in einer anderen Komponente verlinkt werden.

Parameter:

  • Die ID des Benutzers.
  • Boolean true, falls laut Einstellungen in der Galerie nicht der Benutzername sondern der vollständige Name des Benutzers ausgegeben werden soll.
  • Umgebung, in der der Benutzername angezeigt wird, zum Beispiel 'comment oder 'nametag'.

Rückgabewert:

  • Ein String, der anstelle des Benutzernamens ausgegeben wird. Dies kann zum Beispiel der mit einem Profil verlinkte Benutzername sein.

onJoomGetCaptcha

Beschreibung:

  • Dieses Event wird ausgelöst, wenn für eine Aktion in der Galerie zum Schutz-vor Spam ein Captcha verwendet werden kann (im Moment nur beim Kommentieren). Es sollte ein String zurückgegeben werden, der den Captcha darstellt.
  • Das Event wird vermutlich beginnend mit der JoomGallery 4.0 entfernt, da dann die Captcha-Plugins von Joomla! verwendet werden.

Parameter:

  • keine

Rückgabewert:

  • Ein String, der den Captcha darstellt, der für den Schutz vor Spam verwendet werden soll.

onJoomCheckCaptcha

Beschreibung:

  • Dieses Event wird ausgelöst, wenn in der Galerie ein Captcha zur Verifizierung verwendet werden kann (im Moment nur beim Kommentieren). Dabei sollen die Plugins, die dieses Event verwenden, ein Array zurückgegeben, das die Verirzierung enthält (im Gegensatz zum Event 'onJoomGetCaptcha', das zur Ausgabe des Captchas verwendet wird).
  • Das Event wird vermutlich beginnend mit der JoomGallery 4.0 entfernt, da dann die Captcha-Plugins von Joomla! verwendet werden.

Parameter:

  • keine

Rückgabewert:

  • Ein Array, mit dem Schlüssel 'valid', der entweder den Boolean-Wert true oder den Wert false enthält. Steht 'valid' auf false, kann mit dem Schlüssel 'error' optional noch eine Fehlermeldung, die dann ausgegeben wird, übergeben werden.

onJoomGetLastComments

Beschreibung:

  • Dieses Event wird ausgelöst, wenn die Galerie eine bestimmte Anzahl der zuletzt hinzugefügten Kommentare verlangt. Dadurch können Third-Party-Erweiterungen ihre Kommentare in die Toplist der Galerie einpflegen.

Parameter:

  • Ein Array aus Objekten, das gefüllt werden sollte.
  • Die Anzahl der Kommentare, die übergeben werden sollten

onJoomGetSmileys

Beschreibung:

  • Dieses Event wird ausgelöst, wenn die Galerie alle verfügbaren Smileys abfragt. Das übergebene Array kann beliebig erweitert oder verkleinert werden.

Parameter:

  • Ein Array, das die bereits gesammelten Smileys enthält.

onJoomOpenImage

Beschreibung:

  • Dieses Event wird ausgelöst, sobald ein Bildes geöffnet werden soll und wenn in der Galerie eingestellt wurde, dass das Öffnen der Bilder von Plugins geregelt werden soll.

Parameter:

  • Ein String, in den das Plugin den neuen Link zum Bild schreiben sollte.
  • Ein Objekt, das die Daten des Bildes enthält.
  • Ein String, der die URL zum Bild enthält.
  • Ein String, der den Namen der Gruppe, in die das Bild hinzugefügt werden sollte.
  • Ein String, der den zu öffnenden Bildtyp enthält ('thumb', 'img' oder 'orig').

onJoomSearch

Beschreibung:

  • Dieses Event wird ausgelöst, wenn in der Galerie über die entsprechenden Funktionen eine Suche durchgeführt wird [ist bis jetzt leider noch nicht voll funktionsfähig].

Parameter:

  • Der String, der in die Suche eingegeben wurde.

Rückgabewert:

  • Ein Array, das weitere Suchparameter enthält.

Joomla!®

Joomla! ist freie, unter der GNU/GPL-Lizenz veröffentlichte Software. Der Name Joomla! und das Logo werden unter einer limitierten Lizenz durch Open Source Matters als Rechteinhaber in den USA und anderen Staaten vergeben. Joom::Gallery ist weder Mitglied noch Teil des Joomla!-Projekts oder von Open Source Matters.