J3.x

建立一個 Joomla! 外掛

From Joomla! Documentation

This page is a translated version of the page J3.x:Creating a Plugin for Joomla and the translation is 100% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎Nederlands • ‎português • ‎русский • ‎中文(台灣)‎
Joomla! 
3.x
系列
Joomla 1.5 外掛的結構就相當彈性並且有力,不僅能夠透過核心應用以及擴充套件來處理觸發的事件,還可以使用來提昇第三方擴充套件的功能。從 Joomla 1.5過渡到 Joomla 2.5/ Joomla 3.x系列,主要的更動是事件的命名。

這個說明問件應該會提供您,開發外掛最基本需要了解的內容。大多數的外掛僅由一個程式碼檔案組成,但是如果要正確安裝這個外掛程式,還得把檔案包裝到安裝器,讓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>

如您所見,整個檔案看起來很類似其他的 Joomla! XML 安裝檔案。您只需要找到 <extension> 標籤中的 group="xxx",以及 <filename> 標籤中的擴充套件資訊。這些資訊會告訴 Joomla!要把檔案複製到哪些資料夾中,以及增加外掛到哪些群組。

如果說您正在建立一個外掛,來回應現有的核心事件,group="xxx"屬性要被改寫,以配合現有外掛資料夾中,您想要新增的事件類型,例如,group="authentication" 或是 group="user"。請見外掛/事件(event)來獲得完整的核心事件類別。要建立新的外掛,來回應核心事件,很重要的事情是,外掛的名稱必須是獨一無二的,不要與任何其他的外掛衝突,它們可能也會回應核心事件。

如果您正在建立外掛來回應非核心系統事件,依據您選擇的group="xxx"標籤。請記得標籤內容不要與現有的核心類別名稱一樣。

小撇步 如果您增加了屬性 method="upgrade" 到標籤 extension中,這個外掛在安裝,時會跳過解除安裝先前版本的動作。所有重複的資料會被覆寫,但是不會刪除舊的檔案。

建立外掛

要用物件導向的方式來撰寫外掛,需要建立一個 JPlugin底下的子類別(subclass),JPlugin 是基礎類別,會執行基本的外掛參數屬性,再您的方法(methods)中,以下的屬性是可用的:

  • $this->params: 管理員介面的外掛屬性
  • $this->_name: 外掛的命名
  • $this->_type: 外掛的群組 (類型)
  • $this->db: 資料庫物件(db object) (Joomla 3.1之後)
  • $this->app: 應用程序物件 (Joomla 3.1之後)

小撇步 要使用 $this->db 以及 $this->appJPlugin 會測試屬性是否存在,而且不是私有的(private)。如果想要讓預設物件能夠使用,那麼建立請在外掛class 中建立非實例化的屬性 (也就是protected $db; protected $app;protected $autoloadLanguage = true; 相同的位置)。除非屬性明確地被建立,否則屬性不會存在。

在以下示範的程式碼中,<PluginGroup>代表著外掛的群組 (類型) ,而<PluginName>代表著外掛的名稱。請注意在PHP中, class 和function的命名是大小寫有差別的。命名必須符合XML設定值中, filenameplugin 元素屬性。

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

在程式當中使用外掛

現在您已經建立好您的外掛,您可能會想要在程式碼中呼叫它。You might not: Joomla! 核心有一些預備好的事件,是您的外掛程式可能會用來註冊的。如果是這樣的話,您不需要做以下的動作。

如果您想要觸發一個事件,您需要使用像這樣的程式碼:

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

重要的是要記得,要把屬性放在陣列中,外掛的function會獲得屬性,當成一個單獨的值。回傳的值會由從其他外掛來的回傳值陣列組成(所以它也可以包含多個層級的陣列)。

如果您正要建立一個新的、非核心的外掛,請記得在安裝之後要啟用。在您的新外掛中,所有的reference之前要有 JPluginHelper::importPlugin() 指令。