3 XOOPS2模組的靈魂xoops_version.php
以上是一個在 XOOPS2 中使用 PHP 最簡單的方法,但接著,我們要開始進入棘手的部分了!本文以建立一個簡單的通訊錄為範例,示範整個模組開發的流程,只要流程熟悉了,那麼,開發模組就簡單了!首先,您得知道的是,XOOPS2 的所有模組都放在「XOOPS安裝目錄/modules」底下,換言之, modules 目錄下的每一個目錄都是一個模組。因此,我們要建立一個新模組,第一步就是先在 modules 目錄下建立一個新目錄。本例在 modules 目錄下建立一個名為 my_phonebook 的目錄,文後一律稱之為「模組目錄」。
XOOPS2 的模組可大可小,但有幾個目錄及檔案是一定要有的,我們先來認識一下最重要的一個檔案就是 xoops_version.php。這一個檔案是模組的設定檔,掌管著模組的大小資訊,同時也是和 XOOPS2 系統溝通的重要管道,小從模組名稱設定,大到該模組是否需要選單、區塊、樣版、管理介面...等,通通要在裡頭設定。因此,本文從頭到尾這個檔您會常常看 到。
每個模組一定都會有一個 xoops_version.php,而且內容都很長!看起來似乎相當複雜,其實,若是一步一步來看,您會發現:原來並不複雜嘛!OK!您可以在您的xoops_version.php 檔中輸入以下內容:
<?php $modversion['name'] = "我的電話簿"; //模組名稱 $modversion['version'] = 0.01; //模組版本 $modversion['description'] = "簡易的電話簿程式"; //模組描述 $modversion['credits'] = "tad"; //模組著作權人 $modversion['author'] = "tad"; //模組作者 $modversion['license'] = "GPL see LICENSE"; //模組版權 $modversion['image'] = "images/logo.png"; //模組圖示 $modversion['dirname'] = "my_phonebook"; //模組目錄名稱 ?> |
內容中,最重要的是 $modversion['dirname'] 必須填入該模組的目錄的名稱,填錯了模組可是不能動的!其餘的部分,只要是等號(=)後面的,您都可以自行修改。至於圖檔,沒放也無所謂,不過,建議您還 是設計個圖檔,並且依據您的設定值,建立相關的目錄及檔案,以上面的設定為例,我們還必須在您的模組目錄下建立一個 images 的目錄,並且放置一個名為 logo.png 的圖檔,以作為模組圖示。
輸入完之後,進入管理介面的模組管理中,您就會發現,可以安裝的模組中,已經多了一個叫做「我的電話簿」的模組,點選安裝也真的可以安裝喔!不過,目前空空如也,所以,並沒有安裝的必要。
圖 1. 已經出現在模組管理中囉!
4 資料表設定
大部分的模組都會用到資料庫的資料表,若是您的模組不需要,那麼這部分可以略過。如果需要資料表,那麼您必須在 xoops_version.php 加入資料表的相關設定:
$modversion['sqlfile']['mysql']是設定安裝模組時,要匯入資料庫的資料表結構檔案的位置。mysql.sql 的內容可以自行撰寫,檔名也可以自己取,檔案中一次可以放好幾個資料表,您也可以利用 phpMyAdmin 去新增資料表,然後利用輸出功能把資料表的架構輸出存檔,這樣是比較方便的作法。我們在模組目錄下建立一個 sql 目錄,其中放置 mysql.sql,其內容為:
另外,$modversion['tables'][/n]則是設定 mysql.sql 中的資料表名稱,此名稱必須和 mysql.sql 中的資料表名稱相符。若是同時有數個資料表,那麼 n 可以從 0 開始依序遞增即可。
$modversion['sqlfile']['mysql'] = "sql/mysql.sql"; //資料表檔案 $modversion['tables'][/0] = "phone"; //表格名稱 |
$modversion['sqlfile']['mysql']是設定安裝模組時,要匯入資料庫的資料表結構檔案的位置。mysql.sql 的內容可以自行撰寫,檔名也可以自己取,檔案中一次可以放好幾個資料表,您也可以利用 phpMyAdmin 去新增資料表,然後利用輸出功能把資料表的架構輸出存檔,這樣是比較方便的作法。我們在模組目錄下建立一個 sql 目錄,其中放置 mysql.sql,其內容為:
CREATE TABLE `phone ` ( `sn` smallint(5) unsigned NOT NULL auto_increment, `name` varchar(40) NOT NULL default "", `tel` varchar(10) NOT NULL default "", PRIMARY KEY (`sn`) ) ; |
另外,$modversion['tables'][/n]則是設定 mysql.sql 中的資料表名稱,此名稱必須和 mysql.sql 中的資料表名稱相符。若是同時有數個資料表,那麼 n 可以從 0 開始依序遞增即可。
5 模組管理介面設定
您的模組需要管理介面嗎?如果需要,那麼您必須在 xoops_version.php 加入: $modversion['hasAdmin'] = 1; //是否有管理介面 $modversion['adminindex'] = "admin/index.php"; //管理介面的首頁位置 $modversion['adminmenu'] = "admin/menu.php"; //管理介面的選單程式 |
若您想替該模組加個管理介面,$modversion['hasAdmin'] 必須設定成 1,若不需要,設成 0 即可。
$modversion['adminindex']是設定主要管理程式的位置,通常會放在 admin 目錄中,因此必須建立一個 admin 目錄,並產生一個 index.php 檔以作為管理程式的主檔案。
和index.php息息相關的是 $modversion['adminmenu'] 設定,它是設定當滑鼠移到模組圖示上時,所出現的浮動選單的內容檔案,通常命名為 menu.php。當使用者點選 menu.php 中的選項時,系統會將執行命令傳給 menu.php 中所設定的 $adminmenu[/n]['link'] 位置,而此位置通常就是 $modversion['adminmenu']的所在位置。
menu.php 的內容兩兩為一組,包含指令名稱 ($adminmenu[/n]['title']) 以及指令的執行連結 ($adminmenu[/n]['link']),原則上可以無限多組,例如選單中希望有 10 個執行指令,那麼,n 就可以從 1 編到 10。我們只要在選單中放兩個功能,所以只有兩組設定,menu.php 內容看起來就像這樣:
<?php
$adminmenu[/1]['title'] ="新增電話";
$adminmenu[/1]['link'] = "admin/index.php?op=Add";
$adminmenu[/2]['title'] = "刪除電話";
$adminmenu[/2]['link'] = "admin/index.php?op=Del";
?>
6 管理介面的index.php
從選單內容來看可以知道,我們設定了兩個功能,分別為新增和刪除,這兩個功能必須靠 index.php 來執行,因此,我們在 index.php 中就必須做出這兩個功能出來。本例的 index.php 內容如下:
看起來似乎很常很複雜,其實,撇開PHP的部分不說,僅說 XOOPS2 的模組規則,那到還蠻簡單的。
第一行的「include '../../../include/cp_header.php'; 」是一定要加的,該程式算是一個中介程式,讓您的模組與系統接軌用的,所以相當重要。此外,最後的「xoops_cp_header();」是管理頁的頁 首檔,而「xoops_cp_footer();」是管理頁的頁尾檔,這兩個檔可以讓您的模組看起來像是嵌在 XOOPS2 的管理介面中一樣。其餘的部分您可以自行發揮!
以本例而言,index.php 所負責的就是新增和刪除資料,因此,裡頭包含三個主要函數,分別為用來進行新增、刪除以及列表。若您的函數中會用到資料庫,那麼記得宣告「global $xoopsDB;」,以便讓函數內部也可以取得資料庫設定。
另外,當您要呼叫資料表時,請用「$xoopsDB->prefix("資料表名稱")」的方式來呼叫,因為 XOOPS2 會自動替每一個資料表加上前置字元,原先您的表叫做「phone」的話,安裝到 XOOPS2 中,可能會變成「xoops_phone」,若直接呼教會很容易出錯,因為前置字元是可以隨使用者高興而隨便訂的!因此,用「$xoopsDB-> prefix("資料表名稱")」這種方式,他會自動幫您判斷前置字元為何,以確保能夠正確的找到資料表。
在送出 SQL 請求的時候,您可以用 XOOPS2 內建的資料庫物件來操作,例如:「$xoopsDB->query(SQL語法)」,若是您的 SQL 語法是要刪除或修改,請用「$xoopsDB->queryF(SQL語法)」來進行。
若是語法執行失敗,XOOPS2 通常會出現一個警告畫面,然後轉到某一頁去,這樣的功能用「redirect_header("欲導向的位置","顯示的時間","畫面訊息"); 」即可做到。
其餘的部分均是 PHP 的程式碼,只要稍具 PHP 程式撰寫能力,應該相當容易懂。
<?php include '../../../include/cp_header.php'; //新增一筆電話資料 function add_phone(){ global $xoopsDB; $sql_insert = "insert into ".$xoopsDB->prefix("phone")." (sn,name,tel) values ('$_POST[/sn]','$_POST[/name]','$_POST[/tel]')"; $xoopsDB->query($sql_insert) or redirect_header($_SERVER['PHP_SELF'], 10,"執行錯誤"); } //刪除一筆電話資料 function del_phone(){ global $xoopsDB; $sql_delete = "delete from ".$xoopsDB->prefix("phone")." where sn=$_GET[/sn]"; $xoopsDB->queryF($sql_delete) or redirect_header($_SERVER['PHP_SELF'], 10,"執行錯誤"); } //電話一覽表 function list_phone(){ global $xoopsDB; $allData=" <form action='".$_SERVER['PHP_SELF']."' method=post> <table border=1> <tr> <td><input type='text' name='name'></td> <td><input type='text' name='tel'></td> <td><input type='hidden' name='op' value='Add'> <input type='submit' value='新增'></td> </tr>"; $sql_select="select * from ".$xoopsDB->prefix("phone"); $result = $xoopsDB->query($sql_select) or redirect_header($_SERVER['PHP_SELF'], 10,"執行錯誤"); while (list($sn,$name,$tel)=$xoopsDB->fetchRow($result)){ $allData.="<tr><td>$name</td><td>$tel</td><td><a href='".$_SERVER['PHP_SELF']."?op=Del&sn=$sn'>刪除</a>< /td> </tr>"; } $allData.="</table></form>"; return $allData; } switch($_REQUEST['op']){ case "Add"; add_phone(); header("location: ".$_SERVER['PHP_SELF']); break; case "Del"; del_phone(); header("location: ".$_SERVER['PHP_SELF']); break; default: $main=list_phone(); break; } xoops_cp_header(); echo "我的電話簿管理介面"; echo $main; xoops_cp_footer(); ?> |
看起來似乎很常很複雜,其實,撇開PHP的部分不說,僅說 XOOPS2 的模組規則,那到還蠻簡單的。
第一行的「include '../../../include/cp_header.php'; 」是一定要加的,該程式算是一個中介程式,讓您的模組與系統接軌用的,所以相當重要。此外,最後的「xoops_cp_header();」是管理頁的頁 首檔,而「xoops_cp_footer();」是管理頁的頁尾檔,這兩個檔可以讓您的模組看起來像是嵌在 XOOPS2 的管理介面中一樣。其餘的部分您可以自行發揮!
以本例而言,index.php 所負責的就是新增和刪除資料,因此,裡頭包含三個主要函數,分別為用來進行新增、刪除以及列表。若您的函數中會用到資料庫,那麼記得宣告「global $xoopsDB;」,以便讓函數內部也可以取得資料庫設定。
另外,當您要呼叫資料表時,請用「$xoopsDB->prefix("資料表名稱")」的方式來呼叫,因為 XOOPS2 會自動替每一個資料表加上前置字元,原先您的表叫做「phone」的話,安裝到 XOOPS2 中,可能會變成「xoops_phone」,若直接呼教會很容易出錯,因為前置字元是可以隨使用者高興而隨便訂的!因此,用「$xoopsDB-> prefix("資料表名稱")」這種方式,他會自動幫您判斷前置字元為何,以確保能夠正確的找到資料表。
在送出 SQL 請求的時候,您可以用 XOOPS2 內建的資料庫物件來操作,例如:「$xoopsDB->query(SQL語法)」,若是您的 SQL 語法是要刪除或修改,請用「$xoopsDB->queryF(SQL語法)」來進行。
若是語法執行失敗,XOOPS2 通常會出現一個警告畫面,然後轉到某一頁去,這樣的功能用「redirect_header("欲導向的位置","顯示的時間","畫面訊息"); 」即可做到。
其餘的部分均是 PHP 的程式碼,只要稍具 PHP 程式撰寫能力,應該相當容易懂。
7 模組主程式
管理介面做好了之後,現在要來做的就是給使用者看的畫面,亦即模組的主程式。模組的主程式請命名為 index.php,並放置在模組目錄的根目錄下。
以本例而言,我們從資料庫中讀取所有的電話簿資料,然後秀出給使用者觀看,所以整個程式很簡單,只要把資料給抓出來並秀出即可。
「include '../../mainfile.php'; 」是引入 XOOPS2 主要設定檔,非常重要,一定要引入的,比較大型的模組可能會將之放在 header.php 中,供其他程式引入。
「include XOOPS_ROOT_PATH.'/header.php';」是 XOOPS2 的網頁頁首檔,「include XOOPS_ROOT_PATH.'/footer.php'; 」則是 XOOPS2 的網頁頁尾檔,利用這兩個檔案將您的程式包起來,可以讓您的模組看起來像是嵌在 XOOPS2 裡面一樣。
另外,為了讓使用者能夠在選單上點選該模組功能,我們必須在 xoops_version.php 加入:
這樣最基本的模組就大功告成了!
以本例而言,我們從資料庫中讀取所有的電話簿資料,然後秀出給使用者觀看,所以整個程式很簡單,只要把資料給抓出來並秀出即可。
<?php include '../../mainfile.php'; include XOOPS_ROOT_PATH.'/header.php'; $sql_select="select * from ".$xoopsDB->prefix("phone"); $result = $xoopsDB->query($sql_select) or redirect_header($_SERVER['PHP_SELF'], 10,"執行錯誤"); while (list($sn,$name,$tel)=$xoopsDB->fetchRow($result)){ $data.="
|
「include '../../mainfile.php'; 」是引入 XOOPS2 主要設定檔,非常重要,一定要引入的,比較大型的模組可能會將之放在 header.php 中,供其他程式引入。
「include XOOPS_ROOT_PATH.'/header.php';」是 XOOPS2 的網頁頁首檔,「include XOOPS_ROOT_PATH.'/footer.php'; 」則是 XOOPS2 的網頁頁尾檔,利用這兩個檔案將您的程式包起來,可以讓您的模組看起來像是嵌在 XOOPS2 裡面一樣。
另外,為了讓使用者能夠在選單上點選該模組功能,我們必須在 xoops_version.php 加入:
$modversion['hasMain'] = 1; //是否加入主選單 |
這樣最基本的模組就大功告成了!