Die API

Zuletzt aktualisiert am Freitag, 10. Mai 2013 13:31

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

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:

Parameter:

Rückgabewert:

onJoomAfterComment

Beschreibung:

Parameter:

onJoomBeforeUpload

Beschreibung:

Parameter:

Rückgabewert:

onJoomAfterUpload

Beschreibung:

Parameter:

onJoomBeforeVote

Beschreibung:

Parameter:

Rückgabewert:

onJoomAfterVote

Beschreibung:

Parameter:

onJoomBeforeSendMessage

Beschreibung:

Parameter:

Rückgabewert:

onJoomAfterAddFavourite

Beschreibung:

Parameter:

onJoomAfterRemoveFavourite

Beschreibung:

Parameter:

onJoomAfterClearFavourites

Beschreibung:

Parameter:

onJoomAfterDisplayThumb

Beschreibung:

Parameter:

Rückgabewert:

onJoomAfterDisplayCatThumb

Beschreibung:

Parameter:

Rückgabewert:

onJoomAfterSend2Friend

Beschreibung:

Parameter:

onJoomAfterTag

Beschreibung:

Parameter:

onJoomDisplayIcons

Beschreibung:

Parameter:

Rückgabewert:

onJoomDisplayUser

Beschreibung:

Parameter:

Rückgabewert:

onJoomGetCaptcha

Beschreibung:

Parameter:

Rückgabewert:

onJoomCheckCaptcha

Beschreibung:

Parameter:

Rückgabewert:

onJoomGetLastComments

Beschreibung:

Parameter:

onJoomGetSmileys

Beschreibung:

Parameter:

onJoomOpenImage

Beschreibung:

Parameter:

onJoomSearch

Beschreibung:

Parameter:

Rückgabewert: