Joomla! Programmierung/Programmierung/Plugins/Inhalt
Inhaltsverzeichnis |
[Bearbeiten] Einleitung
Inhalt- oder „Content Plugins” stellen nebend den Modulen die häufigste und zugleich auch einfachste Form von Erweiterung dar, mit denen sich Ausgaben bzw. Inhalte verschiedener Artikel dynamisch verändern lassen. Hierzu zählt beispielsweise das automatische Ersetzen und Umwandeln von Schlüsselbegriffen in einem Artikel oder einer Komponente. Wie für alle Plugins stehen auch der Plugin Gruppe „content” einige Events bereit.
Diese Anleitung beschreibt an einem einfachen Beispiel das Ersetzen verschiedener Platzhalter in einem Artikel. Zu diesem Zweck verwenden wir das Event „onContentPrepare”.
[Bearbeiten] environment_vars.xml
Beginnen wir mit dem sogenannten „XML Manifest”, der Installationsdatei des Plugin. Hier werden neben einigen Angaben zum Autor, die für die Installation nötigen Anweisungen vorgenommen. Die Verwendung dieser Datei und auch der Sprachdatei ist allgemein gültig und unabhängig vom jeweiligen Event.
<?xml version="1.0" encoding="utf-8"?> <extension version="2.5" type="plugin" group="content" method="upgrade"> <name>Content - Environment Vars</name> <author>Joomla!-Nafu</author> <creationDate>June 2012</creationDate> <copyright>Copyright (C) Joomla!-Nafu</copyright> <license>GNU General Public License, http://www.gnu.org/licenses/gpl-2.0.html</license> <authorEmail>kontakt[at]joomla-nafu.de</authorEmail> <authorUrl>http://www.joomla-nafu.de</authorUrl> <version>1.0</version> <description>PLG_ENVIRONMENT_VARS_DESCRIPTION</description> <files> <filename plugin="environment_vars">environment_vars.php</filename> <filename>helper.php</filename> <filename>index.html</filename> </files> <languages> <language tag="de-DE">de-DE.plg_content_environment_vars.ini</language> <language tag="de-DE">de-DE.plg_content_environment_vars.sys.ini</language> </languages> <config> <fields name="params"> <fieldset name="basic"> <field name="enabled" type="radio" default="1" label="PLG_ENVIRONMENT_VARS_ENABLE" description="PLG_ENVIRONMENT_VARS_ADDITIONAL_SWITCH"> <option value="0">JNO</option> <option value="1">JYES</option> </field> </fieldset> </fields> </config> </extension>
[Bearbeiten] Erläuterung
Nach der Angabe des verwendeten Zeichensatzes werden sämtliche Anweisungsblöcke der XML-Datei vom <extension>...</extension> Tag umschlossen.
Wie in unserem Beispiel zu sehen wurden der Anweisung <extension> die erforderlichen Attribute version, type, group und method hinzugefügt.
<extension version="2.5" type="plugin" group="content" method="upgrade">
- version="2.5": Bezeichnet die Joomla!-Version, auf der das Plugin installiert werden kann.
- type="plugin": Durch diese Anweisung teilen Sie dem Installationsscript mit, dass es sich um ein Plugin handelt. Bei Komponenten würde hier „component” stehen. Bei Modulen „module”.
- group: Hier wird dem Installationsvorgang mitgeteilt, um welche Plugin Gruppe es sich handelt.
- method="upgrade" (optional): Das Plugin kann installiert werden, ohne die bereits installierte Version löschen zu müssen.
<name>Content - Environment Vars</name> <author>Joomla!-Nafu</author> <creationDate>June 2009</creationDate> <copyright>Copyright (C) Joomla!-Nafu</copyright> <license>GNU General Public License, http://www.gnu.org/licenses/gpl-2.0.html</license> <authorEmail>kontakt[at]joomla-nafu.de</authorEmail> <authorUrl>http://www.joomla-nafu.de</authorUrl> <version>1.0</version> <description>PLG_ENVIRONMENT_VARS_DESCRIPTION</description>
Der dann folgende Anweisungsblock enthält Informationen zum Autor, Lizenz- und Versionsangaben sowie der Angabe optionaler Kontaktdaten und unterliegt einschließlich der Beschreibung keinen stilistischen Vorgaben.
Um in Ihrer Beschreibung HTML Anweisungen verwenden zu können, muss diese mit <![CDATA[...]]> umschlossen werden. Die darin befindlichen Informationen werden dadurch vom XML Parser ignoriert.
Hinweis: Eine weitere Möglichkeit ist es, die HTML Formatierungen in die Sprachdatei auszulagern. Dies hat im Gegensatz zur Verwendung von CDATA den Vorteil dass die Beschreibung sowohl bei der Installation, als auch in der Backend Administration des Plugin korrekt Dargestellt wird.
[Bearbeiten] Dateien
Im Bereich <files> wird mit dem Attribut plugin="environment_vars" der Name des Plugins übergeben, welcher nach der Installation in der Datenbank unter: #prefix_plugins|Plugin_Name|element verwendet wird. Weiterhin wird der Name der PHP Datei notiert, die später den Einstiegspunkt darstellt.
<files> <filename plugin="environment_vars">environment_vars.php</filename> <filename>helper.php</filename> <filename>index.html</filename> </files>
Sowohl die Installationsdatei (environment_vars.xml), als auch alle zusätzlichen Dateien werden vom Installationsprozess in das Verzeichnis: 
Joomla!Hauptverzeichnis/plugins/content/environment_vars kopiert.
Wenn man ein größeres Plugin schreibt, das Unterordner beinhaltet, ist für diese die Syntax <folder>Unterordner</folder> zu empfehlen. Dadurch werden alle Dateien und Unterverzeichnisse des betreffenden Ordners vom Installationsvorgang berücksichtigt, müssen also nicht extra aufgelistet werden.
[Bearbeiten] Parameter
Um dem Plugin mehr Funktionalität geben zu können haben wir die Möglichkeit verschiedene Parameter einzubauen. Diese Parameter werden in der XML Datei über den Tag <config>...</config> angegeben und erscheinen später im Backend in den Einstellungen des Plugins. Joomla! stellt eine Reihe von Standard Parametern, wie Eingabefelder oder Auswahllisten bereit, mit deren Hilfe man das Verhalten oder die Ausgabe des Plugin beeinflussen kann. Es ist ebenso möglich eigene Parameter Elemente zu erstellen.
<config> <fields name="params"> <fieldset name="basic"> <field name="enabled" type="radio" default="1" label="PLG_ENVIRONMENT_VARS_ENABLE" description="PLG_ENVIRONMENT_VARS_ADDITIONAL_SWITCH"> <option value="0">JNO</option> <option value="1">JYES</option> </field> </fieldset> </fields> </config>
Im späteren Verlauf dieses Beispiels werden wir zeigen, wie auf diese Paramter zugegriffen werden kann.
- Weitere Informationen: XML Parameter Elemente
[Bearbeiten] Übersetzung
Wenn Sie vorhaben Ihr Plugin der Allgemeinheit zur Verfügung zu stellen sollten Sie darauf achten, dass die Beschreibungen aller Parameter, also der Einstellungen im Backend, sowie deren Informationstexte vom System übersetzt werden können. Wir benutzen dafür folgende Anweisung:
<languages> <language tag="de-DE">de-DE.plg_content_environment_vars.ini</language> <language tag="de-DE">de-DE.plg_content_environment_vars.sys.ini</language> </languages>
Weitere Informationen zu Sprachdateien können Sie dem nächsten Abschnitt entnehmen.
[Bearbeiten] de-DE.plg_content_environment_vars.ini
Der Name der Sprachdatei wird nach dem Schema xx-XX.plg_Gruppe_NameDesPlugins.ini erstellt. Der erste Teil stellt den Ländercode dar, wobei für die Übersetzung die Sprache in Joomla! installiert sein muss. Eine Liste der Ländercodes finden Sie unter http://en.wikipedia.org/wiki/List_of_ISO_639-1_codes in der Spalte 639-1. Der zweite Teil enthält den Namen der Gruppe welcher das Plugin angehört.
Plugin Sprachdateien werden vom System in das Verzeichnis administrator/language/xx-XX kopiert. In unserem Fall also administrator/language/de-DE.
PLG_ENVIRONMENT_VARS_ENABLE_PLUGIN=Plugin aktivieren PLG_ENVIRONMENT_VARS_ADDITIONAL_SWITCH=Zusätzlicher Parameter zum deaktivieren oder aktiveren des Plugins PLG_ENVIRONMENT_VARS_DESCRIPTION=<strong>Environment Vars - Joomla! 2.5.x Content Plugin</strong><br />Ersetzt definierte Konstanten mit Umgebungsvariablen.
Hier sieht man, dass die Sprachtags, die in der Installationsdatei und den PHP-Dateien verwendet werden, in die betreffende Sprache übersetzt werden. Die Sprachtags, üblicherweise auf Englisch, in Großbuchstaben, zusammengeschrieben bzw. mit Unterstrich und systematisch benannt, sind sozusagen Platzhalter, für welche die hier definierten Texte eingesetzt werden. Wenn es für einen der Platzhalter keine Entsprechung in den Sprachdateien gibt, wird der Platzhalter selbst ausgegeben.
Wie oben zu sehen, werden die Platzhalter in die xml-Datei wie normaler Text geschrieben, in PHP-Dateien bedient man sich der Klasse JText. Folgender Beispielcode würde also in einer PHP-Datei des Plugins die Pluginbeschreibung ausgeben:
<?php echo JText::_('PLG_ENVIRONMENT_VARS_DESCRIPTION'); ?>
Hinweis: Die Sprachdateien müssen mit der Endung .ini im UTF-8 Format gepeichert werden und dürfen kein BOM enthalten.
[Bearbeiten] de-DE.plg_content_environment_vars.sys.ini
Diese Datei ist optional und beinhaltet nur Übersetzungen, die direkt bei der Installation verwendet werden sollen. In diesem Fall können wir also unsere Pluginbeschreibung noch zusätzlich in diese Datei schreiben:
PLG_ENVIRONMENT_VARS_DESCRIPTION=<strong>Environment Vars - Joomla! 2.5.x Content Plugin</strong><br />Ersetzt definierte Konstanten mit Umgebungsvariablen.
[Bearbeiten] environment_vars.php
<?php /** * @author Joomla!-Nafu * @authorurl http://www.joomla-nafu.de * @Version 1.0 * @license GNU General Public License, http://www.gnu.org/licenses/gpl-2.0.html * * Environment Vars - Joomla! 1.5.x Content Plugin - Replacing Defined Constants With Environment Variables * Copyright (C) 2009 - Joomla!-Nafu * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the * Free Software Foundation. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Pdeaublic License for * more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, see <http://www.gnu.org/licenses/>. **/ // Standard Überprüfung ob die Datei über das Framework aufgerufen wurde defined( '_JEXEC' ) or die( 'Nah, Joomla! - you know,...' ); // Import der JPlugin Klasse jimport( 'joomla.plugin.plugin' ); // Erweitern der Klasse JPlugin class plgContentEnvironment_Vars extends JPlugin { /** * Zu Beginn muss die Sprachdatei geladen werden. **/ public function __construct(& $subject, $config) { parent::__construct($subject, $config); $this->loadLanguage(); } /** * Aufruf der Event-Methode * * Die Methode "onContentPrepare" stellt die erste Stufe der Generierung * der Artikel Ausgabe dar und wird für Content Plugins am häufigsten verwendet. * * @param object Übergabe des Artikel Objekts. Die Verwendung von $article->text ist ebenso möglich. * @param object Das $params Objekt enthält alle Artikel zugehörigen Parameter. * @param int Seitenzahl **/ public function onContentPrepare( $article, $params, $page = 0 ) { /** * Prefix * * Das hier erstellte Prefix wird bei der Status Prüfung und im Regulären * Ausdruck benutzt. **/ $prefix = 'ev_'; /** * Um Ressourcen zu sparen wird an dieser Stelle überprüft ob der String * "{ev_" im Artikel vorkommt. Wenn der Vergleich "true" ist * , also der String nicht im Text enthalten ist wird der Vorgang beendet. * Andernfalls wird das Plugin weiter ausgeführt. **/ if ( JString::strpos( $article->text, '{'.$prefix ) === false ) { return true; } /** * Regulärer Ausdruck - Schlüsselwort * * Zur Identifizierung unserer Schlüsselwörter benötigen * wir ein Erkennungsmuster. Sie können dafür ein beliebiges Wort * oder eine Zeichenfolge verwenden, sollten jedoch bei Ihrer Auswahl * darauf achten, dass der verwendete Begriff so in keinem Artikel oder * Ausgabe vorkommt. * * Beispiel: Mit $regexpr = '/Datum/' soll das Wort "Datum" durch das aktuelle * Datum ersetzt werden. * * In diesem Fall würde das Plugin sämtliche Vorkommen von "Datum" umwandeln. * Besser wäre: '/{Datum}/' oder '/{plg_.*?}/i' * Näheres zur Verwendung von Regulären Ausdrücken finden sie in den * weiterführenden Links. **/ $regexpr = '/{'.$prefix.'.*?}/i'; /** * Seitens Joomla! ist es im Falle eines deaktivierten Plugins nicht * vorgesehen, dass die in einem Artikel enthaltenen Schlüsselwörter * gefiltert werden. * * Über die XML Datei haben wir einen zusätzlichen Schalter * eingebaut, mit dessen Hilfe wir diese Funktion nachrüsten. Bei * ausgeschaltetem Plugin wird der übergebene Text vom Regulären * Ausdruck, und somit allen notierten Schlüsselwörtern bereinigt. * * Wenn Sie das Plugin über Joomla! deaktivieren verbleiben die * Schlüsselbegriffe ungefiltert im Artikel. **/ if ( !$this->params->get( 'enabled', 1 ) ) { // Ersetzen der Schlüsselwörter durch eine leere Zeichenfolge $article->text = preg_replace( $regexpr, '', $article->text ); return true; } /** * Mit der Funktion preg_match_all() werden alle Zeichenfolgen die unserem * Suchmuster entsprechen in einem Array gespeichert. **/ preg_match_all( $regexpr, $article->text, $matches ); // Liefert die Suche kein Ergebnis wird das Plugin regulär beendet if ( !count( $matches[0] ) ) { return true; } // Bereitstellung einiger Objekte und Variablen $user = JFactory::getUser(); $date_format = $pluginParams->get( 'date_format', '%d.%m.%Y' ); // Import der Helper Klasse JLoader::import( 'mod_environment_vars.helper', JPATH_SITE.DS.'modules' ); /** * Unterscheidung zwischen angemeldetem Benutzer oder Gast * * In Abhängigkeit vom Status des Besuchers werden den zu ersetzenden * Platzhaltern aus unserem Text die entsprechenden Informationen * zugewiesen. **/ if ( $user->get( 'guest' ) ) { // Gast $user_vars = array( '{'.$prefix.'id}' => 0, '{'.$prefix.'name}' => 'Gast', '{'.$prefix.'username}' => 'Gast', '{'.$prefix.'email}' => 'mail@domain.tld' ); } else { // Angemeldeter Benutzer $user_vars = array( '{'.$prefix.'id}' => $user->get( 'id' ), '{'.$prefix.'name}' => $user->get( 'name' ), '{'.$prefix.'username}' => $user->get( 'username' ), '{'.$prefix.'email}' => $user->get( 'email' ) ); } // Informationen zum Artikel $article_vars = array( '{'.$prefix.'article_id}' => $article->id, '{'.$prefix.'article_title}' => $article->title, '{'.$prefix.'article_author}' => $article->author, '{'.$prefix.'article_section}' => $article->section, '{'.$prefix.'article_category}' => $article->category ); // Allgemeine Informationen $environment_vars = array( '{'.$prefix.'today}' => JHTML::_( 'date', 'now', $date_format ) ); // Weitere Informationen // Zusammenführen aller Informationen zu einem Array $all_vars = array_merge( $user_vars, $article_vars, $environment_vars ); // $all_keys = array_keys( $all_vars ); /** * Ersetzt die Schlüsselwörter mit den im Plugin * zugewiesenen Daten. **/ $article->text = str_replace( $all_keys, $all_vars, $article->text ); } }
Nachdem im ersten Teil des Plugins einige Abfragen zum Status und Prüfungen auf Vorkommen von gesuchten Schlüsselwörtern gemacht wurden, beginnt mit dem Zuweisen der Werte über die jeweiligen Arrays die eigentliche Funktion.
Nehmen wir einmal an, Sie würden in Ihrem Artikel {ev_today} benutzen. Durch die Zweisung des Rückgabewerts der Klasse JHTML wird nun anhand der übergebenen Formatierung %d.%m.%Y das aktuelle Datum im Array gespeichert. Im weiteren Verlauf wird das Schlüsselwort ersetzt womit wir in unserem Beispiel als Ergebnis die Ausgabe: 17.07.2009 erhalten.
[Bearbeiten] Anpassung
Durch geringe Veränderung des Codes wäre es nun möglich die Ausgabe dieses Datums über das Backend zu formatieren. Erstellen Sie dafür einen weiteren Parameter des Typ text und fügen diesen in die XML Datei ein. Vergessen Sie dabei nicht nötigen Übersetzungen in der Sprachdatei zu notieren.
<params> ... <param name="date_format" type="text" default="" label="Date Format" description="Defining Date Output Format" /> </params>
... DATE FORMAT=Datumsformat DEFINING DATE OUTPUT FORMAT=Geben Sie hier das gewünschte Datumsformat ein.<br /><strong>Beispiel:</strong><br />%A %d.%m.%Y
Als nächstes holen wir uns das Datumsformat aus den Parametern und weisen den Inhalt der Variable $date_format zu. Der zuvor verwendete Standardwert %d.%m.%Y wird nun benutzt um die Variable mit Inhalt zu füllen, sollte der Parameter im Backend nicht gesetzt worden sein.
Um an den Wert des Parameters zu kommen wird der get() Methode des Parameter Objekts der Name des XML Elements übergeben.
// Bereitstellung einiger Objekte und Variablen ... ... $date_format = $pluginParams->get( 'date_format', '%d.%m.%Y' )
Hinweis: Die Darstellung der aktuellen Uhrzeit ist abhängig vom Offset das Sie im Backend eingestellt haben. Es ist eventuell nötig die Zeitzone zu ändern um Sommer- und Winterzeit zu berücksichtigen.
Welche möglichen Formatierungen Ihnen zur Verfügung stehen, sehen sie in der PHP Funktionsreferenz::strftime.
[Bearbeiten] helper.php
Das Artikel Objekt das dem Plugin übergeben wird stellt bereits einige Informationen zur weiteren Verarbeitung bereit. Im Array $article_vars haben wir Daten, wie den Namen des Autors oder den Titel des Artikels zugewiesen. Zusätzlich wollen nun noch eine Link Liste weiterer Artikel des jeweiligen Autors bereitstellen. Die dafür nötigen Methoden finden wir in der zuvor eingebundenen Helper Klasse.
// Import der Helper Klasse JLoader::import( 'mod_environment_vars.helper', JPATH_SITE.DS.'modules' );
<?php /** * @author Joomla!-Nafu * @authorurl http://www.joomla-nafu.de * @Version 1.0 * @license GNU General Public License, http://www.gnu.org/licenses/gpl-2.0.html * * Environment Vars - Joomla! 1.5.x Content Plugin - Replacing Defined Constants With Environment Variables * Copyright (C) 2009 - Joomla!-Nafu * * This program is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License as published by the * Free Software Foundation. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY * or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for * more details. * * You should have received a copy of the GNU General Public License along * with this program; if not, see <http://www.gnu.org/licenses/>. **/ // Standard Überprüfung ob die Datei über das Framework aufgerufen wurde defined( '_JEXEC' ) or die( 'Nah, Joomla! - you know,...' ); // Helper Klasse class plgEnvironmentVarsHelper { /** * * **/ public function todo() { // } }
[Bearbeiten] index.html
Die index.html dient dazu, die Auflistung von Dateien in zusätzlich angelegten Ordnern zu unterbinden.
<html><body bgcolor="#FFFFFF"></body></html>
[Bearbeiten] Ausgabe
Abschließend soll die Ausgabe und Funktionsweise an einigen Beispielen aufgezeigt werden. Hierbei werden alle möglichen Schlüsselbegriffe in einem Artikel notiert und durch das Plugin ersetzt.
[Bearbeiten] Siehe auch
- Das in Joomla! 1.5 enthaltene Beispielplugin (Quellcode; Wichtig: nur mit Joomla! 1.5 verwendbar!)
