Joomla!Magazin D-A-CH Ausgabe 01/2016

Das sollte dein Ergebnis sein!

Wenn du nun in einem Beitrag eine GPS Koordinate in der Form

50.000 7.8765

eingibst, wird diese in einen Hyperlink zur passenden Örtlichkeit auf der OSM Karte umgewandelt:

<a href=“http://www.openstreetmap.org/#map=15/50.000/7.8765”>50.000 7.8765</a>

Programmcode im Detail

coordstomap.xml

Sehen wir uns hier einmal jede Zeile der Datei coordstomap.xml im einzelnen an.

<?xml version=“1.0″ encoding=“UTF-8”?>

Bei der Installationsdatei handelt es sich um eine XML-Datei kodiert im Zeichensatz UTF-8

<extension version=“3.0″

Mit der Versionsnummer gibst du an, ab welcher Joomla Version dein Plugin lauffähig ist. Falls du dein Plugin auch für Joomla! 2.5 anbieten willst, solltest du hier version=“2.5”eintragen. Diese Zeile dient momentan nur der Dokumentation. Bei der eigentlichen Installation wird sie nicht geprüft. Also, auch wenn hier version=“3.0″steht, kann das Plugin unter Joomla! 2.5 installiert werden.

type=“plugin”

Über den Parameter Typ erfährt Joomla, um welche Art von Erweiterung es sich handelt. Hier also um ein plugin.

group=“content”

Das Attribut group ist nur für Plugins relevant. Wir haben hier, wie oben schon aufgezeichnet, ein Content Plugin erstellt.

method=“upgrade”>

Der Eintrag method=“upgrade”>ist wichtig. Wenn du diesen Eintrag vergisst, wird dein Plugin bei jedem weiteren Update zunächst deinstalliert. In der Regel bedeutet das, dass alle bisher eingegeben Daten verloren gehen. Für unser Plugin ist das nicht wirklich ein Problem, weil wir bisher keine Daten speichern. Das kann sich aber ja ändern und damit der Eintrag dann nicht vergessen wird, ist es eine gute Idee ihn nun schon einzufügen.

    <name>Content - Coordinates to OSMMap</name>
     <author>Astrid Günther</author>
     <creationDate>Dezember 2016</creationDate>
     <copyright>Copyright (C) 2016 Astrid Günther</copyright>
     <license> http://www.gnu.org/licenses/gpl-3.0.html</license>
     <authorEmail>Diese E-Mail-Adresse ist vor Spambots geschützt! Zur Anzeige muss JavaScript eingeschaltet sein!</authorEmail>
     <authorUrl>http://astrid-guenther.de</authorUrl>

Dieser Textblock erklärt sich von selbst, oder? Gib hier einfach deine Daten ein.

<version>1.0.0</version>

Dieser Eintrag ist nun wieder wichtig wenn du planst dein Plugin weiterzuentwickeln und später Updates anbietest. Ihn solltest du der Ordnung halber mit jeder Änderung aktualisieren. Ich finde es immer gut, wenn in einem Projekt Dinge einheitlich gehandhabt werden. Verwende doch hier auch die von Joomla! genutzte Art der Versionierung.

<description>This plugin will replace gps coordinates with a link to osm. Requires Joomla 3.0 or greater. Don’t forget to publish this plugin! </description>

Die Beschreibung enthält den Text, den ein Benutzer direkt nach der Installation angezeigt bekommt.

Wie du es schafft ihn mehrsprachig anzubieten zeige ich dir in Plugin-Entwicklung - Teil 3 Sprachdateien.

Es ist nützlich, hier den Hinweis anzuzeigen, dass das Plugin eventuell noch aktiviert werden muss. Standardmäßig werden Plugins nämlich nach der Installation deaktiviert. Sie erledigen ihre Arbeit erst dann, wenn sie aktiviert wurden.

<files> <filename plugin=“coordstomap”>coordstomap.php</filename> </files>

Im letzten Abschnitt unserer Installationsdatei erfährt Joomla!, welche Dateien genau zum Plugin gehören. In unserem Fall ist es, abgesehen von der Installationsdatei, nur eine Datei.

</extension>

Und zum guten Schluss muss das Tag <extension>dann nur noch geschlossen werden.

coordstomap.php

Als nächstes sehen wir uns die Datei coordstomap.php genauer an.

    <?php
     /**
     * @package     Joomla.Plugin
     *
     * @copyright   Copyright 2015 Astrid Günther. All rights reserved.
     * @license     GNU General Public License version 2 or later;
     */

Am Anfang jeder Datei solltest du einen Kommentarblock einfügen. Auch im Weiteren solltest du so gut wie möglich den Programmcode dokumentieren. Falls du dies nicht tust, läuft dein Plugin natürlich trotzdem. Die Kommentare sind aber sinnvoll. Nicht nur für dich oder andere die später noch einmal am Programm etwas ändern wollen. Es gibt Tools, die auf der Grundlage deiner Kommentare automatische Dokumentationen anfertigen können. Außerdem helfen die Kommentare Integrierten Entwicklungsumgebungen bei der automatischen Programmcodevervollständigung. In Joomla! ist es üblich die Joomla! Coding Standards zu beachten. Ich fand das am Anfang ganz unsinnig und schrecklich. Ich habe mich aber darauf eingelassen und dann schnell gemerkt, dass es mehr Vorteile als Nachteile gibt, wenn man sich an die Standards hält. Im Weiteren werde ich dich aber der Vereinfachung halber nicht weiter mit Kommentarblocks nerven.

