Joomla! Documentation™

Joomla! 

3.x

Serie

Die Pluginstruktur für Joomla! 1.5 war sehr flexibel und mächtig. Plugins können nicht nur verwendet werden um Events, die durch die Hauptanwendung und durch Erweiterungen ausgelöst wurden, zu verarbeiten, sondern auch, um Erweiterungen von Drittanbietern erweiterbar und leistungsfähig zu gestalten. Die wichtigste Änderung von Joomla! 1.5 auf die 2.5/3.x-Serie war die Änderung der Namen der Events.

Diese Anleitung soll mit den Grundlagen vertraut machen, die man für die Entwicklung eines eigenen Plugins benötigt. Die meisten Plugins bestehen nur aus einer einzigen Code-Datei. Um es allerdings richtig zu installieren, muss der Plugin-Code in eine Installationsdatei gepackt werden, die vom Joomla! Installer verarbeitet werden kann.

Erstellen der Installationsdatei

Wie bei allen Erweiterungen in Joomla können Plugins einfach als .zip-Datei installiert werden (.tar.gz wird ebenfalls unterstützt). Es muss jedoch eine korrekt formatierte XML-Datei enthalten sein. Als Beispiel ist hier die XML-Installationsdatei für das Kategorien-Such-Plugin.

<?xml version="1.0" encoding="utf-8"?>
<extension version="3.1" type="plugin" group="search">
	<name>plg_search_categories</name>
	<author>Joomla! Project</author>
	<creationDate>November 2005</creationDate>
	<copyright>Copyright (C) 2005 - 2013 Open Source Matters. All rights reserved.</copyright>
	<license>GNU General Public License version 2 or later; see LICENSE.txt</license>
	<authorEmail>admin@joomla.org</authorEmail>
	<authorUrl>www.joomla.org</authorUrl>
	<version>3.1.0</version>
	<description>PLG_SEARCH_CATEGORIES_XML_DESCRIPTION</description>
	<files>
		<filename plugin="categories">categories.php</filename>
		<filename>index.html</filename>
	</files>
	<languages>
		<language tag="en-GB">en-GB.plg_search_categories.ini</language>
		<language tag="en-GB">en-GB.plg_search_categories.sys.ini</language>
	</languages>
	<config>
		<fields name="params">

			<fieldset name="basic">
				<field name="search_limit" type="text"
					default="50"
					description="JFIELD_PLG_SEARCH_SEARCHLIMIT_DESC"
					label="JFIELD_PLG_SEARCH_SEARCHLIMIT_LABEL"
					size="5"
				/>

				<field name="search_content" type="radio"
					default="0"
					description="JFIELD_PLG_SEARCH_ALL_DESC"
					label="JFIELD_PLG_SEARCH_ALL_LABEL"
				>
					<option value="0">JOFF</option>
					<option value="1">JON</option>
				</field>

				<field name="search_archived" type="radio"
					default="0"
					description="JFIELD_PLG_SEARCH_ARCHIVED_DESC"
					label="JFIELD_PLG_SEARCH_ARCHIVED_LABEL"
				>
					<option value="0">JOFF</option>
					<option value="1">JON</option>
				</field>
			</fieldset>

		</fields>
	</config>
</extension>

Wie du sehen kannst, ähnelt der Aufbau anderen Joomla! XML-Installationsdateien. Achte nur auf den Eintrag group="xxx" im Tag <extension> und die erweiterten Informationen im Tag <filename>. Die Informationen sagen Joomla!, in welchen Ordner die Datei kopiert werden soll und zu welcher Gruppe von Plugins es hinzugefügt werden soll.

Falls ein Plugin erstellt wird, das auf bestehende Kern-Events reagiert, würde sich das Attribut group="xxx" ändern, um die Bezeichnung des bestehenden Pluginordners für den Ereignistypen, den man zu erweitern wünscht, wiederzugeben. Beispielsweise group="Authentifizierung" oder group="User". Beachte auch Plugin/Events für eine vollständige Liste von bestehenden Kategorien von Kern-Events. Bei der Erstellung eines neuen Plugins, welches auf Kern-Events reagiert, ist es wichtig, dass der Pluginname eindeutig ist. Er darf nicht mit irgendeinem der anderen Plugins kollidieren, die ebenfalls auf das entsprechende Kern-Event reagieren können.

