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

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:

Bahasa Indonesia • ‎Deutsch • ‎English • ‎Nederlands • ‎español • ‎français • ‎português do Brasil • ‎русский • ‎中文（台灣）‎

Joomla!

3.x

教學

建立一個簡單的模組

本系列文章

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

讓我們從簡介開始，您可以使用底下的導覽按鈕來瀏覽文章，或是右側的方塊中的連結(列出所有的文章)。您可以觀看 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 模組並編輯它。

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

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

結論

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

上一篇：介紹

下一篇：使用資料庫

J3.x