27.2    Inhaltsplugin erweitern 

Die neue Version des Image Popup wird um Features aus dem Standardrepertoire von Plugins und einigen Applikationscode erweitert. Übrigens finden Sie auch diese Version 0.2.0 wieder im Download-Bereich der Begleitwebsite.

• Einsatz einer Sprachdatei
  Erlaubt Joomla!-Webmastern das Überschreiben der Beschriftungen (siehe Abschnitt 12.3, »Individuelle Übersetzungen mit Overrides anlegen«) und ist gleichzeitig die Vorbereitung für mehrsprachige Ausgaben. Dazu senden Ihnen die Joomla!-Webmaster, die Ihr Plugin übersetzen, die entsprechende Sprachdatei, die Sie dann in der nächsten Version im Erweiterungspaket ergänzen.

• Plugin-Konfiguration
  Über das XML-Manifest definieren Sie beliebige Formularfelder zur Konfiguration des Plugins. Textfelder, Auswahlboxen, Dropdown-Listen und WYSIWYG-Editoren lassen sich ohne PHP-Programmierung hinzufügen, JForm macht’s möglich. Das Beispiel wird um einen einfachen Radio-Umschalter ergänzt, mit dem der Webmaster später zwischen verschiedenen Popup-Technologien wechselt.

• Applikationscode/Businesslogik
  Steht das Plugin-Gerüst erst einmal, kümmern Sie sich um die Businesslogik, also den eigentlichen Applikationscode, der den Zweck des Plugins erfüllt. Dieses Beispiel aktiviert ein Popup-Fenster, sobald der Frontend-Besucher auf ein beliebiges Bild klickt. Dafür eignen sich verschiedene JavaScript- und CSS-Funktionalitätenerweiterungen, deren Umschaltung über die Plugin-Konfiguration erfolgt.

 

27.2.1    XML-Manifest – »imagepopup.xml« 

Neben der Erhöhung der Versionsnummer von 0.1.0 auf 0.2.0 enthält das neue XML-Manifest einen Abschnitt für die Referenz zur Sprachdatei und einen größeren Block für die Integration von Bedienelementen der Plugin-Konfiguration. Außerdem wurden alle Ausgabetexte durch Variablen ersetzt, deren Inhalte aus einer neu anzulegenden Sprachdatei stammen:

<?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.2.0</version>
  <description>PLG_CONTENT_IMAGEPOPUP_DESCRIPTION</description>
  <files>
    <filename plugin="imagepopup">imagepopup.php</filename>
    <filename>index.html</filename>
  </files>
  <languages>
    <language tag="en-GB">language/en-GB/en-GB.plg_content_imagepopup.ini 
      </language>
  </languages>
  <config>
    <fields name="params">
      <fieldset name="basic">
        <field name="popupTechnology" type="radio"
          default="0"
          class="btn-group"
          label="PLG_CONTENT_IMAGEPOPUP _FIELD_POPUPTECHNOLOGY_LABEL"
          description="PLG_CONTENT_IMAGEPOPUP _FIELD_POPUPTECHNOLOGY_DESC">
          <option value="0">PLG_CONTENT_IMAGEPOPUP _FIELD_POPUPTECHNOLOGY_ 
            OPTION_0_OFF</option>
          <option value="1">PLG_CONTENT_IMAGEPOPUP _FIELD_POPUPTECHNOLOGY_ 
            OPTION_1_MAGNIFICPOPUP</option>
        </field>
      </fieldset>
    </fields>
  </config>
</extension>

Listing 27.3    »imagepopup.xml«: Erweiterung des XML-Manifests um eine Plugin-Konfiguration und Referenzen zu Sprachdateien

Die neuen Abschnitte im Detail:

<languages>
  <language tag="en-GB">language/en-GB/en-GB.plg_content_imagepopup.ini
    </language>
</languages>

Über den <languages>-Block hinterlegen Sie pro Sprache (<language>-Tag) den Pfad zur Sprachdatei. Beachten Sie dabei die Konventionen zum Pfad: language, gefolgt vom Sprachkürzel.

<config>
  <fields name="params">
    <fieldset name="basic">
      <field name="popupTechnology" type="radio"
        default="0"
        class="btn-group"
        label="PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_LABEL"
        description="PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_DESC">
        <option value="0">PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_OPTION_ 
          0_OFF</option>
        <option value="1">PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_OPTION_ 
          1_MAGNIFICPOPUP</option>
      </field>
    </fieldset>
  </fields>
