--=REKLAMA=--

J3.5

Tworzenie dodatku dla Joomla

Z Joomla!WikiPL

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.

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


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 group="xxx" zamieszczony w tagach <extension> oraz na dodatkowe informacje w sekcji <filename>. 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 group="xxx" powinien zawierać nazwę istniejącego folderu wtyczki dla typu zdarzenia, które chcesz rozszerzyć, np. group="authentication" lub group="user".

Przeczytaj 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 group="xxx" umieścić nazwę kategorii zdarzeń, która nie będzie się dublowała z nazwami już istniejących.

Wskazówka. Jeśli dodasz atrybut method="upgrade" w sekcji extension, 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 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:

  • $this->params: zbiór parametrów dodatku, zdefiniowany przez administratora
  • $this->_name: nazwa dodatku
  • $this->_type: grupa (typ) dodatku
  • $this->db: obiekt bazy danych (od Joomla 3.1)
  • $this->app: obiekt aplikacji (od Joomla 3.1)

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

<?php
// no direct access
defined( '_JEXEC' ) or die( 'Restricted access' );
 
class plg<PluginGroup><PluginName> extends JPlugin
{
	/**
	 * Wczytywanie instancji pliku językowego. Własność dostępna od wersji Joomla 3.1.
	 * Jeśli chcesz jej użyć we wcześniejszych wersjach, musisz nadpisać konstruktor klasy
	 *
	 * @var    boolean
	 * @since  3.1
	 */
	protected $autoloadLanguage = true;
 
	/**
	 * Metoda dodatku nazwana tak samo jak zdarzenie, zostanie wywołana automatycznie.
	 */
	 function <EventName>()
	 {
		/*
		 * Tutaj kod wtyczki.
		 * Dostęp do bazy danych można, obiektu aplikacji oraz parametrów można uzyskać odpowiednio 
                 * za pomocą $this->db, $this->app i $this->params
		 */
		return true;
	}
}
?>

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:

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

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 JPluginHelper::importPlugin().

© Ten materiał jest dokładnym albo swobodnym tłumaczeniem artykułu http://docs.joomla.org/J3.2:Creating_a_Plugin_for_Joomla udostępnionego na licencji JEDL na witrynie: Oficjalnej dokumentacji Joomla!.Pierwszy autor oryginału: Wilsonge.
© Tłumaczenie: Robertm. Tłumaczenie wykonano na warunkach licencji JEDL.