20.3 Parametrisieren
Es war schon einige Male die Rede davon, dass Module auch parametrisiert werden können. Dazu sind zwei Schritte notwendig. Zum einen müssen wir in der XML-Datei festlegen, welche Parameter es geben soll und über welche Formularelemente auf sie zugegriffen werden kann. Zum anderen ist der Modul-Code so zu ändern, dass diese Einstellungen auch Wirkung zeigen.
Sehen wir uns zunächst die XML-Datei an. Wir wollen vier Parameter einführen. Mit dem ersten soll man festlegen können, welche Bezeichnung für Gäste ausgegeben wird. Der zweite lässt dem User die Wahl zwischen einem von drei Layouts des Moduls. Der dritte bestimmt, ob ein Tooltip erzeugt wird, und der vierte legt fest, welches Bild als Hotspot für diesen Tooltip angezeigt werden soll.
Die Angabe der Parameter erfolgt über das XML-Tag <params>. Dieses enthält für jede Einstellungsoption ein weiteres Tag <param>, das wiederum einige Attribute hat.
Tabelle 20.2 Attribute von <param>
| Attribut
|
Beschreibung
|
| name
|
Name der Variable, über die der Wert später angesprochen werden soll.
|
| type
|
Art und Weise, wie die Werte des Parameters in der Einstellungsseite angegeben werden können (s. u.).
|
| label
|
Beschriftung des Eingabefeldes.
|
| size
|
Größe des Eingabefeldes.
|
| description
|
Eine Beschreibung der Auswirkung des Parameters. Diese wird als Tooltip hinter dem Eingabefeld ausgegeben.
|
| default
|
Vorgabewert, falls nichts geändert wird.
|
| Hinweis: Das Attribut description wird in älteren Joomla!-Versionen unter Umständen nicht angezeigt. Dieser Fehler ist in Version 1.0.8 behoben.
|
Die Darstellung einer Option auf der Einstellungsseite wird durch das Attribut type festgelegt. Hier haben Sie im Wesentlichen die Möglichkeiten, die man von HTML schon kennt, sowie einige Joomla!-spezifische Anzeigen.
Werden neue Parameter für ein Modul eingeführt, so muss das Modul komplett neu installiert werden, da in diesem Fall zusätzliche Einträge in der Datenbank notwendig sind. Wenn Sie nur die Texte der Anzeige ändern wollen, so können Sie das wieder im joomla/modules-Verzeichnis tun. In unserem Fall könnte die Parameter-Sektion in der Datei mod_halloparams.xml aus dem separaten Verzeichnis so aussehen:
14 ...
15 <params>
16 <param name="gast" type="text"
17 label="Gast" default="Besucher"
18 description="Bezeichnung für Gast-User"/>
19 <param name="layout" type="list"
20 label="Layout" default="layout1"
21 description="Erscheinungsbild des Moduls">
22 <option value="layout1">Layout 1</option>
23 <option value="layout2">Layout 2</option>
24 <option value="layout3">Layout 3</option>
25 </param>
26 <param name="@spacer" type="spacer"
27 default="" label="" description="" />
28 <param name="tooltip" type="radio"
29 label="Tooltip" default="yes"
30 description="Anzeige des Tooltips">
31 <option value="yes">Ja</option>
32 <option value="no">Nein</option>
33 </param>
34 <param name="hotspot" type="imagelist"
35 label="Hotspot" default="tooltip.png"
36 directory="/includes/js/ThemeOffice"
37 hide_none="1" hide_default="1"
38 description="Bild für den Hotspot" />
39 </params>
40 </mosinstall>
Listing 20.6 Ausschnitt aus mos_halloparams.xml
Die Beschreibung des Textfeldes (Zeilen 16–18) weist keine Besonderheiten auf und ist relativ leicht zu verstehen. Im folgenden Auswahlfeld (Zeilen 19–25) finden Sie die Untertags <option>, die die Werte angeben, die zur Auswahl stehen. Das Attribut value bestimmt in diesem Fall, welcher Wert an das Modul übergeben wird. Dieser Wert muss auch im default-Attribut von <param> angegeben werden, damit dieses richtig umgesetzt wird. Die horizontale Linie (Zeilen 26–27) hat im name-Attribut einen Wert, der mit @ beginnt. Damit wird dem System klar gemacht, dass es diesen Parameter als Wert ignorieren kann. Die Auswahl über Radio-Buttons (Zeilen 28–33) funktioniert genauso wie das Auswahlfeld. Der letzte Parameter, die Liste der Bilder (Zeilen 34–39), hat drei zusätzliche Attribute. directory gibt das Verzeichnis an, aus dem die Einträge für die Liste ausgewählt werden sollen. Der Pfad muss relativ zum Joomla!-Verzeichnis sein und mit einem Schrägstrich beginnen. Die Attribute hide_none und hide_default verstecken (Wert 1) oder zeigen (Wert 0) die Einträge »Use no image« und »Use default image« in der Liste.
Um das Ergebnis zu sehen, deinstallieren Sie das »Hallo Joomla«-Modul und installieren es neu. Wenn Sie nun die Einstellungsseite aufrufen, sollte die in etwa so aussehen, wie in Abbildung 20.3 dargestellt.
Bisher haben die Parameter noch wenige Auswirkungen auf die Darstellung des Moduls. Daher müssen wir die Datei mos_halloparams.php so modifizieren, dass sie die Einstellungen berücksichtigt. Zentral ist natürlich der Zugriff auf die gespeicherten Werte. Dieser wird über das params-Objekt angesprochen. Es besitzt eine Methode get, in der Sie den Namen des Parameters und einen Standardwert angeben müssen. Die Ausgabe des Gastnamens muss also so verändert werden:
6 $my_name = $params->get('gast', 'Besucher');
Die Einstellung der Tooltip-Anzeige finden Sie in der nächsten Zeile:
12 if (!$tt = mosGetParam($_GET, 'tooltip'))
13 $tt = $params->get('tooltip', 'yes');
Um das richtige Bild ausgeben zu lassen, ist noch eine letzte Änderung nötig:
17 if ($tt == "yes")
18 echo mosToolTip($my_grp, 'Gruppe', '30',
19 $params->get('hotspot', 'tooltip.png'));
20 echo "</H1>";
Wie Sie sehen, haben wir an alle Stellen, an denen die Werte der Parameter verwendet werden, einfach die Abfrage des params-Objekts gestellt. Die Änderung der Anzeige in Abhängigkeit von einem bestimmten Layout werden wir weiter unten besprechen.
|
