27    Plugins entwickeln 

Werden Sie auf der Suche nach einer bestimmten Funktion im Joomla! Extensions Directory nicht fündig, programmieren Sie sie einfach selbst. Plugins eignen sich für verschiedenste Funktionalitätserweiterungen ohne Benutzerinteraktionen.

Plugins sind die am einfachsten zu programmierenden Erweiterungen, da sie abgesehen von einem einfachen Konfigurationsformular keine Interaktion zwischen dem Benutzer oder Administrator und Joomla! vorsehen. Sie dienen dazu, das CMS um kleine Funktionalitäten zu bereichern. Nachträgliche Manipulationen an Beitragsinhalten, Cache- und Redirect-Mechanismen, HTML-Aufräumarbeiten, Authentifizierungsverfahren, alles kleine Helfer, die ihre Arbeit unbemerkt im System verrichten. Das ist nicht auf nachträglich installierbare Erweiterungen beschränkt. Auch der Joomla!-Core besteht aus einigen wichtigen Plugins, in die Sie jederzeit einen Blick werfen können, um die Umsetzung einer Funktionalität zu studieren.

In diesem Kapitel lernen Sie zunächst das Grundgerüst eines Plugins kennen, das Sie im Anschluss um eine kleine Applikationslogik erweitern. Das Image Popup nutzt dabei eines der vielen bereitgestellten Joomla!-Ereignisse, um Beitragsinhalte kurz vor der Darstellung im Browser um einen Popup-Mechanismus zu erweitern.

Tabelle 27.1    Die wichtigsten Begriffe zur Plugin-Programmierung

Im Kern besteht ein Joomla!-Plugin aus zwei Dateien:

• XML-Manifest
  Das XML-Manifest ist die erste Datei, die sich Joomla! ansieht, um alle wichtigen Eckdaten zur Erweiterung zu erhalten. Neben Name, Versionsnummer und enthaltenen Dateien ist es für Plugins insoweit wichtig, da hier auch die Formularfelder der Plugin-Konfiguration hinterlegt sind (Beispiel in Abbildung 27.1). Der Dateiname muss dem internen Namen der Erweiterung nach dem Schema pluginname.xml entsprechen, für das Beispiel auf den folgenden Seiten: imagepopup.xml.

  

  Abbildung 27.1    Über das XML-Manifest legen Sie die grundsätzlichen Eigenschaften des Plugins fest, dazu gehört neben Name und Beschreibung auch das Formular der Plugin-Konfiguration.

• PHP-Businesslogik
  Der Applikationscode befindet sich in einer Datei nach dem Namensschema pluginname.php. Der Code wird im Joomla!-Kontext ausgeführt und kann auf alle Klassen und Objekte des Frameworks, des Content-Management-Systems und die Inhalte zugreifen. Entsprechende Komplexität vorausgesetzt, arbeiten Sie hier auch mit Includes oder binden eigene PHP- oder Applikations-Frameworks ein. Für das simple Image Popup genügt aber eine einzelne imagepopup.php-Datei.

 

27.1    Einfaches Inhaltsplugin erzeugen 

Zum Einstieg erzeugen Sie ein primitives Plugin, das im ersten Schritt eine Debug-Ausgabe im Frontend von Joomla! erzeugt. So stellen Sie sicher, dass die Plugin-Eigenschaften vorbereitet sind, das Gerüst steht und alle Bezeichner den korrekten Namen haben. Später, in der zweiten Version, beeinflusst das Plugin direkt den Inhalt von Beiträgen und modifiziert beispielhaft das HTML-Tag <img> so, dass im Fließtext enthaltene Bilder sich per Mausklick in einem Popup-Fenster öffnen. Der Arbeitstitel dieses kleinen Projekts lautet deshalb Image Popup. Derartige Inhalte manipulierende Plugins gehören übrigens zum Typ content, alle Typen lernen Sie in Kürze kennen.

Ziel: Erstellen Sie Ihr erstes Plugin mit einer einfachen Debug-Ausgabe.

