View source for Creating a Plugin for Joomla/ru

<noinclude><languages /></noinclude>
<noinclude>{{Joomla version|version=3.x|comment=series}}</noinclude>
Система плагинов в Joomla! 1.5 была очень мощной и гибкой. Плагины можно использовать не только для обработки событий, вызванных ядром приложения и его расширениями, но и для того, чтобы сделать сторонние дополнения более мощными и расширяемыми. Изменения в Joomla!  2.5/3.x в отличие от 1.5 в основном касаются имен событий.

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

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

<source lang="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>
</source>

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

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

Если вы делаете плагин, которые будет реагировать не на системные события ядра, то тег <code>group="xxx"</code> должен отличаться от существующих базовых категорий ядра.

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

=== Создание плагинов ===
Объектно-ориентированный подход к написанию плагинов включает в себя создание подклассов от [http://api.joomla.org/Joomla-Platform/Plugin/JPlugin.html JPlugin], базового класса, реализующего основные свойства плагинов. Для ваших методов доступны следующие свойства:

* <code>$this->params</code>: the [[S:MyLanguage/Parameter|parameters]] set for this plugin by the administrator
* <code>$this->_name</code>: имя плагина
* <code>$this->_type</code>: группа (тип) плагина
* <code>$this->db</code>: объект базы данных (since {{JVer|3.1}})
* <code>$this->app</code>: объект приложения (since {{JVer|3.1}})

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

<source lang="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;
	}
}
?>
</source>

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

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

<source lang="php">
$dispatcher = JDispatcher::getInstance();
$results = $dispatcher->trigger( '<EventName>', <ParameterArray> );
</source>

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

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

<noinclude>
[[Category:Tutorials]]
[[Category:Plugin Development]]
</noinclude>