Falls man jedoch ein Plugin erstellt, das auf System-Events außerhalb des Joomla-Kerns reagiert, sollte sich die Wahl des Tags group="xxx" von den bestehenden Kernkategorien unterscheiden.

Tipp: Wird das Attribut method="upgrade" dem Tag extension hinzugefügt, kann dieses Plugin installiert werden, ohne eine vorherige Version entfernen zu müssen. Alle bestehenden Dateien werden überschrieben, aber alte Dateien werden nicht gelöscht.

Das Plugin erstellen

Die objekt-orientierte Vorgehensweise zur Erstellung von Plugins erfordert das Erstellen einer Unterklasse von JPlugin. Das ist eine Grundlagenklasse, welche die grundlegenden Eigenschaften von Plugins umsetzt. In den Methoden sind die folgenden Eigenschaften verfügbar:

• $this->params: die Parameter, die durch den Administrator für das Plugin gesetzt werden
• $this->_name: der Name des Plugins
• $this->_type: die Gruppe (Typ) des Plugins
• $this->db: das db-Objekt (seit )
• $this->app: das Applikations-Objekt (since )

Tipp Bei Verwendung von $this->db und $this->app, testet JPlugin, ob die Eigenschaft existiert und nicht privat ist. Wenn die Standardobjekte verwendet werden sollen, müssen nicht-instanziierte Eigenschaften in der Plugin-Klasse (d. h. protected $db; protected $app; im gleichen Bereich wie protected $autoloadLanguage = true;) erstellt werden. Die Eigenschaften werden nicht existieren, es sei denn, sie werden explizit erstellt.

Im folgenden Code-Beispiel steht <PluginGroup> für die Gruppe (type) des Plugins, und <PluginName> für seinen Namen. Es sollte beachtet werden, dass Klassen- und Funktionsnamen in PHP die Groß-/Kleinschreibung nicht berücksichtigen. Der Name muss mit dem plugin-Attribut des filename-Elements in der XML-Konfiguration übereinstimmen, das auf die Plugin-php-Datei zeigt.

<?php
// no direct access
defined( '_JEXEC' ) or die;

class plg<PluginGroup><PluginName> extends JPlugin
{
	/**
	 * Load the language file on instantiation. Note this is only available in Joomla 3.1 and higher.
	 * If you want to support 3.0 series you must override the constructor
	 *
	 * @var    boolean
	 * @since  3.1
	 */
	protected $autoloadLanguage = true;

	/**
	 * Plugin method with the same name as the event will be called automatically.
	 */
	 function <EventName>()
	 {
		/*
		 * Plugin code goes here.
		 * You can access database and application objects and parameters via $this->db,
		 * $this->app and $this->params respectively
		 */
		return true;
	}
}
?>

Plugins im Code verwenden

Nach der Erstellung eines neuen Plugins soll es wahrscheinlich im Programmcode aufgerufen werden. Hinweis: Der Joomla! Kern enthält eine Vielzahl von eingebauten Events, für welche der neue Plugincode vielleicht registriert werden soll (in diesem Fall kann der folgende Abschnitt ignoriert werden).

Wenn ein Event ausgelöst werden soll, kann folgender Code verwendet werden:

$dispatcher = JDispatcher::getInstance();
$results = $dispatcher->trigger( '<EventName>', <ParameterArray> );

Es ist wichtig zu beachten, dass die Parameter in einem Array vorliegen müssen. Die Plugin-Funktion selbst wird die Parameter als Einzelwerte erhalten. Der Rückgabewert wird aus einem Array von Rückgabewerten der verschiedenen Plugins bestehen (kann also auch mehrstufige Arrays enthalten).

Falls ein Plugin für ein neues, den Kern nicht betreffendes Event erstellt wird, muss das Plugin nach der Installation aktiviert werden. Vor jedem Bezug auf ein neues Plugin sollte die Anweisung JPluginHelper::importPlugin() verwendet werden.