</config>

Der neue Konfigurationsblock enthält zunächst einige Tags zur Gruppierung (<fields> und <fieldset> mit Standardattributen params und basic), das <field>-Tag ist das eigentliche Formularelement. Abgesehen von name, type, label und description sind die Attribute abhängig vom Feldtyp, also ob es sich um ein Textfeld oder eine Dropdown-Liste handelt. Die wichtigsten dieser JForm-Elemente listet Abschnitt 25.3.2, »JForm-Feldtypen«. Die vollständige Auflistung finden Sie unter https://docs.joomla.org/Standard_form_field_types. Für den Beispielumschalter lautet der Typ radio, der langweilige Radio-Markierungsknöpfe darstellt. Da Joomla! aber das CSS-Framework Bootstrap auch im Administrations-Backend integriert, ist eine ansprechendere Darstellung über die Klassenkombination btn-group möglich (siehe Abbildung 27.3).

Abbildung 27.3    Dank Bootstrap erscheinen die Formularfelder modern und ansprechend, hier die Umschaltervariante für Radiobuttons mit zusätzlichen Popup-Technologien.

Die Auswahlmöglichkeiten der Radiobuttons sind als <option>-Tags gelistet, das Attribut value enthält den programminternen Wert der Option, der später im PHP-Code über den Namen dieses Formularfelds (name="popupTechnology") ausgelesen wird. Im Beispiel entscheidet der Umschalter, welche Popup-Technologie für die heranzoomenden Bilder (sogenannte Lightbox) Einsatz findet. Zu Anfang gibt es hier nur zwei Optionen: 0 – deaktiviert und 1 für die beliebte externe Popup-Bibliothek Magnific Popup.

Beachten Sie die langen großgeschriebenen Variablennamen in den <label>-, <description>- und <option>-Tags sowie weiter oben bei der Plugin-<description>. Dies sind Referenzen auf die Zeichenketten in der neuen Sprachdatei, die sogenannten Sprachschlüssel. Dabei ist es hilfreich, der Bezeichnungskonvention zu folgen, um allein vom Variablennamen direkt auf die Stelle schließen zu können, an der der Text auftaucht:

PLG_PLUGINTYP_PLUGINNAME_ELEMENT

Der Variablenname darf nur aus Großbuchstaben, Ziffern und Unterstrichen bestehen. Dieser Variablenname, z. B. PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_DESC, für die ausführliche Tooltip-Beschreibung des Formularfelds Popup Technology findet übrigens auch bei Sprach-Overrides Verwendung (Erweiterungen • Sprachen • Seitenleiste Overrides • Filter English (en-GB) – Administrator, dann Button Neu • nach Schlüssel »popup« suchen).

 

27.2.2    Applikationscode – »imagepopup.php« 

Die PHP-Datei imagepopup.php erhält drei, im folgenden Listing hervorgehobene Ergänzungen: die Einbindung der Sprachdatei, das Auslesen der XML-Manifest-Konfiguration, um die ausgewählte Popup-Technologie zu erfahren, und den eigentlichen Applikationscode: das Hinzufügen von HTML- und JavaScript-Code, der in Abhängigkeit von der Konfiguration Bilder per Mausklick in einem Popup-Fenster öffnet.

