Joomla 元件開發入門完整教學：目錄結構、安裝 SQL、工具列建立、MVC 概念、前後台分離

開發 Joomla 元件是掌握 Joomla 擴充架構的核心技能。本文從零開始，帶你建立一個 com_reviews (餐廳評論) 元件，涵蓋目錄結構規範、安裝 SQL 註冊選單、前後台進入點、工具列建立與狀態切換、MVC 分層概念，並說明 Joomla 獨特的「前後台程式碼物理隔離」設計哲學。

一、元件命名與目錄結構

元件名稱 唯一、無空格、小寫，前綴 com_。

# 前台 (Site)
components/com_reviews/
├── reviews.php           # 進入點 (舊版單檔風格)
├── controller.php        # 控制器
├── models/               # 模型
├── views/                # 視圖
│   └── review/
│       ├── view.html.php
│       └── tmpl/
│           └── default.php
└── routers.php           # 路由 (SEF)

# 後台
administrator/components/com_reviews/
├── admin.reviews.php     # 進入點
├── controller.php
├── controllers/
├── models/
├── views/
│   └── reviews/
│       ├── view.html.php
│       ├── tmpl/
│       │   └── default.php
│       └── toolbar.reviews.html.php  # 工具列輸出
└── toolbar.reviews.php   # 工具列邏輯

二、最小可行性進入點

前台 components/com_reviews/reviews.php

<?php
defined('_JEXEC') or die('Restricted access');
echo '<div class="componentheading">Restaurant Reviews</div>';

後台 administrator/components/com_reviews/admin.reviews.php

<?php
defined('_JEXEC') or die('Restricted access');
echo 'Restaurant Reviews Administration';

驗證

• 前台：index.php?option=com_reviews
• 後台：administrator/index.php?option=com_reviews

三、資料庫註冊元件（安裝 SQL）

INSERT INTO `#__components` 
(`name`, `link`, `admin_menu_link`, `admin_menu_alt`, `option`, `admin_menu_img`, `params`)
VALUES
('Restaurant Reviews', 
 'option=com_reviews', 
 'option=com_reviews', 
 'Manage Reviews', 
 'com_reviews', 
 'js/ThemeOffice/component.png', 
 '');

執行後，後台「元件」選單自動出現「Restaurant Reviews」。

四、前台選單項建立

1. 後台 → 選單 → 主選單 → 新增
2. 選單項目類型 → 「Restaurant Reviews」
3. 填寫標題 → 儲存
4. 前台選單即出現連結

五、後台工具列系統

Joomla 後台工具列分離 邏輯 與 輸出：

1. 輸出類 toolbar.reviews.html.php

<?php
defined('_JEXEC') or die;
class TOOLBAR_reviews {
    function _DEFAULT() {
        JToolBarHelper::title(JText::_('Restaurant Reviews'), 'generic.png');
        JToolBarHelper::publishList();
        JToolBarHelper::unpublishList();
        JToolBarHelper::editList();
        JToolBarHelper::deleteList();
        JToolBarHelper::addNew();
    }
    function _NEW() {
        JToolBarHelper::save();
        JToolBarHelper::apply();
        JToolBarHelper::cancel();
    }
}

2. 邏輯類 toolbar.reviews.php

<?php
defined('_JEXEC') or die;
require_once JApplicationHelper::getPath('toolbar_html'); // 載入輸出類

switch ($task) {
    case 'edit':
    case 'add':
        TOOLBAR_reviews::_NEW();
        break;
    default:
        TOOLBAR_reviews::_DEFAULT();
        break;
}

3. 任務參數驅動

URL &task=add 觸發 _NEW() 顯示「儲存/套用/取消」；預設顯示「發布/取消發布/編輯/刪除/新增」。

六、標準工具列按鈕對照

七、前後台分離架構優勢

• 安全性：後台邏輯 (ACL、資料庫寫入) 絕不洩露至前台。
• 效能：前台不載入後台類別、資源。
• 維護性：獨立開發、部署、測試。
• 共用模型：後台可 require_once JPATH_SITE . '/components/com_reviews/models/review.php' 共用資料層。

八、進階：MVC 現代化結構 (Joomla 3.x+ 建議)

components/com_reviews/
├── src/
│   ├── Controller/       # 控制器
│   ├── Model/            # 模型
│   ├── View/             # 視圖 (Html/Json/Feed)
│   └── Service/          # 服務層
├── tmpl/                 # 佈局檔
├── forms/                # 表單 XML
├── config.xml            # 參數設定
├── script.php            # 安裝/更新腳本
└── com_reviews.xml       # 安裝清單

採用 src/ 命名空間 Joomla\Component\Reviews\Site / Administrator，支援自動載入、依賴注入、單元測試。

九、學習路徑建議

1. 完成本文「最小元件」→ 理解進入點、註冊、工具列。
2. 建立資料表 + Model (JTable) → 掌握 CRUD。
3. 建立 View + Layout → 輸出 HTML/JSON。
4. 實作 Controller 處理 Task → 表單提交、刪除、狀態切換。
5. 加入 ACL (assets 表) → 精細權限控制。
6. 撰寫安裝清單 XML + script.php → 打包發布。
7. 遷移至 src/ 現代架構 → 企業級開發標準。

總結

Joomla 元件開發核心在於命名規範、前後台物理隔離、工具列任務驅動、MVC 分層。從單檔進入點開始，逐步遷移至現代 src/ 架構，即能建構安全、可維護、符合生態規範的擴充套件。