Difference between revisions of "Creating a Plugin for Joomla/zh-tw"

Latest revision as of 20:58, 27 January 2021

 外掛的結構就相當彈性並且有力，不僅能夠透過核心應用以及擴充套件來處理觸發的事件，還可以使用來提昇第三方擴充套件的功能。從 過渡到 / 系列，主要的更動是事件的命名。

這個說明問件應該會提供您，開發外掛最基本需要了解的內容。大多數的外掛僅由一個程式碼檔案組成，但是如果要正確安裝這個外掛程式，還得把檔案包裝到安裝器，讓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中，這個外掛在安裝，時會跳過解除安裝先前版本的動作。所有重複的資料會被覆寫，但是不會刪除舊的檔案。

Creating the Plugin

The object-oriented way of writing plugins involves writing a subclass of JPlugin, a base class that implements the basic properties of plugins. In your methods, the following properties are available:

• $this->params: the parameters set for this plugin by the administrator
• $this->_name: the name of the plugin
• $this->_type: the group (type) of the plugin
• $this->db: the db object (since )
• $this->app: the application object (since )

Tip To use $this->db and $this->app, JPlugin tests if the property exists and is not private. If it is desired for the default objects to be used, create un-instantiated properties in the plugin class (i.e. protected $db; protected $app; in the same area as protected $autoloadLanguage = true;). The properties will not exist unless explicitly created.

In the following code example, <PluginGroup> represents the group (type) of the plugin, and <PluginName> represents its name. Note that class and function names in PHP are case-insensitive. The name must correspond with the plugin attribute of the filename element in the XML configuration that points at the plugin php file.

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

Using Plugins in Your Code

Now that you've created your plugin, you will probably want to call it in your code. You might not: the Joomla! core has a number of built-in events that you might want your plugin code to be registered to. In that case you don't need to do the following.

If you want to trigger an event then you use code like this:

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

It is important to note that the parameters have to be in an array. The plugin function itself will get the parameters as single values. The return value will consist of an array of return values from the different plugins (so it can also contain multilevel arrays).

If you are creating a plugin for a new, non-core event, remember to activate your plugin after you install it. Precede any reference to your new plugin with the JPluginHelper::importPlugin() command.