Vorgehen: Sie erzeugen nacheinander das XML-Manifest und die PHP-Programmdatei innerhalb Ihrer Joomla!-Entwicklungsumgebung. Zum Ende der Entwicklung schnüren Sie aus beiden Dateien ein Erweiterungspaket, das Sie wie eine reguläre Erweiterung in andere Joomla!-Installationen, z. B. auf dem Live-Server, installieren. Falls Sie übrigens kein Freund vom Abtippen von Listings sind, laden Sie das Plugin-Paket Version 0.1.0 auch gerne direkt von https://joomla-handbuch.com/downloads/handbuch herunter.

Öffnen Sie nun Ihren Dateimanager, wechseln Sie in Ihrer Joomla!-Installation ins Verzeichnis /plugins/content/, und erzeugen Sie ein neues Verzeichnis /imagepopup/. Hierin erstellen Sie alle auf den folgenden Seiten vorgestellten Dateien.

 

27.1.1    Verzeichnisschutzdatei – »index.html« 

Die erste benötigte Datei hat zunächst nicht viel mit dem Plugin zu tun, sondern dient der Sicherheit. Ist die Verzeichnisausgabe des Webservers falsch konfiguriert, können findige Hacker die Dateien verschiedener Verzeichnisse einsehen. Um dem entgegenzuwirken, legen Sie in alle Verzeichnisse und Unterverzeichnisse Ihrer Erweiterung eine Datei index.html, die auch schlecht konfigurierte Server ausgeben, bevor sie Einblick ins Verzeichnis gewähren. Diese index.html enthält dabei nicht mehr als den nackten Rahmen eines HTML-Dokuments und gibt damit einem Servereindringling keinerlei Hinweise auf Webapplikation, Programmiersprachen oder Versionsnummern, um eine mögliche Schwachstelle ausfindig zu machen.

<html><body></body></html>

Hinweis: Legen Sie in Zukunft in jedes neu erzeugte Unterverzeichnis in Ihrem Plugin diesen index.html-Dummy.

 

27.1.2    XML-Manifest – »imagepopup.xml« 

Als Nächstes erstellen Sie die Datei imagepopup.xml, wie eingangs erwähnt, enthält sie alle Metadaten zum Plugin.

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.0" type="plugin" group="content" method="upgrade">
    <name>Content - Image Popup</name>
    <author>Vorname Nachname</author>
    <creationDate>May 2015</creationDate>
    <copyright>Copyright (C) 2015 Vorname Nachname. All rights reserved. 
      </copyright>
    <license>http://www.gnu.org/licenses/gpl-3.0.html</license>
    <authorEmail>vorname.nachname@IhrDomainName.de</authorEmail>
    <authorUrl>http://IhrDomainName.de</authorUrl>
    <version>0.1.0</version>
    <description>Beschreibung</description>
    <files>
        <filename plugin="imagepopup"> imagepopup.php</filename>
        <filename>index.html</filename>
    </files>
</extension>

Listing 27.1    »imagepopup.xml«: einfachste Ausführung eines Plugin-XML-Manifests mit Referenzen zur Programm- und Verzeichnisschutzdatei

Der XML-Code im Detail:

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.0" type="plugin" group="content" method="upgrade">
[…]
</extension>

Den Rahmen für die Erweiterungsdefinition bilden die Deklaration des XML-Dokuments und das <extension>-Tag, das grundsätzliche Eigenschaften dieser Erweiterung festlegt.

• version gibt an, ab welcher Joomla!-Version diese Erweiterung eingesetzt werden kann. Das ist abhängig von den Features, die Sie zur Programmierung einsetzen. Mit "3.0" fahren Sie aber relativ sicher, die meisten einfachen Plugins sind auch noch unter "2.5" lauffähig.

• type="plugin" kennzeichnet diese Erweiterung als Plugin im Gegensatz zu "module" oder "component".

