Joomla! Documentation™

Joomla! 

3.x

series

La estructura de un plugin para Joomla! 1.5 es muy flexible y potente. Los plugins no sólo se pueden utilizar para controlar eventos lanzados por el núcleo de la aplicación y extensiones, también pueden ser utilizados para extender extensiones de terceros y hacerlas más potentes. El cambio principal de las series Joomla! 1.5 a 2.5/3.x fue el cambio en los nombres de los eventos.

Esto debe proveerte los conceptos básicos sobre lo que necesitas saber para desarrollar tu propio plugin. La mayoría de los plugins consisten en un único archivo de código, pero para instalar correctamente el plugin debe ser empaquetado en un archivo de instalación que pueda ser procesados el instalador de Joomla!.

Crear el Archivo de Instalación

Como con todas las extensiones en Joomla!, los plugins se instalan fácilmente como un archivo .zip (.tar.gz también es compatible), pero un archivo XML con el formato correcto debe ser incluido. Como ejemplo, aquí está el archivo de instalación XML para el plugin de búsqueda de categorías.

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

Como se puede ver, el sistema es similar al de los archivos XML de instalación de Joomla!. Sólo tienes que prestar atención a la entrada group="xxx" en la etiqueta <extension> y la información extendida en la etiqueta <filename>. Esta información le dice a Joomla! en que carpeta se debe copiar el archivo y a que grupo se debe agregar el plugin.

Si vas a crear un plugin que responda a los eventos centrales existentes, el atributo group="xxx" debería ser cambiado para reflejar el nombre de la carpeta plugins existentes para el tipo de evento que desea aumentar. Por ejemplo, group="authentication" o group="user". Ver Plugin/Eventos para una lista completa de las categorías de eventos del núcleo. En la creación de un nuevo plugin para responder a los eventos del núcleo es importante que el nombre de tu plugin sea único y no entre en conflicto con alguno de los otros plugins que también puede responder a eventos del núcleo en caso que desees el servicio.

Si va a crear un plugin para responder a un sistema de eventos que no son del núcleo la elección de la etiqueta group="xxx" debe ser diferente a cualquiera de las categorías del núcleo.

Consejo Si se agrega el atributo method="upgrade" a la etiqueta extension, este plugin puede ser instalado sin desinstalar una versión anterior. Todos los archivos existentes se sobrescribirán, pero los archivos antiguos no serán eliminados.

Crear el Plugin

La forma de escribir plugins, orientada a objetos, implica la escritura de una subclase de JPlugin, una clase base que implementa las propiedades básicas de los plugins. En sus métodos, las propiedades siguientes están disponibles:

• $this->params: los parametros establecidos para este plugin por el administrador
• $this->_name: el nombre del plugin
• $this->_type: el grupo (tipo) del plugin
• $this->db: el objeto db (desde )
• $this->app: el objeto aplicación (desde )

Consejo Para usar $this->db y $this->app, JPlugin comprueba si la propiedad existe y no es privada. Si deseas que los objetos se puedan usar de forma predeterminada, crear o no crear instancias de propiedades en el plugin de clase (por ej.: protected $db; protected $app; en la misma área como protected $autoloadLanguage = true;). Las propiedades no van a existir a menos que explícitamente sean creadas.

En el ejemplo de código siguiente <PluginGroup> representa el grupo (tipo) del plugin, y <PluginName> representa su nombre. Ten en cuenta que la clase y los nombres de función en PHP no diferencian mayúsculas de minúsculas. El nombre debe corresponder con el atributo plugin del elemento filename en la configuración XML que apunta al archivo php del complemento.

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

El uso de Plugins en tu Código

Ahora que has creado tu plugin, probablemente vas a querer llamarlo en tu código. Podría ser que no: el núcleo de Joomla! tiene una serie de eventos incorporados que es posible que desees registar en el código de tu plugin. En este caso no necesitas hacer lo siguiente.

Si desea lanzar un evento, utiliza un código como este:

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

Es importante tener en cuenta que los parámetros tienen que estar en un array. La función del plugin en sí va a obtener los valores de los parámetros como valores individuales. El valor de retorno se compone de un array de valores con el retorno de los diferentes plugins (por lo que también puede contener arrays multinivel).

Si va a crear un plugin para un nuevo evento, que no es del núcleo, recuerda activar el plugin después de instalarlo. Preceder cualquier referencia a tu nuevo plugin con el comando JPluginHelper::importPlugin().