<?php
/**
 * @version   0.2.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)
  {
      $this->loadLanguage();
      JFactory::getApplication()->enqueueMessage(JText::_('PLG_CONTENT_ 
        IMAGEPOPUP_DEBUGMESSAGE'), 'notice');

    if (($this->params->get('popupTechnology', 0) == 0) || ($context == 
      'com_finder.indexer'))
    {
      return true;
    }

    JHtml::_('jquery.framework');

    switch ($this->params->get('popupTechnology', 0))
    {
      case '1':
                /* Magnific Popup */
                
                $doc =& JFactory::getDocument();
                $doc->addScript('//cdnjs.cloudflare.com/ajax/libs/ 
                  magnific-popup.js/1.0.0/jquery.magnific-popup.min.js');
                $doc->addStyleSheet('//cdnjs.cloudflare.com/ajax/libs/ 
                  magnific-popup.js/1.0.0/magnific-popup.min.css');

                $regex      = '/<img.*?>/';

                $createImageLink = function($imageTag)
                { 
                    preg_match('/src="([^"]*)"/i', $imageTag[0], $results);
                    $srcAttribute = $results[0];
                    $srcUrl = explode("=", $srcAttribute);
                    return '<a href=' . $srcUrl[1] . ' class="magnific_ 
                      popup">'.$imageTag[0].'</a>';
                };

                if (isset($article->text))
                {
                    $article->text = preg_replace_callback($regex, 
                       $createImageLink, $article->text);
                    $article->text .= '<script> jQuery( document ). 
                      ready(function() { jQuery(".magnific_popup"). 
                      magnificPopup({ type: "image", enableEscapeKey: 
                      true }); });</script>';
                }
                if (isset($article->introtext))
                {
                    $article->introtext = preg_replace_callback($regex,  
                      $createImageLink, $article->introtext);
                    $article->introtext .= '<script> jQuery( document ). 
                      ready(function() { jQuery(".magnific_popup").magnificPopup 
                      ({ type: "image", enableEscapeKey:true }); });</script>';
                }
                break;
    }

    return true;
  }
}

Listing 27.4    »imagepopup.php«: Ergänzung der Sprachschlüssel-Platzhalter und Businesslogik für die Darstellung der Popup-Fenster

Unmittelbar nach Öffnen der Funktion onContentPrepare() erfolgt die Integration der Sprachdatei:

$this->loadLanguage();

Damit stehen in der Funktion alle in der Sprachdatei hinterlegten Texte mit dem Joomla!-internen Befehl JText zur Verfügung. Am Beispiel der leicht modifizierten Debug-Mitteilung:

JFactory::getApplication()->enqueueMessage(JText::_('PLG_CONTENT_IMAGEPOPUP_DEBUGMESSAGE'), 'notice');

Bevor nun die eigentliche Businesslogik beginnt, folgen einige Bedingungen, unter denen das Plugin sofort wieder aussteigt:

if (($this->params->get('popupTechnology', 0) == 0) || ($context ==  
  'com_finder.indexer'))
{
  return true;
}

Die erste Bedingung greift auf die Konfiguration des XML-Manifests zu und vergleicht den Wert der Plugin-Konfigurationsvariablen popupTechnology mit dem Wert 0, der im XML-Quelltext dem Deaktivieren der Popup-Technologie entspricht.

Die zweite Bedingung sieht sich den Kontext an, unter dem der Plugin-Code gerade ausgeführt wird, d. h. welche Joomla!-Komponente gerade Webseiteninhalte darstellt und deshalb auf das Ereignis onBeforeContent reagiert. In der Regel ist das die für Beiträge zuständige com_content, aber auch die Joomla!-interne Suchfunktion (Smart Search, com_finder) klappert beim Indexieren (com_finder.indexer) alle Beiträge ab. Da macht es wenig Sinn, den für das Bild-Popup in Kürze ergänzten JavaScript-Code auszuführen, daher erfolgt mit return true; das vorzeitige Aus.

JHtml::_('jquery.framework');

Es folgt ein Include, das sicherstellt, dass die JavaScript-Bibliothek jQuery integriert ist. Das erfolgt normalerweise immer, aber bei der Vielzahl der eingebundenen Komponenten weiß man nicht genau, wann das geschieht. Über das JHtml-Include ist nun garantiert, dass nachfolgender Code, der von jQuery abhängig ist, fehlerfrei läuft.

