J3.x

建立一個簡單的模組/開發一個簡單的模組

From Joomla! Documentation

< J3.x:Creating a simple module
This page is a translated version of the page J3.x:Creating a simple module/Developing a Basic Module and the translation is 100% complete.

Other languages:
Deutsch • ‎English • ‎español • ‎français • ‎Bahasa Indonesia • ‎Nederlands • ‎português do Brasil • ‎русский • ‎中文(台灣)‎
Joomla! 
3.x
教學
建立一個簡單的模組

這一系列的文章介紹如何 建立一個 Joomla! 模組 版本 Joomla 3.x。您可以依序瀏覽文章。

讓我們從簡介開始,您可以使用底下的導覽按鈕來瀏覽文章,或是右側的方塊中的連結(列出所有的文章)。 您可以觀看 2 部和本教學相關的影片,基本 Joomla 模組開發影片教學 1 and 基本 Joomla 模組開發影片教學 2.




模組是輕量化且具有彈性的擴充套件。它們會用在比較不複雜的小型任務,可以在不同的元件頁面中呈現。

在 Joomla! 標準安裝中,您可以看到很多預先裝好的模組,例如「選單」、「最新文章」、「登入表單」等等。

這個教學會解釋如何建立一個簡單的 Hello World 模組。透過這些教學您會學到基本的模組檔案結構。這個基本架構可以再進一步擴充成更複雜的模組。

檔案結構

在標準的模組開發形式中,有四個基本的檔案。

  • mod_helloworld.php - 這個檔案是模組的主要入口點,它會負責所有起始的作業,呼叫 helper 作業來蒐集需要的資料,然後顯示於佈景主題排版的頁面中。
  • mod_helloworld.xml - 這個檔案包含了與模組相關的資訊,它定義了需要被安裝的模組檔案清單,並指定了模組可以設定的參數。
  • helper.php - 這個檔案包含了 helper class,用來執行真正的工作,獲得要呈現在模組中的訊息。 (通常是從資料庫或是其他的資料來源)。
  • tmpl/default.php - 這是模組的佈景主題。這個檔案會取用從 mod_helloworld.php 獲得的資料,並產生 HTML 來顯示在頁面上。

建立 mod_helloworld.php

mod_helloworld.php 檔案執行三個工作:

  • include helper.php 檔案,它是用來包含會使用來蒐集必要的資料的 class
  • invoke the appropriate helper class method 來獲得資料
  • include 佈景主題來顯示要輸出的內容

helper class 定義於helper.php 檔案。這個檔案會用require_once句法來引用:

require_once dirname(__FILE__) . '/helper.php';

使用了 require_once ,因為我們的 helper functions 是在 class 當中被定義,我們只會需要定義這個 class 一次。

我們還沒有定義 helper class,但是一旦定義了,它會包含有一個 method: 在這裡是 getHello()。雖然在我們這個基本範例中,並不需要做這個 — 這個 method 回傳的 “Hello, World” 這一行訊息,大可以被包含在佈景主題中就可以了。儘管如此,在此我們會使用 helper class ,來示範這個基本的機制。

我們的模組目前來說,並未使用任何參數,但無論如何,我們會傳遞參數給helper method,這樣一來,假如之後我們要擴展模組的規模時,它們可以被使用。

使用以下的方法來調用 helper class method:

$hello = modHelloWorldHelper::getHello($params);

完成 mod_helloworld.php 檔案

完整的 mod_helloworld.php 檔案的內容如下:

<?php
/**
 * Hello World! Module Entry Point
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @license    GNU/GPL, see LICENSE.php
 * @link       http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */

// No direct access
defined('_JEXEC') or die;
// Include the syndicate functions only once
require_once dirname(__FILE__) . '/helper.php';

$hello = modHelloWorldHelper::getHello($params);
require JModuleHelper::getLayoutPath('mod_helloworld');

到目前為止我們都還沒有解釋 defined('_JEXEC') or die; 這一行程式碼。這一行程式碼確保這個檔案只會從 Joomla! 應用程序調用,對於防範 variable injection 以及其它的安全風險而言,這是必須的。

建立 helper.php

helper.php 檔案包含 helper class ,那是用來取得要顯示在module output的資料。如同先前提過的,我們的 helper class 會有一個 method,那就是 getHello()。這個method 會回傳 ‘Hello, World’ 訊息。

這是 helper.php 檔案的程式碼:

