Joomla! 外掛開發教學 - Plugin tutorial & sketch files

Written by Simon Asika on

在 Joomla! 2.5 以後，開發 plugin 主要需要兩個檔案。一個是外掛主檔(php)，另一個是安裝資訊檔(xml)。只要有這兩者即可成為一個可運作的外掛。其他語系檔或者附加檔案可在自行加上去。

首先從 xml 檔開始

<?xml version="1.0" encoding="utf-8"?>
<extension version="2.5" type="plugin" group="folder" method="upgrade">
    <name>plg_folder_example</name>
    <author>Asika</author>
    <creationDate>2013-09-08</creationDate>
    <copyright>Copyright (C) 2013 Asikart.com</copyright>
    <license>GNU General Public License version 2 or later; see LICENSE.txt</license>
    <authorEmail>asika@asikart.com</authorEmail>
    <authorUrl>http://asikart.com</authorUrl>
    <version>1.0</version>
    <description>PLG_FOLDER_EXAMPLE_XML_DESCRIPTION</description>


    <files>
        <filename plugin="example">example.php</filename>
    </files>

    <config>
        <fields name="params">

            <fieldset name="basic">

                <field name="field1" type="text"
                    description="PLG_FOLDER_EXAMPLE_FIELD1_DESC"
                    label="PLG_FOLDER_EXAMPLE_FIELD1_LABEL"
                />

            </fieldset>

        </fields>
    </config>

</extension>

將xml內的所有example代換成你的plugin名稱，folder代換成plugin的群組名稱（例如system或content）。

files 中的 plugin="example" 請全部小寫，example.php 則是外掛主檔案的名稱，同樣小寫。

之後的<config>請依照 Joomla! config 規則來寫，這部份代表了你在後台可以編輯的選項。而label, description 兩個項目是可以被語系檔取代的。

外掛主檔案

<?php

// no direct access
defined('_JEXEC') or die;

jimport('joomla.plugin.plugin');

class plgFolderExample extends JPlugin
{
    public function __construct(&$subject, $config)
    {
        parent::__construct( $subject, $config );

        // Load plugin language in front-end
        $this->loadLanguage();
    }

    public function onContentPrepare($context, &$article, &$params, $page = 0) {

        //how to get params
        $param_p1 = $this->params->get('p1','default');

        //Your plugin code.

    }
}

依照命名原則代換Folder與Example。若外掛在前台有需要語系檔，則需要一個 __constructor() ，並載入語系。若不需要，其實 constructor 可以省略。

function onContentPrepare() 可以代換成你想要的任何Joomla! Event.

Joomla! Events

Authentication

  • onUserAuthenticate

Captcha

  • onInit
  • onDisplay
  • onCheckAnswer

Content

  • onContentPrepare
  • onContentAfterTitle (Joomla 3.x only)
  • onContentBeforeDisplay
  • onContentAfterDisplay
  • onContentBeforeSave
  • onContentAfterSave
  • onContentPrepareForm
  • onContentPrepareData
  • onContentBeforeDelete
  • onContentAfterDelete
  • onContentChangeState
  • onContentSearch
  • onContentSearchAreas

Editors

  • onInit
  • onSave
  • onSetContent
  • onDisplay
  • onGetContent
  • onGetInsertMethod
  • Extensions
  • onExtensionAfterInstall
  • onExtensionAfterUninstall
  • onExtensionAfterUpdate

Finder

  • onFinderCategoryChangeState
  • onFinderChangeState
  • onFinderAfterDelete
  • onFinderAfterDelete
  • onFinderBeforeSave
  • onFinderAfterSave

Quick Icons

  • onGetIcons

System

  • onAfterInitialise
  • onAfterRoute
  • onAfterDispatch
  • onAfterRender
  • onBeforeRender
  • onBeforeCompileHead
  • onSearch
  • onSearchAreas

User

  • onUserBeforeSave
  • onUserAfterSave
  • onUserBeforeDelete
  • onUserAfterDelete
  • onUserLogin
  • onUserLoginFailure
  • onUserLogout
  • onUserAuthenticate
  • onUserAuthorisation

也就是說，function 名稱等於 event 名稱，即可自動呼叫該函式。

參考資源：

http://docs.joomla.org/Plugin/Events

語系檔

PLG_LANGUAGE_KEY="Plg language key"

在這個範例中，假設外掛類別為 system 名稱為 example ，則需要以下三個檔案：

  1. example.php
  2. example.xml （或manifest.xml）
  3. language/zh-TW.plg_system_example.ini

安裝

確認命名原則都沒錯之後，將檔案包在 zip 檔中即可安裝。或是直接將檔案放在： /plugins/{folder}/{your_plugin}/ 下面，並且在後台擴充套件管理探索安裝。

範例檔下載

最後，我將範例檔案放在 GitHub 上供大家參考： https://github.com/asikart/Joomla-Plugin-Example

Control Tools

WS-logo