20.2 Die API nutzen
Unser nächstes Anliegen ist es, nicht nur irgendwelchen Text auszugeben, sondern auch auf die Umgebung von Joomla! zu reagieren. Dazu stellen die Programmierer uns eine Schnittstelle zur Verfügung, über die wir auf die Daten und Funktionen des Systems zugreifen können: die so genannte API. Leider ist diese bisher sehr spärlich dokumentiert. Das soll sich mit Joomla! 1.1 ändern. Hier wurde schon ein Dokumentations- und Entwicklerportal eingerichtet, das Sie unter der URL dev.joomla.org aufrufen können.
Generell stellt die API einige allgemeine Funktionen sowie den Zugriff auf bestimmte Objekte zur Verfügung, die das Verhalten von Joomla! bestimmen. Die wichtigsten Objekte sind:
|
Mainframe
Über dieses Objekt haben Sie Zugriff auf die erstellte Seite. |
|
|
Database
Regelt die Kommunikation mit der Datenbank. |
|
|
patTemplate
Eine Template-Engine, die Sie auch für Ihre Erweiterungen nutzen können. |
|
|
My
Die Daten des angemeldeten Users. |
|
|
Params
Über dieses Objekt erhalten Sie Informationen aus den Parameterseiten der Erweiterungen. |
|
|
mosHTML
Gibt HTML-Tags aus. |
Eine Übersicht über wichtige Funktionen finden Sie in der Referenz in Anhang A. Um ein Gefühl für die API zu bekommen, wollen wir unser Modul dahingehend erweitern, dass als Ausgabe der Name eines eingeloggten Users erscheint. Hinter dem Namen soll ein Info-Icon stehen, das einen Tooltipp einblendet, wenn man mit der Maus darüber fährt.
Informationen über den User stehen im Objekt $my der Klasse mosUser. Dort finden Sie zwei wichtige Eigenschaften: username enthält den Namen des Benutzers, und usertype gibt an, in welcher Gruppe er sich befindet. Zudem haben Sie über id noch Zugriff auf eine Identifikationsnummer, die bei Datenbankabfragen von Bedeutung sein kann (s. u.).
Nun können wir schon den ersten Teil der Aufgabe erledigen. Öffnen Sie dazu die Datei joomla/modules/mod_hallojoomla.php, und ersetzen Sie die vierte Zeile, die »Hallo Joomla« ausgibt, durch den folgenden Code. Funktionen der Joomla!-API sind dabei jeweils fett gedruckt:
3 ...
4 if ($my->id == 0)
5 {
6 $my_name = "Besucher";
7 } else {
8 $my_name = $my->username;
9 }
10 echo "<H1>$my_name</H1>";
Listing 20.3 Auszug aus mod_api_1.php
In Zeile 4 wird überprüft, ob die User-ID 0 ist. In diesem Fall gibt es keinen angemeldeten Benutzer und wir müssen unseren Gast neutral ansprechen. Dazu speichern wir die Ausgabe in eine Zwischenvariable (Zeile 6). Hat sich ein User angemeldet, so können wir ihn mit seinem Usernamen begrüßen, der dann in Zeile 8 in die Ausgabevariable geschrieben wird. Die Ausgabe selbst erfolgt ganz unspektakulär in Zeile 10.
| Hinweis: Zum Testen können Sie dieses Modul wieder installieren. Die XML-Datei können Sie aus mod_hallojoomla.xml übernehmen. Vergessen Sie nicht, den Eintrag <filename> in der zugehörigen XML-Datei anzupassen. Dies gilt auch für die folgenden Programme.
|
Die Ausgabe eines Tooltips wird von der Funktion mosToolTip übernommen. Da die Tooltip-Funktionalität in HTML mithilfe eines JavaScripts realisiert wird, muss die Datei joomla/includes/js/overlib_mini.js noch in die Seite eingebunden werden. mosToolTip nimmt in unserem Fall vier Parameter entgegen. Der erste enthält den auszugebenden Text, also die Usergruppe. Dann folgt ein Text, der im Titel der Anzeige erscheinen soll. Der nächste Wert ist die Mindestbreite in Pixel, und zuletzt geben wir eine Grafik an, die als Basis für den Tooltip dienen soll. Die Abfrage des Usernamens im obigen Listing muss jeweils um die des Usertyps ergänzt werden.
3 ...
4 if ($my->id == 0)
5 {
6 $y_name = "Besucher";
7 $my_grp = "Gast";
8 } else {
9 $my_name = $my->username;
10 $my_grp = $my->usertype;
11 }
12 echo '<script type="text/javascript"
13 src="includes/js/overlib_mini.js"></script>';
14 echo "<H1>$my_name";
15 echo mosToolTip($my_grp, 'Gruppe', '30', 'tooltip.png');
16 echo "</H1>";
17 ?>
Listing 20.4 Auszug aus mod_halloapi_2.php
In den Zeilen 12 und 13 wird die JavaScript-Datei eingebunden. Sie sehen, dass der Pfad relativ zum Host angegeben wird. Der eigentliche Tooltip-Code wird in Zeile 15 erzeugt. Das Bild tooltip.png wird von Joomla! mitgeliefert und liegt im Verzeichnis includes/js/ThemeOffice.
Nehmen wir an, Sie hätten gern die Möglichkeit, wieder auf den Tooltip zu verzichten. Dazu wollen wir in der URL die Möglichkeit bieten, einen weiteren Parameter tooltip=no anzugeben, der die Anzeige unterdrückt. URL-Parameter werden über den Befehl mosGetParam entgegengenommen. Dieser benötigt zwei Angaben. Die erste besagt, auf welche Art der Parameter übergeben wurde. Für URL-Parameter benötigen Sie $_GET, für Daten aus HTML-Formularen wird häufig $_POST verwendet. Wenn Sie nicht sicher sind, so verwenden Sie $_REQUEST. Die zweite Angabe enthält den Namen des Parameters, der abgefragt werden soll.
11 ...
12 if (!$tt = mosGetParam($_GET, 'tooltip')) $tt = 'yes';
13 if ($tt == "yes") echo '<script type="text/javascript"
14 src="includes/js/overlib_mini.js"></script>';
15 echo "<H1>$my_name";
16 if ($tt == "yes") echo
17 mosToolTip($my_grp, 'Gruppe', '30', 'tooltip.png');
18 echo "</H1>";
19 ?>
Listing 20.5 Ausschnitt aus mod_halloapi_3.php
In Zeile 12 wird der Wert des Parameters tooltip ausgelesen und in die Variable $tt gespeichert. Wenn kein Parameter übergeben wurde, so wird $tt auf yes gesetzt. Damit die Einstellung Wirkung zeigt, müssen wir die Ausgabe der Zeilen, die für den Tooltip verantwortlich sind, vom Wert des Parameters abhängig machen. Das passiert in den Zeilen 13 und 16.
|
