Сайт справки

J3.x:Создание плагина для Joomla

Система плагинов в Joomla! 1.5 была очень мощной и гибкой. Плагины можно использовать не только для обработки событий, вызванных ядром приложения и его расширениями, но и для того, чтобы сделать сторонние дополнения более мощными и расширяемыми. Изменения в Joomla! 2.5/3.x в отличие от 1.5 в основном касаются имен событий.

В этом руководстве описаны основы разработки своего плагина. Большинство плагинов состоит из одного файла с кодом, но для правильной установки он должен быть упакован в установочный файл, который будет обработан установщиком Joomla!.

Создание установочного файла

Как и любые расширения для Joomla, плагины легко устанавливаются в виде .zip файлов (.tar.gz тоже поддерживается), но архив должен содержать правильно составленный XML файл. Вот пример XML файла для плагина поиска по категориям.

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

Как можно заметить, он похожа на другие инсталляционные XML файлы для Joomla!. Нужно только обратить внимание на запись group="xxx" в разделе <extension>, а также на дополнительную информацию в разделе <filename> . Эта информация сообщает Joomla!, в какую папку копировать файл и в какую группу будет добавлен плагин.

Если вы создаете плагин, который реагирует на существующие события ядра, атрибут group="xxx" должен быть изменен в соответствии с именем уже существующей папки для события, которое вы хотите использовать. Например, group="authentication" or group="user". Смотрите Plugin/Events полный список существующих категорий событий. При создании нового плагина важно, чтобы его название было уникальным, и чтобы он не конфликтовал с уже существующими плагинами, которые могут реагировать на то же событие, какое используете вы.

Если вы создаете плагин реагировать на неосновные системные события вашего выбора для группы="ХХХ" тег должен отличаться от любого из существующих базовых категорий.

Совет: если вы добавляете атбибут method="upgrade" к тэгу extension, то плагин можно будет устанавливать без удаления предыдущей версии. Все существующие файлы будут перезаписаны, но оставшиеся файлы удалены не будут..

Создание плагинов

Объектно-ориентированный подход к написанию плагинов включает в себя создание подклассов от JPlugin, базового класса, реализующего основные свойства плагинов. Для ваших методов доступны следующие свойства:

  • $this->params: Параметры, установленные для этого плагина администратором
  • $this->_name: имя плагина
  • $this->_type: группа (тип) плагина
  • $this->db: объект базы данных (от Joomla 3.1)
  • $this->app: объект приложения (от Joomla 3.1)

В следующем примере <PluginGroup> представляет группу (тип) плагина, а <PluginName> его название. Обратите внимание, что имена класса и функции в PHP не чувствительны к регистру.

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

Использования плагинов в коде

Теперь, когда вы создали свой плагин, то вам наверняка захочется его вызвать. Но необязательно, ядро Joomla! имеет набор встроенных событий, которые вы пожете использовать для запуска плагина. Тогда нижеописанное делать не нужно:

Чтобы запустить событие, используйте следующий код:

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

Важно отметить, что параметры должны передаваться в массиве. Функция же в плагине будет получить параметры как отдельные значения. Возвращаемое значение будет состоять из массив возвращаемых значений из разных плагинов (поэтому он также может содержать многоуровневые массивы). Возвращаться будет массив значений из разных плагинов (этот массив может быть многоуровневым).

Если вы создаете плагин для нового события, а не для встроенного события ядра. то не забудьте активировать плагин после установки. Перед ссылкой на ваш новый плагин должна стоять команда JPluginHelper::importPlugin().

Наверх

© Сайт справки 2024