• Magazin
  • Communtiy
  • Presse

Joomla bietet jede Menge Schnittstellen, die du nutzen kannst. Um diese besser zu verstehen, möchte ich als Grundlage ein kleines Plugin mit dir schreiben.

Wenn du das fertige Plugin aktiviert hast und deine Seite besuchst, werden alle GPS-Koordinaten in Beiträgen, sofern vorhanden, in Hyperlinks zur passenden Stelle auf der OSM-Karte abgeändert. Ein sehr sinnvolles Plugin finde ich! Vor allem dann, wenn man auf einer Website zum Wandern immer die Koordinaten in einem bestimmten Format eingibt und sich nach Jahren dazu entschließt diese zu einer Karte zu verlinken.

Eingeladen sind hier also alle die, die sich bisher noch an keine eigene Erweiterung herangetraut haben. Dabei ist das gar nicht so schwer! Ich hoffe, dass ich alles verständlich erläutere und dich zum Nachahmen anrege, denn Joomla! macht Spaß, ist clever und dabei super flexibel.

Was brauchst du?

Natürlich ist eine laufende Joomla! Installation eine Voraussetzung. Dazu reicht dir ein lokaler Webserver der schnell mit XAMPP installiert ist. So kannst du herumexperimentieren ohne dabei Angst haben zu müssen, dass du etwas kaputt machst. Eine super Anleitung für diese Installation findest du im JCM: Joomla lokal installieren mit XAMPP.

Außerdem ist ein Editor, der die PHP Syntax hervorhebt recht nützlich. Grundsätzlich reicht aber auch Notepad++.

Ansonsten sind PHP-Kenntnisse hilfreich, wobei ich alles so einfach wie möglich beschreibe. Lass dich also nicht entmutigen und gib der Anleitung eine Chance.

Basiswissen

Bevor du dein erstes Plugin schreibst, solltest du wissen, dass es unterschiedliche Plugin Typen gibt. Wir beginnen mit dem einfachsten - einem Content Plugin. Dieses ermöglicht es dir Änderungen im Inhalt von Beiträgen vorzunehmen, bevor diese angezeigt werden.

Joomla Plugin Typen
Joomla Plugin Typen

Und dann solltest du dir bewusst machen, dass Joomla! seine Inhalte ständig beobachtet. Es nutzt dabei das Entwurfsmuster Beobachter der objektorientierten Programmierung. Joomla! hilft dir hier also ein bewährtes Lösungsschema für wiederkehrende Probleme anzuwenden.

Beispiel: Der Text eines Beitrages wird im Browser dargestellt. Der Website Besucher will aber permanent etwas anderes sehen. Ein Plugin ist nun nichts anderes als ein Beobachter. Es ist mit einem globalen Beobachter des Joomla! Kerns verbunden, dem Event Dispatcher.

Was bedeutet das für dich?

Joomla! übernimmt die Arbeit für dich. Du - und damit dein Plugin- müssen nicht wissen, wie die Komponente der Beiträge genau arbeitet. Du musst nur wissen, was womit ersetzt werden soll. Joomla! macht es dir also einfach! Sobald das „Was“ im Beitrag erscheint, führt der Beobachter, also das Plugin, seinen Auftrag aus.

Joomla! Entwurfsmuster Beobachter
Joomla! Entwurfsmuster Beobachter

Durch diese Beobachter wird dein Plugin im Kern von Joomla! nutzbar. Aber Achtung, dies bedeutet auch, dass es zu Problemen kommen kann, wenn in einem aktivierten Plugin ein Fehler steckt. Mit einem Content Plugin kannst du Joomla! aber nicht kaputt machen. Deaktiviere das Plugin einfach wenn dir eine Fehlermeldung angezeigt wird und fange von vorne an. So lernst du am meisten. Wenn du eine konkrete Frage stellst, hilft man dir auch gerne im Supportforum auf joomla.de.


Fangen wir nun aber endlich an

Alle Joomla-Plugins werden mit Hilfe einer Installationsdatei installiert. Diese Datei übergibt alles Wichtige zum Plugin an Joomla! wenn du das Plugin installierst.

Erstelle also dazu eine Datei mit dem nachfolgenden Inhalt und nenne sie coordstomap.xml.


    <?xml version=“1.0″ encoding=“UTF-8”?>
    <extension
    version=“3.0″
    type=“plugin”
    group=“content”
    method=“upgrade”>
    <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>
    <version>1.0.0</version>
    <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>
    <files>
    <filename plugin=“coordstomap”>coordstomap.php</filename>
    </files>
    </extension>

Die eigentliche Arbeit übernimmt die Plugin Datei. Erstelle dazu nun eine Datei mit dem nachfolgenden Inhalt und nenne sie coordstomap.php.


	<?php
	 /**
	 * @package     Joomla.Plugin
	 * @subpackage  Content.Coordstomap
	 *
	 * @copyright   Copyright 2015 Astrid Günther. All rights reserved.
	 * @license     GNU General Public License version 2 or later;
	 */
	 defined(‘_JEXEC’) or die;
	 /**
        * Coords to map plugin class.
        *
        * @since  3.0
        */class PlgContentCoordstomap extends JPlugin
         {
         	/**
            * Plugin that add a hyperling to the osm map to all gsp coordinates.
            *
            * @param   string   $context  The context of the content being passed to the plugin.
            * @param   mixed    $row      An object with a “text” property or the string to be cloaked.
            * @param   mixed    $params   Additional parameters. See {@see PlgContentEmailcloak()}.
            * @param   integer  $page     Optional page number. Unused. Defaults to zero.
            *
            * @return  boolean    true on success.
            */
            ublic function onContentPrepare($context, $row, $params, $page = 0)
            {
                if (is_object($row))
                {
                    return $this->coordstomap($row->text, $params);
                }
         
                return $this->coordstomap($row, $params);
            }
         
             /**
             * Generate a search pattern based on link and text.
             *
             * @param   string  &$text    The text enclosed by the link.
             * @param   string  &$params  The target of an email link.
             *
             * @return  string    A regular expression that matches a link containing the parameters.
             */
            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;
            }
         }

Wenn ich dir Namen vorschlagen musst du diese natürlich nicht übernehmen. Du kannst dein Plugin nennen wie du magst. Beachten solltest du aber, dass die XML-Datei genauso heißt wie das Plugin - oder manifest.xml.
Außerdem muss der Name deiner Klasse folgendermaßen zusammengesetzt sein: Plg + Art des Plugins + Name des Plugins
Bei uns im Beipspiel also: Plg + Content + Coordstomap = PlgContentCoordstomap

Packe nun die beiden Dateien in ein Zip-Archiv, nenne dieses zum Beispiel plg_content_coordstomap_v1.0.0. Hier spielt die Namenswahl keine Rolle. Installiere dieses Packet dann ganz normal über die Joomla Installationsroutine Erweiterung Plugin. Falls du mehr zum Thema Namenswahl und Versionsnummer wissen willst, empfehle ich dir die englischen Beiträge Extension name und den Abschnitt Erklärung der Versions-Nummerierungim Beitrag Welche Version von Joomla! sollte verwendet werden?

Joomla! - ein Plugin installieren
Joomla! - ein Plugin installieren

Wechsele nun in die Liste der installierten Plugins. Hier sollte nun dein Plugin in der Liste zu finden sein. Aktiviere dieses nun und probiere es aus! Dann erläutere ich die wenigen Zeilen des Programmcodes.

Joomla! - ein Plugin aktivieren
Joomla! - ein Plugin aktivieren

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.

 

Unser Hostingsponsor

Mittwald Logo