switch ($this->params->get('popupTechnology', 0))
    {
      case '1':
        /* Magnific Popup */

Nun ein Blick in die Konfiguration: Per PHP-switch-Anweisung folgen von der eingestellten Popup-Technologie abhängige case-Blöcke. Im vorliegenden Beispiel gibt es zwar nur einen Fall, 1, aber auf diese Weise ist das Plugin später schnell um weitere Lightbox-Varianten erweiterbar.

Nun erfolgt das Laden der externen Magnific-Popup-Bibliothek. Dabei handelt es sich um jeweils eine JavaScript- und eine CSS-Datei, die das Plugin per addScript() und addStyleSheet() offiziell in die interne Liste nachzuladender Dateien auf der aktuellen Webseite ($doc) integriert. Dass die Einbindung so unkompliziert erfolgt, ist der Existenz von Content Delivery Networks (CDN) zu verdanken. Unter der URL https://cdnjs.cloudflare.com stehen zahlreiche nützliche Open-Source-Technologien zum kostenlosen Download und Einsatz bereit.

$doc =& JFactory::getDocument();
$doc->addScript('//cdnjs.cloudflare.com/ajax/libs/magnific-popup.js/1.0.0/ 
  jquery.magnific-popup.min.js');
$doc->addStyleSheet('//cdnjs.cloudflare.com/ajax/libs/magnific-popup.js/1.0.0/ 
  magnific-popup.min.css');

Weiter im Code:

$regex      = '/<img.*?>/';

$createImageLink = function($imageTag)
{ 
  preg_match('/src="([^"]*)"/i', $imageTag[0], $results);
  $srcAttribute = $results[0];
  $srcUrl = explode("=", $srcAttribute);
  return '<a href=' . $srcUrl[1] . ' class="magnific_popup">'.$imageTag[0]. 
    '</a>';
};                                                     

if (isset($article->text))
{
  $article->text = preg_replace_callback($regex, $createImageLink, 
    $article->text);
  $article->text .= '<script> jQuery( document ).ready(function() 
     { jQuery(".magnific_popup").magnificPopup({ type: "image", 
     enableEscapeKey:true }); });</script>';
}
if (isset($article->introtext))
{
  $article->introtext = preg_replace_callback($regex, $createImageLink,  
    $article->introtext);
  $article->introtext .= '<script> jQuery( document ).ready(function() { jQuery(".magnific_popup"). 
   magnificPopup({ type: "image", enableEscapeKey:true }); });</script>';
}
break;

Diese Logik durchforstet alle Beitragstexte und Homepage-Beitragsteasertexte nach <img>-Tags und ergänzt gegebenenfalls den Popup-Technologie-abhängigen Code.

Zu Beginn wird in $regex der reguläre Ausdruck für die <img>-Suche festgehalten. Darauf folgt die Definition einer Unterfunktion $createImageLink, die das gefundene <img>-Tag in einen <a>-Link wickelt. Die spezielle Klasse class="magnific_popup" markiert das Bild als popup-fähig.

Der Aufruf dieser Funktion geschieht in den beiden folgenden preg_replace-callback-Anweisungen. isset() überprüft zunächst, ob im aktuell übergebenen Content-Objekt ($article) ein Beitragstext ($article->text) oder ein Beitragsteasertext der Homepage ($article->introtext) enthalten ist. Das verhindert im Frontend störende PHP-Notice-Meldungen, falls das nicht der Fall und die Variable nicht gesetzt ist. Die Anweisung preg_replace-callback durchsucht dann $article->text/introtext nach dem regulären Ausdruck in $regex (<img>-Tag) und ruft bei jedem Fund die zuvor definierte $createImageLink-Funktion auf, die wiederum das modifizierte <img>-Tag zurücksendet. Das Ergebnis dieser Suchen-und-Ersetzen-Mechanik landet wieder in $article->text/introtext. Zum Schluss folgt ein kurzes jQuery-JavaScript-Fragment, das die Magnific-Popup-Technologie initialisiert (jQuery(".magnific_popup").magnificPopup()), sobald das HTML-Dokument fertig geladen wurde.

(Beachten Sie, dass das Beitragsobjekt bei der onContentPrepare-Definition als Referenz importiert wird – das kaufmännische Und bei &$article. Das heißt, alle Modifikationen am Beitragstext werden direkt in $article und seinen Eigenschaften vorgenommen, sodass das Ereignis später ohne speziellen Text-Rückgabewert beendet wird: return true;)

 

27.2.3    Sprachdatei – »en-GB.plg_content_imagepopup.ini« 

Damit steht der Applikationscode, es fehlt aber noch ein Element, das die zweite Image-Popup-Version lauffähig macht: die Sprachdatei. Diese legen Sie per Hand im Ordner /administrator/language/en-GB/ an und benennen sie en-GB.plg_content_imagepopup.ini. Das sind der Pfad und der Dateiname, die Sie zuvor im XML-Manifest angaben (/administrator/ ist bei dieser Angabe implizit, da es sich um ein Plugin handelt). Fügen Sie in diese Datei alle Sprachvariablen ein, die im Verlauf der Plugin-Weiterentwicklung im XML-Manifest bzw. PHP-Code Erwähnung fanden. Den Textinhalt setzen Sie dahinter nach einem Zuweisungs-Gleichzeichen in doppelte Anführungszeichen.