• group steht für den Plugin-Typ und ist damit ausschließlich für Plugins vorgesehen. content-Plugins dienen beispielsweise der Beeinflussung der Beitragsausgabe im Frontend, während system-Plugins an allen internen Joomla!-Rädern drehen dürfen. Die group beeinflusst dabei die zur Verfügung stehenden Ereignisse, auf die das Plugin reagiert, z. B. content • onContentPrepare für »vor der Darstellung des Inhalts« oder user • onUserLogin für »nach der Anmeldung eines Benutzers«. Werfen Sie einen Blick in Ihre Joomla!-Installation; unter /plugins/ finden Sie Plugin-Unterordner (entsprechen dem Plugin-Typ), die diese group-Zuordnung abbilden. Das Image Popup gehört zum Typ content und wird später in den gleichlautenden Unterordner installiert.

Tabelle 27.2    Der Plugin-Typ des »group«-Attributs beeinflusst die Ereignisse, auf die das Plugin später reagieren kann, um eigenen Code auszuführen.

• method="upgrade" ist erforderlich, falls Ihr Plugin irgendetwas in der Datenbank von Joomla! speichert und diese Daten bei einem Plugin-Update nicht verloren gehen sollen. Fehlt dieses Attribut, löscht Joomla! alle mit dem Plugin assoziierten Daten.

<name>Content - Image Popup</name>
<author>Vorname Nachname</author>
<creationDate>May 2015</creationDate>
<copyright>Copyright (C) 2015 Vorname Nachname. All rights reserved. 
  </copyright>
<license>http://www.gnu.org/licenses/gpl-3.0.html</license>
<authorEmail>vorname.nachname@IhrDomainName.de</authorEmail>
<authorUrl>http://IhrDomainName.de</authorUrl>

Diese Tags sprechen für sich, tragen Sie hier den Plugin-Namen ein, Ihren eigenen, das Erstellungsdatum und Kontaktinformationen. Setzen Sie unter <license> die Lizenz ein, aufgrund derer Bedingungen Sie Ihre Erweiterung vertreiben. GPL ist dabei die in der Joomla!-Community übliche Open-Source-Lizenz, die das Benutzen, Studieren, Verändern und Vertreiben (die berühmten »vier Freiheiten«) der Software erlaubt. Damit ist es Entwicklern möglich, den Code anderer Erweiterungenquellen zu studieren, zu verbessern und/oder Teile in eigene Projekte einzubauen, die vielleicht als Codevorlage für wieder andere Erweiterungen dienen. Ein für den Erfolg von Joomla! entscheidender Aspekt, der die Qualität und Vielfalt der Erweiterungen hochhält.

<version>0.1.0</version>

Das <version>-Tag umklammert die aktuelle Versionsnummer nach softwareüblichem Schema, mit durch Punkte getrennte Hauptversion, Nebenversion und Revisionsnummer. Hauptversionen kennzeichnen große Feature-Ergänzungen, Funktionalitätsänderungen oder ein komplettes internes Refactoring. Nebenversionen werden bei kleinen Funktionserweiterungen hochgezählt, Revisionsnummern dienen Korrekturen oder Bugfixes.

<description>Beschreibung</description>

Der hier angegebene Beschreibungstext erscheint sowohl unmittelbar nach Installation des Plugins als auch beim Aufruf der Plugin-Konfiguration.

<description><![CDATA[<div style="width:50%; padding:6px 12px 0px 12px; border:1px solid #000; border-radius:3px; background-color:#DDD;"><p>Ich bin das <strong>Image Popup</strong> und komme vom <a href="https://joomla-handbuch.com" target="_blank">Joomla!-Handbuch</a></p></div>]]></description>

<files>
    <filename plugin="imagepopup">imagepopup.php</filename>
    <filename>index.html</filename>
</files>