defined(‘_JEXEC’) or die;

Die Zeile defined(‘_JEXEC’) or die; findest du am Anfang von jeder PHP-Datei in Joomla!. Sie macht Joomla! sicherer. Wenn du die Zeile in einer Datei auslässt, könnte man diese Datei außerhalb von Joomla! aufrufen. Mit der Zeile ist nur ein Aufruf innerhalb von Joomla! möglich. Früher hat man der Zeile immer noch einen Hinweis mitgegeben. Zum Beispiel: defined(‘_JEXEC’) or die(‘Restricted access’);. Dies tut man heute aber nicht mehr, weil ein Hacker so nur unnötig Rückschlüsse auf das CMS schließen könnte.

class PlgContentCoordstomap extends JPlugin {

Als nächstes erstellst du deine Plugin Klasse. Dazu erweiterst du die Standardklasse JPlugin und damit registrierst du auch gleichzeitig die Beobachter die dich bei Änderungen informieren. Das hatte ich ja vorher schon einmal erwähnt, erinnerst du dich?

     public function onContentPrepare($context, $row, $params, $page = 0)
        {
            if (is_object($row))
            {
                return $this->coordstomap($row->text, $params);
            }
     
            return $this->coordstomap($row, $params);
        }

Die erste Methode, die wir in die Klasse einfügen heißt onContentPrepare().Immer dann, wenn Joomla! einen Beitrag zur Anzeige vorbereitet, sehen die Beobachter in deinem Plugin nach, ob was zu tun ist. Was zu tun ist genau dann, wenn die Methode onContentPrepare() Programmcode enthält. Und der wird dann ausgeführt.

Hier handelt es sich um ein sehr kleines Plugin. Du hättest allen Programmcode eigentlich auch in dieser Methode unterbringen können. Meistens ist es jedoch so, dass dein Plugin mehr arbeiten soll und dann ist die Aufteilung in verschiedene Methoden in der Regel übersichtlicher. Und das bereiten wir nun schon einmal vor, indem wir in der Methode onContentPrepare() nur prüfen, ob der Beitragstext in Form eines Objektes oder als einfacher Text übergeben wird und diesen Text dann passend umgewandelt an die Funktion coordsToMap() übergeben.

        protected function coordsToMap(&$text, &$params)
        {
            $pattern = ‘/([0-9.]+) ([0-9.]+)/‘;
            $replacement = ‘<a href=“http://www.openstreetmap.org/#map=15/$1/$2″>$1 $2</a>‘;
     
            $text = preg_replace($pattern, $replacement, $text);
     
            return true;
        }

Die Methode coordsToMap übernimmt nun all die harte Arbeit. Ich habe hier ein Beispiel mit regulären Ausdrücken gewählt, weil dies meiner Meinung nach die meisten Möglichkeiten bietet.

Falls dir reguläre Ausdrücke nichts sagen, kannst auch mit einfacheren PHP Funktionen wie zum Beispiel str-replace Ersetzungen im Text vornehmen.

Mit der Variablen &$text wird der Beitragstext an die Methode coordsToMap() übergeben.

Zuerst legt die Methode coordsToMap() in der Variablen $pattern fest, nach welchem Muster gesucht werden soll: $pattern = ‘/([0-9.]+) ([0-9.]+)/‘;.

Danach gibt sie in der Variablen $replacement an, womit dieses Muster ersetzt werden soll: $replacement = ‘<a href=“http://www.openstreetmap.org/#map=15/$1/$2″>$1 $2</a>’;.

Im Anschluss wird der gesamte Beitragstext, der ja als String in der Variablen &$text enthalten ist, nach dem Muster durchsucht und alle Vorkommen werden ersetzt: $text = preg_replace($pattern, $replacement, $text);

Mehr Informationen zur Funktion preg_replace() findest du bei php.net.

Wenn alles glatt läuft, gibt die Methode ein true zurück. Wenn du dich ein bisschen mit regulären Ausdrücken auskennst, kannst du in jedem Beitrag so gut wie alles mit allem ersetzen. Falls dir reguläre Ausdrücke noch nichts sagen, empfehle ich dir dieses Tutorial.

}

Am Schluss beenden wir die Klasse mit der schließenden Klammer. Das PHP-Tag brauchen wir am Ende einer Datei nicht zu schließen. Deshalb tun wir es auch nicht und verhindern so mögliche Probleme.

Fazit

Ein tolles Plugin - oder ? Vielleicht nicht gerade die Funktion die du suchst, aber es zeigt anschaulich die Mächtigkeit, die von Plugins in Joomla! ausgehen kann. Deutlich wird, so hoffe ich, dass es relativ leicht ist, neue Funktionen an Joomla! zu übergeben.

Als nächstes werden wir das Plugin mit Parametern versehen und ihm eine weitere Sprache beibringen.

Quelle

Inspiriert hat mich übrigens der Beitrag Introduction to Plugin Development for Site Builders. Mit Hilfe dieses Beitrags habe ich mein erstes Joomla Plugin geschrieben.