Joomla! Documentation™

Joomla! 

3.x

serie

De plugin structuur voor Joomla! 1.5 was erg flexibel en krachtig. Niet alleen kunnen plugins worden gebruikt voor het verwerken van gebeurtenissen die worden geactiveerd door de core-toepassing en extensies, maar plugins kunnen ook worden gebruikt om extensies van derde partij uitbreidbaar en krachtig te maken. De voornaamste wijziging van Joomla! 1.5 naar de 2.5/3.x serie was de verandering van de naam van gebeurtenissen.

Deze hoe-moet-ik voorziet u van de basis van wat u moet weten om een eigen plugin te ontwikkelen. De meeste plugins bestaan uit slechts één enkel code-bestand maar om de plugin juist te installeren moet het opgenomen zijn in een installatiebestand welke verwerkt kan worden door de Joomla! installer.

Het installatiebestand aanmaken

Zoals alle extensies in Joomla, worden plugins makkelijk geïnstalleerd als .zip bestand (.tar.gz wordt ook ondersteund) maar er moet een juist geformatteerd XML bestand in zitten. Als voorbeeld is hier het XML installatiebestand van de categorie zoek 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>

Zoals u kunt zien is het systeem gelijk aan andere Joomla! XML installatiebestanden. U hoeft alleen maar te kijken naar de group="xxx" code binnen de <extension> tag en de uitgebreide informatie in de <filename> tag. Deze informatie verteld Joomla! in welke map het bestand gekopieerd moet worden en aan welke groep de plugin toegevoegd moet worden.

Als u een plugin maakt die reageert op bestaande events (gebeurtenissen), dan moet het group="xxx" attribuut veranderd worden om aan de naam te voldoen van de bestaande plugin map van het gebeurtenis type dat u wilt uitbreiden. Bijvoorbeeld group="authentication" of group="user". Zie Plugin/Events voor een complete lijst van bestaande core event-categorieën. Bij het aanmaken van een nieuwe plugin om te reageren op core events is het belangrijk dat uw plugin naam uniek is en niet conflicteert met een van de andere plugins die ook reageren op het core event dat u wilt gebruiken.

Als u een plugin maakt die moet reageren op niet-core systeem events, dan moet uw keuze voor de group="xxx" tag anders zijn als één van de bestaande core categorieën.

Tip Als u het attribute method="upgrade" toevoegt aan de tag extension, dan kan deze plugin geïnstalleerd worden zonder een eerdere versie te deïnstalleren. Alle bestaande bestanden worden overschreven, maar oude bestanden worden niet verwijderd.

Het maken van de plugin

De object georiënteerde manier om plugins te schrijven gaat via het schrijven van een subclass van JPlugin, als basis class die de basis eigenschappen van plugins implementeert. In uw methodes zijn de volgende eigenschappen beschikbaar:

• $this->params: de parameters ingesteld voor deze plugin door de beheerder
• $this->_name: de naam van de plugin
• $this->_type: de groep (type) van de plugin
• $this->db: het db object (sinds )
• $this->app: het application object (sinds )

Tip JPlugin test om $this->db en $this->app te gebruiken, of de eigenschap bestaat en niet private is. Maak. als gewenst is dat het standaard object gebruikt wordt, een niet-geïnstantieerde eigenschappen in de plugin class (bijvoorbeeld protected $db; protected $app; in hetzelfde gebied als protected $autoloadLanguage = true;). De eigenschappen bestaan niet behalve als ze expliciet aangemaakt zijn.

In het volgende code voorbeeld, vertegenwoordigt <PluginGroup> de groep (type) van de plugin en <PluginName> vertegenwoordigt zijn naam. Let op dat class- en functienamen in PHP hoofdlettergevoelig zijn. De naam moet overeenkomen met het plugin attribuut van het filename element in de XML configuratie die wijst naar het plugin php bestand.

<?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;
	}
}
?>

Het gebruik van plugins in uw code

Nu u uw plugin heeft gemaakt, wilt u het waarschijnlijk aanroepen vanuit uw code. Het hoeft niet: de Joomla! core heeft een aantal ingebouwde events waaraan u uw plugin-code wilt koppelen. In dat geval hoeft u het volgende niet te doen.

Als u een event wilt activeren, gebruik dan code zoals deze:

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

Het is belangrijk er op te letten dat de parameters een array moeten zijn. De plugin functie zelf krijgt de parameters als een enkele waarden. De return-waarde bestaat uit een array met return-waardes vanuit de verschillende plugins (het kan dus ook multilevel arrays bevatten).

Denk eraan, als u een plugin maakt voor een nieuw, niet-core event, om uw plugin te activeren na het te installeren. Laat elke referentie naar uw nieuwe plugin voorafgaan door het JPluginHelper::importPlugin() commando.