Da das XML-Manifest als erste Anlaufstelle für die Integration der Erweiterung dient, erwartet Joomla! im <files>-Block die Nennung aller übrigen Dateien (<filename>-Tag) und Unterverzeichnisse (<folder>-Tag), die im Plugin enthalten sind. Die hier angegebenen Dateien kopiert das CMS bei der Erweiterungsinstallation aus dem ZIP-Archiv ins Datei-Backend. Für das Beispiel sind das die sämtlichen Programmcode enthaltende PHP-Datei imagepopup.php und die zuvor erzeugte leere index.html. Beachten Sie die genaue Schreibweise des plugin-Attributs, das exakt mit dem PHP- und XML-Dateinamen übereinstimmen muss.

 

27.1.3    Plugin-Code – »imagepopup.php« 

Nach dem XML-Manifest legen Sie die Datei an, die den ausführbaren Code des Plugins enthält, imagepopup.php. Es ist möglich, Code komplexer Plugins über PHPs Include-System auszulagern, für den ersten Test benötigen Sie jedoch nur wenige Zeilen Quellcode, der die Ausführung des Plugins per Debug-Ausgabe bestätigt.

<?php
/**
 * @version   0.1.0
 * @author    Vorname Nachname
 * @copyright Copyright (C) 2015 Vorname Nachname
 * @license   http://www.gnu.org/licenses/gpl-3.0.html
 */
defined('_JEXEC') or die;

class plgContentImagepopup extends JPlugin
{
    public function onContentPrepare($context, &$article, &$params, $page = 0)
    {
        JFactory::getApplication()->enqueueMessage 
          ('Wir sind im Ereignis onContentPrepare', 'notice');
        return true;
    }
}

Listing 27.2    »imagepopup.php«: Businesslogik-Teil des Plugins, eine einfache Debug-Ausgabe für die erste Version

An dieser Stelle noch mal die Erwähnung einer für manche ungewöhnlichen PHP-Konvention, die sofort ins Auge fällt: Schließen Sie im Joomla!-Umfeld keine PHP-Datei mit dem üblichen ?>-Tag. Das erledigt zum einen der Webserver für Sie, zum anderen vermeiden Sie dadurch nachfolgende Whitespaces und Leerzeichen, die im schlimmsten Fall die HTML-Ausgabe zerstören.

<?php
/**
 * @version   0.1.0
 * @author    Vorname Nachname
 * @copyright Copyright (C) 2015 Vorname Nachname
 * @license   http://www.gnu.org/licenses/gpl-3.0.html
 */

Beginnen Sie PHP-Blöcke immer mit ausgeschriebenem Anfangstag <?php und nicht der Shorthand-Kurzform <?, um sicherzustellen, dass Ihr Programmcode auf jedem Server ausgeführt wird. Der Doc-Block mit Informationen zu Dateiversion und Kontakt- und Lizenzinformationen ist selbsterklärend; er wird übrigens mit einem Leerzeichen und nicht wie sonst in Joomla!-PHP mit einem Tab eingerückt.

defined('_JEXEC') or die;

Jede PHP-Datei beginnt mit einer Überprüfung, ob die Ausführung im Kontext von Joomla! erfolgt. Falls nicht, wird der Code sofort verlassen (die).

class plgContentImagepopup extends JPlugin
{

Als Nächstes öffnen Sie die Klasse plgContentImagepopup, die die Standard-Joomla!-Klasse JPlugin erweitert, d. h., alle Eigenschaften und Methoden diese Klasse werden übernommen, und Sie erweitern sie um Ihren eigenen PHP-Code. Achten Sie auf die exakte Schreibweise des Klassennamens: plg (Plugin), dann der im XML-Manifest unter group angegebene Kategorie- und Verzeichnisname (in diesem Fall Content für ein Plugin, das die Ausgabe von Joomla!-Beiträgen beeinflusst), gefolgt vom Plugin-Namen, hier Imagepopup. Die Kamelhöckerschreibweise ist nicht zwingend notwendig, gehört aber zum guten Programmierstil.

public function onContentPrepare($context, &$article, &$params, $page = 0)
{

Jetzt wird es spannend. Joomla! führt Plugin-Programmcode aus, sobald ein bestimmtes Ereignis (Event) eintrat, z. B. vor der Darstellung von Beiträgen, bei der Zusammenstellung des HTML-Headers, nachdem sich ein Benutzer eingeloggt hat oder bevor Joomla! aufgrund eines Besucherklicks ermittelt, welche Webseite dargestellt wird. Eine Liste aller Ereignisse finden Sie am Ende des Kapitels. Für das Image Popup, das später in den Beitragsinhalt eingreift, ist onContentPrepare genau das richtige Event. Hier fängt es einen frühen Schritt der Ausgabevorbereitung von Beiträgen ab. Die wichtigsten Parameter: $context beschreibt, in welcher Komponente Joomla! gerade arbeitet, und &$article enthält einen Zeiger auf den Beitragsinhalt.

        JFactory::getApplication()->enqueueMessage 
          ('Wir sind im Ereignis onContentPrepare', 'notice');
        return true;
    }
}