PLG_CONTENT_IMAGEPOPUP_DESCRIPTION="Beschreibung"
PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_LABEL="Popup Technology"
PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_DESC="Pick any popup technology.  
  If one doesn't work or doesn't look good to you, just try a different one."
PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_OPTION_0_OFF="Off"
PLG_CONTENT_IMAGEPOPUP_FIELD_POPUPTECHNOLOGY_OPTION_1_MAGNIFICPOPUP="Magnific  
  Popup" 
PLG_CONTENT_IMAGEPOPUP_DEBUGMESSAGE="This debugging messages originates from 
  the language file <i>en-GB.plg_content_imagepopup.ini</i>."

Listing 27.5    »en-GB.plg_content_imagepopup.ini«: Zuweisung von Ausgabetexten zu Sprachschlüsseln

Falls an dieser Stelle etwas schiefgeht, merken Sie das im Frontend sofort, da Joomla! dort den vermeintlichen Sprachvariablennamen anzeigt, wenn kein passender Inhalt in der Sprachdatei gefunden wurde.

Haben sich keine Tippfehler eingeschlichen (nutzen Sie gerne auch die Copy-&-Paste-Möglichkeit von https://joomla-handbuch.com), besuchen Sie nun das Plugin im Backend von Joomla! und stellen in seiner Konfiguration die Popup Technology auf Magnific Popup. Aktualisieren Sie im Frontend eine Beitragsseite, die ein Bild enthält, und testen Sie den Lightbox-Mechanismus durch Klick auf das Bild wie in Abbildung 27.4. Falls sich nichts bewegt, die Debug-Nachricht aber sichtbar ist, werfen Sie einen Blick in den Quelltext: Wurden Magnific-Popup-Dateien im HTML-Header inkludiert? Befindet sich das <img>-Tag tatsächlich im erzeugten <a>-Link-Tag?

Abbildung 27.4    Eingeblendetes Magnific-Popup-Bild-Popup und aktivierte »JText«-Debug-Ausgabe mit Text aus der Sprachdatei

 

27.2.4    Erweiterungspaket schnüren 

Als letzten Schritt schnüren Sie aus den Plugin-Dateien in Ihrem Joomla!-Entwicklungssystem ein ZIP-Archiv, das sich wie eine normale Erweiterung aus dem Joomla! Extensions Directory auf Ihrem Live-System einrichten lässt. Vielleicht möchten Sie Ihre Arbeit auch anderen zugänglich machen und das Plugin im JED veröffentlichen. Wie das funktioniert, lesen Sie in Kapitel 30, »Erweiterungen veröffentlichen«.

Zur Zusammenstellung des Archivs kopieren Sie alle betroffenen Dateien in ein Verzeichnis abseits Ihrer Joomla!-Installation, z. B. nennen Sie es plg_content_imagepopup_v0.2.0. Die Integration der Sprachdatei erfordert das Anlegen weiterer Unterverzeichnisse, die exakt der XML-Manifest-Pfadangabe im Tag <languages> • <language tag="en-GB"> entsprechen: /language/en-GB/. Vergessen Sie auch nicht die obligatorischen index.html-Verzeichnisschutzdateien für jeden Unterordner.

Tabelle 27.3    Schieben Sie die Plugin-Dateien aus dem Entwicklungssystem in einen separaten Ordner, um dort das ZIP-Archiv zu erzeugen.

Wie geht es nun weiter mit dem Image Popup? Die Erweiterung könnte zusätzliche Popup-Technologien bereitstellen, damit Webmaster mehr Auswahlmöglichkeiten bei der Zoomdarstellung der Bilder haben. Die Fortführung einer kleinen Idee hält den Programmieraufwand gering: Es kommen nur Popup-Technologien infrage, die per Content Delivery Network (CDN) nachgeladen werden können. Dazu erzeugen Sie weitere PHP-switch-cases und inkludieren die entsprechenden JavaScript- und CSS-Dateien im HTML-Header. Ein Beispiel für das finale Plugin finden Sie im Joomla! Extensions Directory: Das JH Image Popup ist solch eine erweiterte Version dieses Handbuchexperiments, Sie finden es, indem Sie im JED nach »image popup« suchen.