Erste Schritte in der Plugin-Entwicklung - Teil 2: Parameter
Das Joomla! Plugin im Teil 1 dieser Serie "Erste Schritte in der Plugin-Entwicklung" macht seine Arbeit gut, oder? Was aber, wenn du dein Plugin auch anderen, die Geo-Koordinaten in einem anderen Format verwenden, zur Verfügung stellen willst?
Die gängigen Formate für Geo-Koordinaten sind (Grad° Minuten' Sekunden"), (Dezimalgrad) und (Grad° Dezimalminuten), die Reihenfolge ist Breitengrad (N), Längengrad (E). Hier wird klar, wie flexibel Lösungen sein sollten und was Parameter in einem Plugin alles leisten können.
Keine Angst, ich will aus diesem Tutorial weder eine Geo-Koordinaten-Lehrstunde noch ein Tutorial für reguläre Ausdrücke machen. Hier geht es um Joomla! Wir wollen hier ein einfaches Plugin erstellen und der Schwerpunkt ist: Wie ergänze ich mein Plugin um Parameter!
Oft kommt es vor, dass der auszutauschende Text nicht eindeutig ist. Deshalb werden wir nun unser Plugin um einen Parameter ergänzen, der den auszutauschenden Text eindeutig macht. Falls dich der Begriff "Parameter" irritiert: Ich meine das, was viele Joomla!-Anwender auch unter "Optionen" kennen.
Was brauchst du?
Idealerweise hast du den ersten Teil dieses Tutorials bearbeitet. Ausreichend ist es aber auch, wenn du grundsätzlich weißt, welche Typen von Erweiterungen es in Joomla! gibt und was genau ein Plugin ausmacht. Den in Teil 1 erstellten Programmcode kannst du dir auch hier besorgen: Link zu Github.
Und welche Typen von Erweiterungen gibt es? Hier ein kurzer schneller Überblick:
- Komponenten (Components): Komponenten sind quasi die Apps der Joomla!-Welt. Sie werden im Hauptinhaltsbereich angezeigt und du kannst hier frei programmieren.
- Module (Modules): Mit Modulen kannst du bestimmte Inhalte an bestimmten Positionen deiner Website anzeigen.
- Plugins (Plugins): Bei Plugins handelt es sich um Programmcode, der im Hintergrund ausgeführt und von besonderen Ereignissen ausgelöst wird.
- Templates (Templates): Jeder will, dass seine Website etwas ganz Besonders ist. Und das was "man" als Schön ansieht ändert sich, was Design angeht realtiv oft oder muss aufgrund von neuen Geräten angepasst werden. Deshalb ist es gut, dass Joomla Design und Content trennt. Mit dem Template bestimmst du das Design.
- Dateien (Files)/Bibliotheken (Libraries): In Dateien und Bibliotheken kannst du Programmklassen zusammenfassen und ablegen, um sie in anderen Erweiterungen verwenden zu können. Wiederverwendbarkeit ist eines der klassischen Qualitätsmerkmale von Software.
- Pakete (Packages): Joomla ermöglicht es dir, mehrere zusammengehörige Erweiterungen in einem Paket zusammen zu fassen. So kannst du diese leicht zusammen installieren.
- Sprachen (Languages): Einen neuen Beitrag kannst du selbst in deiner Sprache schreiben. Auf deiner Website gibt es aber auch Dinge, die du nicht selbst beeinflussen kannst: Nämlich die Ausgaben von Komponenten, Modulen und Plugins. Die Brotkrumen-Navigation beginnt im Englischen zum Beispiel mit: „You are here:“. Auf Deutsch wünschst du dir aber vielleicht „Aktuelle Seite:“. Dies bewirkst du mithilfe von Sprachpaketen.
Arbeiten wir nun endlich weiter am Plugin
Ergänze die in Teil 1 erstellte Dateien coordstomap.php um den in der folgenden Abbildung grün hervorgehobenen Text und lösche das Rote. Ergänze dann die Datei coordstomap.xml ebenfalls um den grün hervorgehobenen Text und lösche das Rote. Alle Änderungen findest du übrigens auch bei Github. Die vollständigen Dateien kannst du dir hier ansehen.
Packe nun wieder die beiden Dateien in ein ZIP-Archiv, nenne dieses zum Beispiel plg_content_coordstomap_v1.1.0 und installiere es wie in Teil 1 über die Joomla Installationsroutine.
Wie ich schon in Teil 1 erwähnte wird das Plugin dadurch, dass wir die Methode update in der XML-Datei gewählt haben, nicht ganz neu installiert - und somit vorher deinstalliert - sondern aktualisiert! Für uns macht das hier im Moment noch keinen Unterschied. Nach dem Update ist es aber so, dass Parameter, die einmal gesetzt wurden erhalten bleiben, im Falle einer Neuinstallation würden sie auf die Standardwerte zurückgesetz!
Wechsle dann über das Menü Extensions | Plugins in die Liste der installierten Plugins und überprüfe, ob dein Plugin erscheint und aktiviert ist.
Klicke dann auf den Namen des Plugins. Es öffnet sich daraufhin ein Untermenü, in dem du Details zum Plugin ablesen kannst. Außerdem findest du hier auch das Auswahlfeld, mit dem du deinen eben programmierten Parameter - oder deine eben programmierte Option - setzten kannst. Hier wird noch nicht deutsch mit dir gesprochen. Das bringen wir dem Plugin erst im 3. Teil und somit in der nächsten Ausgabe des Magazins bei!
Das sollte dein Ergebnis sein!
In dieser Ausgabe geht es nun folgendermaßen weiter: Im nächsten Kapitel probieren wir die neue Version aus und im übernächsten Kapitel findest du die Erläuterung der in diesem Teil neu eingefügten Zeilen. Öffne nun, falls du es nicht noch vom vorhergehenden Abschnitt offen hast, das Menü Extensions | Plugins und suche den Namen deines neu erstellten Plugins. Klicke dann auf diesen Namen. Setze dann den Parameter „Are the coordinates provided with quotes?“ auf „Ja" (Yes).
Wenn du nun in einem Beitrag eine GPS Koordinate in der Form
50.000 7.8765
in einem Beitrag eingibst, passiert nichts mehr. Gibst du die Zahlen allerdings in der Form
'50.000 7.8765'
ein, wird die Koordinate in einen Hyperlink zur passenden Örtlichkeit auf der OSM Karte umgewandelt. Das sieht dann im HTML so aus:
<a href="http://www.openstreetmap.org/#map=15/50.000/7.8765">50.000 7.8765</a>
Meine Sonderzeichenwahl ist nicht ganz glücklich. Bei Hochkommas handelt es sich um Zeichen, die auch in anderer Bedeutung in einem Text vorkommen können. Idealerweise wählst du hier eine Zeichenkombination, die es im Realen nicht gibt – zum Beispiel das At-Zeichen oder den Klammeraffen in Kombination mit einer spitzen Klammer. Zum Beispiel könntest du mit <@
den Beginn und mit @>
das Ende eins auszutauschenden Textes markieren.
Programmcode im Detail
coordstomap.xml
Sehen wir uns zunächst die neuen Zeilen der Datei coordstomap.xml im Einzelnen an.
<version>1.1.0</version>
Zunächst einmal empfehle ich dir die Versionsnummer des Plugins zu erhöhen. So können wir später immer gut nachvollziehen, welche Funktion in welcher Version ergänzt wurde.
<config>
<fields name="params">
<fieldset name="basic">
Wir haben bisher nur einen Parameter, deshalb habe ich keinen neuen Bereich für die Anzeige angelegt, sondern den schon vorhandenen basic verwendet. Falls du viele Parameter verwendest, empfiehlt es sich der Übersicht halber, diese zu gruppieren. Dies kannst du mit Fieldsets erreichen. <fieldset name="format"> anstelle von <fieldset name="basic"> würde deinen Parameter in einem eigenen Register anzeigen:
<field name="quotes"
Und dann ist noch die Zeile name="quotes" wichtig. Hier vergibst du den Namen des Parameters. Bisher hast du den Parameter ja nur erstellt. Du willst ihn aber später im Plugin auch verwenden und dazu muss er natürlich angesprochen werden können, also einen Namen haben.
type="list"Als nächstes bestimmen wir, welches HTML-Element verwendet werden soll, um den Paramter vom Benutzer ändern zu können. Wir ergänzen das Plugin um eine Auswahlliste – also ein HTML-Element vom Typ „select“. Du kannst natürlich außer den Auswahllisten alle anderer HTML-Elemente als Formularelement nutzen. Joomla! bietet jede Menge Standard Formularelemente. Und falls dir das nicht reicht, kannst du dein eigenes Element oder Custom Form Field programmieren. Das ist aber ein Thema für sich. Hier soll die Auswahlliste, also das HTML-Element vom Typ „select“ als Beispiel genügen. Und dieses Element wählst du, indem du type="list" wählst.
default="0"
Einen Standardwert musst du nicht setzen. Es ist aber meiner Meinung nach immer sinnvoll, dieses zu setzen. Du kannst dies mit default="0" tun. Falls du als Standard die Eingabe mit Hochkomma setzen willst, schreibst du default="1";label="Are the coordinates provided with quotes."
description="The coordinates are provided with quotes. For example, '50 .244 7.2648' instead of 50,244 7.2648."
Mit Label und Description kannst du bestimmen, wie das Label des Elements und die Beschreibung lauten soll. Wie schon gesagt, Joomla spricht englisch – deutsch bringen wir unserem Plugin im nächsten Teil bei.<option value="1">JYES</option><option value="0">JNO</option>
Als Optionen gibt es momentan JYES und JNO, beziehungsweise Ja und Nein. Hier nutzen wir übrigens jetzt schon globale Sprachdateien. Dazu aber mehr im nächsten Teil dieser „Ersten Schritte“.</field></fieldset></fields></config>
So, jetzt schließen wir der Ordnung halber alle Elemente und fertig ist die Konfiguration. Weiter geht es mit dem Teil, der die eigentlich Arbeit macht, der Plugindatei.
coordstomap.php
Als nächstes sehen wir uns die neuen Einträge in der Datei coordstomap.php genauer an.
$quotes = $this->params->get('quotes', 0);
Du hast deinem Parameter in der Konfiguration den Namen $quotes gegeben. Deshalb kannst du ihn hier über $this->params->get('quotes', 0); in die Variable$quotes laden.
if ($quotes == 0)
{$pattern = "/([0-9.]+) ([0-9.]+)/";}
else
{$pattern = "/'([0-9.]+) ([0-9.]+)'/";}
Wenn du nun weißt, ob ein Zahlenpaar allgemein ($quotes == 0) oder ein Zahlenpaar in Hochkomma ($quotes == 1 also $quotes != 0) als Hyperlink zur OSM-Karte angezeigt werden soll, setzt du das Muster entsprechend. Dein Plugin hat mit Hilfe dieser kleinen Änderung viel an Flexibilität gewonnen. Der Benutzer kann in seinem Text selbst beeinflussen, ob die Koordinate umgewandelt werden soll oder nicht.
Fazit
Du weißt nun, wie du ein Plugin so erstellen kannst, dass es vom Anwender mithilfe von Parametern oder Optionen an unterschiedliche Problemstellungen flexibel angepasst werden kann. Als nächstes werden wir dem Plugin eine weitere Sprache beibringen. Wenn du magst, kannst du dein Wissen nun anwenden und das Plugin so erweitern, dass die zu Beginn genannten Geo-Formate alle unterstützt werden. Wahrscheinlich hast du aber auch selbst schon eine eigene Idee, die du umsetzten willst. Vielleicht hat ja auch schon ein anderer genau das gleich Problem wie du und würde sich über deine Lösung freuen. Eventuell ist deine Lösung sogar so hilfreich für andere, dass das Joomla Extension Directory oder JED sie als Erweiterung anbietet!
