Tekst źródłowy strony Użytkownik:Robertm/Brudnopis

{{wersja/poradnik|2.5}}

Konstrukcja wtyczki w Joomla! 1.5 była bardzo elastyczna i wydajna. Pozwalała nie tylko na obsługę zdarzeń wywoływanych przez standardowe rozszerzenia oraz aplikacje, ale również na zwiększanie możliwości rozszerzeń dostarczanych przez osoby trzecie. Główne zmiany, jakie zaszły w dodatkach dla wersji Joomla! 1.5 a 2.5/3.x dotyczą nazw zdarzeń. 

Poradnik ten powinien dostarczyć ci podstawowych informacji potrzebnych do stworzeni własnej wtyczki. Większość wtyczek składa się z pojedynczego pliku z kodem, ale aby zapewnić możliwość poprawnej instalacji dodatku, musimy zamieścić w jego paczce plik instalacyjny, który zostanie zinterpretowany przez instalator Joomla!

=== Tworzenie pliku instalacyjnego ===
Tak jak wszystkie rozszerzenia Joomla!, wtyczki są instalowane za pomocą archiwów .zip (lub .tar.gz) z poprawnie skonstruowanym plikiem XML. Poniższy przykład przedstawia plik instalacyjny wtyczki wyszukiwarki kategorii.

<source lang="xml">
<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" 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>


Jak można zauważyć, plik instalacyjny wtyczki, jest podobny do innych tego typu plików w rozszerzeniach Joomla! Uwagę należy zwrócić na fragment kodu <code>group="xxx"</code> zamieszczony w tagach <code><extension></code> oraz na dodatkowe informacje w sekcji <code><filename></code>. Informacje te wskazują systemowi Joomla!, z jaką grupą wtyczki ma do czynienia i w jakim folderze powinien ją umieścić. 

Jeśli tworzysz wtyczkę, która odpowiada na podstawowe zdarzenia, atrybut <code>group="xxx"</code> powinien zawierać nazwę istniejącego folderu wtyczki dla typu zdarzenia, które chcesz rozszerzyć, np. <code>group="authentication"</code> lub <code>group="user"</code>.
 
Przeczytaj [http://docs.joomla.org/Plugin/Events Events], by zobaczyć listę kategorii podstawowych zdarzeń. Gdy tworzymy dodatek obsługujący podstawowe zdarzenia, ważne jest, by nasza wtyczka miała unikalną nazwę, co zapobiegnie konfliktom z innymi wtyczkami, które mogą próbować obsłużyć to samo zdarzenie.

Jeśli tworzysz dodatek obsługujący niestandardowe zdarzenia, powinieneś  w sekcji <code>group="xxx"</code> umieścić nazwę kategorii zdarzeń, która nie będzie się dublowała z nazwami już istniejących.

'''Wskazówka'''. Jeśli dodasz atrybut <code>method="upgrade"</code> w sekcji <code>extension</code>, dodatek zostanie zainstalowany, bez odinstalowywania wcześniejszej wersji. Wszystkie istniejące pliki wtyczki, które są dołączone do paczki instalacyjnej, zostaną nadpisane, a te których  paczce nie uwzględniono, pozostaną nienaruszone.

=== Tworzenie dodatku ===
Zorientowany obiektowo sposób pisania wtyczki, polega na stworzeniu podklasy [http://api.joomla.org/cms-3/classes/JPlugin.html JPlugin], która jest klasą bazową implementującą podstawowe właściwości wtyczek. W swoich metodach, udostępnia następujące własności:

* <code>$this->params</code>: zbiór [[Parametry| parametrów]] dodatku, zdefiniowany przez administratora
* <code>$this->_name</code>: nazwa dodatku
* <code>$this->_type</code>: grupa (typ) dodatku


W poniższym przykładzie sekcja <code><PluginGroup></code> reprezentuje grupę (typ) dodatku. Natomiast sekcja  <code><PluginName></code> odnosi się do nazwy wtyczki. Należy pamiętać, że w klasach i funkcjach PHP, wielkość liter ma znaczenie.

<source lang="php">
<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );

class plg<PluginGroup><PluginName> extends JPlugin
{
/**
 * Constructor - note in Joomla 2.5 PHP4.x is no longer supported so we can use this.
 *
 * @access      protected
 * @param       object  $subject The object to observe
 * @param       array   $config  An array that holds the plugin configuration
 */
public function __construct(& $subject, $config)
{
	parent::__construct($subject, $config);
	$this->loadLanguage();
}
/**
 * Plugin method with the same name as the event will be called automatically.
 */
 function <EventName>()
 {
    $app = JFactory::getApplication();

        // Plugin code goes here.
        // You can access parameters via $this->params.
    return true;
 }
}
?>
</source>

=== Korzystanie z dodatków w kodzie ===
Teraz, gdy twoja wtyczka jest już utworzona, prawdopodobnie chcesz ją wywołać w kodzie. Nie musisz. Rdzeń Joomla! posiada szereg wbudowanych zdarzeń, które zarejestrują twoją wtyczkę. Z tego powodu nie ma potrzeby robić tego osobiście.

Jeśli chcesz wywołać zdarzenie, użyj poniższego kodu:

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

Należy pamiętać, by parametry były podane w postaci tablicy. Funkcja wtyczki automatycznie odczyta parametry z tablicy, jako pojedyncze wartości. Zwracana wartość będzie składać się z tablicy wartości, zwracanych z różnych wtyczek (może więc zawierać wielopoziomowe tablice).

Jeśli utworzyłeś nowy dodatek, pamiętaj, by po jego zainstalowaniu, aktywować go. Każdą referencję do nowej wtyczki należy poprzedzać poleceniem <code>JPluginHelper::importPlugin()</code>.

{{Źródło|http://docs.joomla.org/J2.5:Creating_a_Plugin_for_Joomla|Wilsonge}}
{{Tłumacz|Robertm}}