<?php
/**
 * Helper class for Hello World! module
 * 
 * @package    Joomla.Tutorials
 * @subpackage Modules
 * @link http://docs.joomla.org/J3.x:Creating_a_simple_module/Developing_a_Basic_Module
 * @license        GNU/GPL, see LICENSE.php
 * mod_helloworld is free software. This version may have been modified pursuant
 * to the GNU General Public License, and as distributed it includes or
 * is derivative of works licensed under the GNU General Public License or
 * other free or open source software licenses.
 */
class ModHelloWorldHelper
{
    /**
     * Retrieves the hello message
     *
     * @param   array  $params An object containing the module parameters
     *
     * @access public
     */    
    public static function getHello($params)
    {
        return 'Hello, World!';
    }
}

並沒有特定的規範,要求我們命名我們 helper class as we have,,然而,這會比較有幫助,往後我們可以比較容易識別它們。請注意,如果您計畫要使用 com_ajax 元件,必須要遵循以下格式。

更多進階的模組可能會包含資料庫請求,或是其他 helper class method 的功能。

建立 tmpl/default.php

default.php 檔案是佈景主題,顯示模組外觀。

default.php 檔案程式碼如下:

<?php 
// No direct access
defined('_JEXEC') or die; ?>
<?php echo $hello; ?>

有個重要的事情要留意,就是佈景主題檔案有著和mod_helloworld.php 檔案一樣的 scope。也就是說可以在 mod_helloworld.php 檔案中定義 $hello 變數,然後使用於佈景主題檔案,無需呼叫任何其他的宣告或是 function。

建立 mod_helloworld.xml

tt>mod_helloworld.xml 用來指定那個檔案是安裝過程中需要的;以及模組管理介面中,哪些參數可以用來設定模組。進一步的模組資訊也會在這個檔案中描述。

mod_helloworld.xml 檔案的內容如下:

<?xml version="1.0" encoding="utf-8"?>
<extension type="module" version="3.1.0" client="site" method="upgrade">
    <name>Hello, World!</name>
    <author>John Doe</author>
    <version>1.0.0</version>
    <description>A simple Hello, World! module.</description>
    <files>
        <filename>mod_helloworld.xml</filename>
        <filename module="mod_helloworld">mod_helloworld.php</filename>
        <filename>index.html</filename>
        <filename>helper.php</filename>
        <filename>tmpl/default.php</filename>
        <filename>tmpl/index.html</filename>
    </files>
    <config>
    </config>
</extension>

Manifest 檔案 說明了使用於XML檔案中的元素的技術細節。

你應該會注意到,有兩個額外的檔案是我們尚未提到的:index.html 以及tmpl/index.html。這些檔案被安排的原因是要讓資料夾路徑無法直接被瀏覽,如果有使用者嘗試將瀏覽器路徑指向這些資料夾,會顯示 index.html 檔案,這些檔案內容可以是空白的,或是簡單地寫下:

<html><body bgcolor="#FFFFFF"></body></html>

會顯示一個空白頁面

因為我們的模組沒有使用任何的 表單欄位,所以設定介面是空白的。

安裝並檢視模組

要安裝模組,請壓縮原始檔案的上層資料夾,命名為mod_helloworld.zip。請注意,副檔名必須是 .zip ,因為伺服器需要使用 Apache 的 mod_zlib library 將之解壓縮。 前往 Joomla 管理區,擴充套件/管理/從...安裝,點擊上傳安裝包頁籤,並上傳您的zip 檔案。您應該會發現模組已經成功安裝。假如沒有的話,仔細檢查您的程式碼,比對上述的教學內容,並確認檔案命名正確。 要讓您的模組能夠顯示在網頁上,請到擴充套件 / 模組清單,點擊 Hello World 模組並編輯它。

  1. 設定狀態為發佈
  2. 選擇要顯示這個模組的位置 (如果您不確定要顯示在哪一個位置,可以訪問擴充套件 / 佈景主題 / 樣式,檢查您的網站套用哪一個佈景主題,接著依照 這個教學 來找到模組位置)。
  3. 到選單管理 Menu Assignment tab set the Module Assignment to 「所有頁面」

儲存並關閉編輯頁面。 現在如果您開啟前台頁面,您應該會看到 "Hello, World!" 顯示於您選擇的模組位置。

結論

Joomla! 模組開發是很容易、直觀流程的。使用上面教學的技巧,只需要小小的付出,就可以開發出無窮無盡的多樣化模組。