Zum Abschluss des ersten Plugin-Experiments erzeugen Sie per Joomla!-Standardfunktion eine Debug-Ausgabe. JFactory::getApplication() sammelt alle über diesen Befehl angegebenen Texte und stellt sie in einem gelb hinterlegten Hinweiskasten dar (siehe Abbildung 27.2). Tipp: Statt notice setzen Sie als zweiten Parameter error, warning oder message für andere Arten von Fehlermeldungen ein.

 

27.1.4    Plugin installieren und aktivieren 

Den Plugin-Programmcode haben Sie zwar innerhalb der Dateistruktur von Joomla! integriert, das CMS weiß aber noch nichts von der Erweiterung. Im nächsten Schritt machen Sie das Plugin deshalb bekannt und aktivieren es.

1. Rufen Sie das Administrations-Backend Ihrer Joomla!-Entwicklungsumgebung auf, und begeben Sie sich dort zum Erweiterungsmanager unter Erweiterungen • Verwalten • Seitenleiste Überprüfen.

2. Falls Ihr Plugin noch nicht erscheint, klicken Sie auf den Button Überprüfen. Markieren Sie es nun mit einem Häkchen, und wählen Sie Installieren.

3. Neue Plugins sind nach ihrer Installation zunächst deaktiviert. Wechseln Sie über Erweiterungen • Plugins zum Plugin-Manager, und suchen Sie nach »popup«.

4. Klicken Sie zur Plugin-Aktivierung auf das rote Stoppschild () in der Status-Spalte, und besuchen Sie kurz die Plugin-Konfiguration durch Klick auf den Plugin-Titel. An dieser Stelle erscheint der Text, den Sie zuvor im <description>-Tag des XML-Manifests hinterlegten.

5. Wechseln Sie jetzt ins Frontend, und laden Sie irgendeine Webseite. Der erste Test war erfolgreich, wenn Sie den Hinweiskasten mit Ihrer Debug-Nachricht sehen.

   

   Abbildung 27.2    Das Event »onContentPrepare« wird bei der Ausgabe jedes Beitrags ausgelöst; da die Reiseforum-Homepage vier Beiträge anteasert, sammelt »enqueueMessage()« die Debug-Ausgabe viermal.

Damit stehen Ihnen prinzipiell alle Wege offen, eigene Plugins zu schreiben. Überlegen Sie sich genau, welchen Zweck Ihr Plugin erfüllen soll, und vergewissern Sie sich im Joomla! Extensions Directory, dass es solch eine Erweiterung noch nicht gibt. Existiert ein ähnliches Plugin, laden Sie es herunter, testen es und werfen einen Blick in den Quelltext. Entweder eignet sich das Plugin out-of-the-box für Ihre Website oder vielleicht auch nach einigen Modifikationen. Mindestens erhalten Sie durch das Quelltextstudium Einblick in die Funktions- und Herangehensweise an das Applikationsthema. Denn das ist der Grund für die GPL-Basis, auf der Joomla! und alle Erweiterungen stehen. Alle Bestandteile des Open-Source-Projekts dienen explizit auch dem Studium und als mögliche Grundlage für ein ähnlich geartetes Erweiterungsprojekt.