Joomla! Documentation™

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) (之後)
• $this->app: 應用程序物件 (之後)

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

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

<?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() 指令。