PMS API 規格

規格版本

Version 1.4 : 6th.Release

主要改進面

  • 自訂掛載點 (Custom Hook Point): addCHP, callCHP 可以讓模組自行定義一個掛載點,進而達成模組擴充其他模組的功能

Version 1.3 : 4th.Anniversary

主要改進面

  • 修改掛載點: PostOnDeletion 無法知道為何種時機觸發 (前端使用者自刪?系統回收刪除?後端管理者刪除?),故加上第二個 cond 參數

Version 1.2 : 4th.Release.3

主要改進面

  • 新增掛載點: 文章被刪除 (PostOnDeletion)、新增文章完成 (RegistAfterCommit)、文章順序處理 (ThreadOrder)、管理頁面功能選項 (AdminFunction)
  • 移除掛載點: UsageExceed (可被 PostOnDeletion 取代)
  • 修改在未初始化前 hookModuleMethod 的話會造成 autoHookXXXX 沒動作 (改為使用此函式時如果發現掛載點為空,先去搜尋 autoHook)
  • autoHookRegistBegin 新增 $isReply 參數

Version 1.1 : 4th.Release.2

主要改進面

  • 由事前將所有掛載點掛載所有模組之方法再執行工作,變為先執行工作,需要使用掛載點時才動態載入 (Loading all before acting -> Acting with loading dynamically)
  • 新增掛載點
  • 更改部份掛載點方法
  • 新增模組單載入支援

Version 1.0 : 4th.Release

方法一覽

PMS API

模組設計者面

  • getModulePageURL : 取得模組獨立頁面 URL
  • hookModuleMethod : 手動掛載方法於掛載點
  • addCHP : 掛載方法於自訂掛載點
  • callCHP : 呼叫自訂掛載點之方法

系統內部面

  • init : 初始化
  • onlyLoad : 模組單載入模式
  • loadModules : 載入指定模組檔案
  • getLoadedModules : 取得已載入模組名稱列表
  • getModuleMethods : 取得特定模組擁有之方法列表
  • __autoHookMethods : 自動搜尋模組之自動掛載機制方法並掛載於掛載點
  • useModuleMethods : 呼叫特定掛載點之所有方法

模組檔案 API

掛載點一覽 (非方法)

Head

這是 HTML 檔頭的掛載點,可以動態增改諸如樣式表連結、JavaScript 等標籤。

Toplink

這是頁面上方的連結列,可以動態新增連結功能。

PostInfo

這是發文/回文表單下方的提示說明事項區,可以新增說明列表。

LinksAboveBar

這是模式指示條上的連結列,可以動態新增連結功能。

ThreadFront

這是所有討論串印出前的排版部分,可以新增標籤以印出。

ThreadPost

這是印出討論串首篇的標籤取代新增功能,需搭配 PTE 樣板函式庫連動。可以動態增加或修改取代字串標籤 (ex: {$NAME})

ThreadReply

這是印出討論串回應的標籤取代新增功能,需搭配 PTE 樣板函式庫連動。可以動態增加或修改取代字串標籤 (ex: {$NAME})

ThreadRear

這是所有討論串印出後的排版部分,可以新增標籤以印出。

Foot

這是頁尾部分,可以新增標籤以印出。

ModulePage

這是供模組以獨立頁面運作的特殊掛載點,特殊的是此掛載點沒有 autoHook 功能,需手動掛載。掛載之後 Pixmicat! 便可以以 mode=module&load=XXX 方式來呼叫並給予其工作權,可以讓模組達成更多功能。

AdminList

這是在後端頁面供每一個文章能有一些的操作功能的連結而產生的。比方說可以將此文章的圖檔做點修正,或者是將發文者的 IP 地址加入封鎖列表等等。

Authenticate

這是用作認證管理權限的掛載點,當管理或刪除時就會發動。

RegistBegin

這是在文章送出開始處理前的掛載點,可以在此時檢查文章資料,如果不合規定可以馬上拒絕。

RegistBeforeCommit

同上,不過文章內容已經過處理即將儲存,可以在此在檢查文章資料 (例如 Trip),如果不合規定可即時拒絕。

RegistAfterCommit

比 RegistBeforeCommit 還要慢發生的掛載點,當文章儲存完成後才會發生。此掛載點並不能修改文章內容,僅可作為文章已寫入的確認。

PostForm

這是發文表單最末「刪除用密碼」下方的額外欄位插入處,可在此插入新欄位 (比方驗證碼或者是簡易防機器人欄位問題)

PostOnDeletion

這是在文章即將被刪除前會觸發的掛載點,可在此時對即將刪除的文章作最後的處理。

ThreadOrder

這是文章在準備印出前,可以更改其印出順序的掛載點。

AdminFunction

這是在後台或前台管理新增動作選項的掛載點,此掛載點並可以接受管理員所選取的動作和欲處理的文章編號陣列進行處理。

模組資訊部分

  • getModuleName : 取得模組名稱
  • getModuleVersionInfo : 取得模組版本資訊

獨立頁面

  • ModulePage : 獨立頁面功能呼叫方法

自動掛載機制方法

  • autoHookHead : 自動掛載於 Head 之方法
  • autoHookToplink : 自動掛載於 Toplink 之方法
  • autoHookPostInfo : 自動掛載於 PostInfo 之方法
  • autoHookLinksAboveBar : 自動掛載於 LinksAboveBar 之方法
  • autoHookThreadFront : 自動掛載於 ThreadFront 之方法
  • autoHookThreadPost : 自動掛載於 ThreadPost 之方法
  • autoHookThreadReply : 自動掛載於 ThreadReply 之方法
  • autoHookThreadRear : 自動掛載於 ThreadRear 之方法
  • autoHookFoot : 自動掛載於 Foot 之方法
  • autoHookAdminList : 自動掛載於 AdminList 之方法
  • autoHookAuthenticate : 自動掛載於 Authenticate 之方法
  • autoHookRegistBegin : 自動掛載於 RegistBegin 之方法
  • autoHookRegistBeforeCommit : 自動掛載於 RegistBeforeCommit 之方法
  • autoHookRegistAfterCommit : 自動掛載於 RegistAfterCommit 之方法
  • autoHookPostForm : 自動掛載於 PostForm 之方法
  • autoHookPostOnDeletion : 自動掛載於 PostOnDeletion 之方法
  • autoHookThreadOrder : 自動掛載於 ThreadOrder 之方法
  • autoHookAdminFunction : 自動掛載於 AdminFunction 之方法

方法細節

PMS API

模組設計者面

getModulePageURL

string getModulePageURL(string $moduleName)

取得模組獨立頁面之 URL,製作超連結導引時用。

參數: $moduleName - 模組名稱 (即模組檔案所定義的 class 名稱)
回傳值: 獨立頁面之 URL 位置

hookModuleMethod

void hookModuleMethod(string $hookPoint, callback $methodObject) // 其他掛載點
void hookModuleMethod(string $hookPoint, string $moduleName) // ModulePage 掛載點

手動將方法掛載至指定掛載點。手動掛載獨立頁面則是指定模組檔案的 class 名稱。

參數:
$hookPoint - 掛載點名稱。掛載點列表請參考上方的掛載點一覽 (非方法) 介紹
$methodObject - 掛載之方法。一般來說是以 array(&$this, '方法名稱') 的 callback 形式表示
$moduleName - 模組名稱。此項與 getModulePageURL 指定之 $moduleName 相同

addCHP

void addCHP($CHPName, $methodObject)

將方法掛載到自訂掛載點上。

參數:
$CHPName - 自訂掛載點名稱
$methodObject - 欲掛載的方法。一般來說是以 array(&$this, '方法名稱') 的 callback 形式表示

callCHP

void callCHP($CHPName, $parameter)

呼叫指定之自訂掛載點上之所有方法。

參數:
$CHPName - 自訂掛載點名稱
$parameter - 參數陣列。依自訂掛載點不同而須傳入不同的參數格式,請參照使用之自訂掛載點的模組說明

系統內部面

init

void init()

為模組系統真正進行載入模組檔案、自動掛載機制的方法。不內建在建構元的理由是有的時候頁面並不需要模組系統作用,如果每次都載入並掛載是很沒效率的。

onlyLoad

bool onlyLoad(string $specificModule)

單載入模式入口點,使用此方法可以只載入指定名稱的模組而不必一次載入。而當模組欲使用其它掛載點方法時會自動再加載其餘模組,以正常工作。

參數: $specificModule - 要求載入特定模組之名稱。此方法由呼叫獨立頁面時使用。
回傳值: 是否載入成功。如果要求模組載入失敗或不存在會回傳 false

loadModules

void loadModules(mixed $specificModule=false)

依建構元接收之載入模組列表載入模組檔案並生成物件。

參數: $specificModule - 要求載入特定模組之名稱。此方法由呼叫獨立頁面時使用。

getLoadedModules

array getLoadedModules()

回傳已載入之模組名稱陣列。

回傳值: 已載入之模組名稱陣列

getModuleMethods

array getModuleMethods(string $module)

回傳指定模組擁有之方法列表陣列。

參數: $module - 模組名稱
回傳值: 指定模組擁有之方法列表陣列

__autoHookMethods

array __autoHookMethods(string $hookPoint)

依序搜尋各已載入模組物件內的自動掛載方法,並將其加入至掛載點內,最後回傳。

參數: $hookPoint - 掛載點名稱
回傳值: 掛載點陣列

useModuleMethods

void useModuleMethods(string $hookPoint, array $parameter)

呼叫特定掛載點的所有掛載方法,傳入一些參數供方法使用。

參數:
$hookPoint - 掛載點名稱
$parameter - 參數陣列。依掛載點不同可能是空陣列或者是文章資料等

模組檔案 API

getModuleName

string getModuleName()

傳回模組識別名稱以讓程式其他地方辨別。

回傳值: 模組識別名稱

getModuleVersionInfo

string getModuleVersionInfo()

傳回模組的簡單版本資訊說明以讓程式其他地方辨別。

回傳值: 模組的版本資訊說明

ModulePage

void ModulePage()

模組獨立頁面執行的方法。如果有向 PMS 掛載 ModulePage 掛載點,則這個方法就是必要的。當程式以獨立頁面方式呼叫時,PMS 會自動呼叫指定模組的 ModulePage() 方法並將控制權完全交給模組,就可以作更多事情。

autoHookHead

void autoHookHead(string &$style, int $isReply)

在 HTML 檔頭新增原始碼。一般來說都是讓 $style 附加一段HTML原始碼以達成效果。

參數:
$style (傳址) - HTML 原始碼
$isReply - 是否為回應模式 (0: 否, 其他: 是)

autoHookToplink

void autoHookToplink(string &$link, int $isReply)

在頁面上方導覽連結列上新增原始碼。一般來說都是讓 $link 附加一段連結原始碼以達成插入連結效果。

參數:
$link (傳址) - 上方連結列 HTML 原始碼
$isReply - 是否為回應模式 (0: 否, 其他: 是)

autoHookPostInfo

void autoHookPostInfo(string &$txt)

在發文表單下方附加說明文字項目原始碼。

參數: $txt (傳址) - 發文表單下方說明項目文字原始碼

autoHookLinksAboveBar

void autoHookLinksAboveBar(string &$link, string $pageId, mixed $addinfo=false)

在模式指示條上,主標題之下的連結列上新增原始碼。

參數:
$link (傳址) - 連結列 HTML 原始碼
$pageId - 頁面的識別碼文字,目前有以下幾項
- "admin" : 管理區
- "search" : 搜尋模式
- "category" : 按下類別標籤之列出頁面
- "modules" : 系統資訊→模組資訊頁面
- "status" : 系統資訊頁面
$addinfo - 額外的資訊,目前這一項只有在 admin 區有用,會回傳是否有管理權限,可用來分辨是否已登入

autoHookThreadFront

void autoHookThreadFront(string &$txt, int $isReply)

在印出所有討論串的區塊之前插入原始碼。

參數:
$txt (傳址) - 討論串之前顯示文字原始碼
$isReply - 是否為回應模式 (0: 否, 其他: 是)

autoHookThreadPost

void autoHookThreadPost(array &$arrLabels, array $post, int $isReply)

在每則討論串首篇輸出前可進行文章內容的修改或 PTE 取代標籤的插入以達成新功能。

參數:
$arrLabels (傳址) - PTE 輸出討論串首篇之樣板取代標籤陣列
 {$NO} - 文章編號
 {$SUB} - 文章標題
 {$NAME} - 文章發文者名稱
 {$NOW} - 文章發文日期
 {$COM} - 文章內文
 {$CATEGORY} - 文章類別
 * {$QUOTEBTN} - 文章引用回應按鈕 (可按下的 No.XXXX 即是此)
 * {$REPLYBTN} - 回應按鈕 (即 [回應])
 * {$IMG_BAR} - 圖片資訊列 (檔名:1264230546610.jpg-(87 KB, 1400x864) [以預覽圖顯示] 這種東西)
 {$IMG_SRC} - 圖片真實位置 (連結至大圖片的位置)
 * {$WARN_OLD} - 舊文章提示 (這篇已經很舊了,不久後就會刪除。)
 * {$WARN_BEKILL} - 舊圖提示 (這篇因附加圖檔容量限制,附加圖檔不久後就會刪除。)
 * {$WARN_ENDREPLY} - 停止回應提示 (這篇討論串已被管理員標記為禁止回應。)
 * {$WARN_HIDEPOST} - 回應已被隱藏提示 (有回應 n 篇被省略。要閱讀所有回應請按下回應連結。)
 * {$NAME_TEXT} - 名稱顯示前的文字 (預設值 "名稱:")
 * {$CATEGORY_TEXT} - 類別顯示前的文字 (預設值 "類別:")
 * {$SELF} - pixmicat.php 位置
 標註 * 號者為系統內部使用,不建議修改
$post - 討論串首篇資料陣列
$isReply - 是否為回應模式 (0: 否, 其他: 是)

動態新增取代標籤的範例:

<?php
$arrLabels['{$NEW_LABEL}'] = 'Hello world';
?>

則樣板檔內對應 THREAD 區塊的 {$NEW_LABEL} 則會被取代成設定值,前提是要先自行安插 {$NEW_LABEL} 到區塊適當位置。

autoHookThreadReply

void autoHookThreadReply(array &$arrLabels, array $post, int $isReply)

同 autoHookThreadPost() 方法,故請參見。

  • autoHookThreadReply 的 $arrLabels 少了 {$REPLYBTN}, {$WARN_OLD}, {$WARN_ENDREPLY}, {$WARN_HIDEPOST}

autoHookThreadRear

void autoHookThreadRear(string &$txt, int $isReply)

同 autoHookThreadFront() 方法,故請參見。

autoHookFoot

void autoHookFoot(string &$foot)

在頁尾附加原始碼。

參數: $foot (傳址) - 頁尾顯示文字原始碼

autoHookAdminList

void autoHookAdminList(string &$modFunc, array $post, int $isres)

在後端管理頁面之各文章項目新增功能連結項目原始碼。

參數:
$modFunc (傳址) - 後端管理頁面文章額外功能連結原始碼
$post - 文章資料陣列
$isres - 此文章是否為回應 (0: 否, 其他: 是)

autoHookAuthenticate

void autoHookAuthenticate(string $passwordField, string $action, bool &$result)

在後端管理頁面及刪除表單中認證刪除人權限。

參數:
$passwordField - 密碼欄位
$action - 目前執行動作 (如 admin, userdel 等)
$result (傳址) - 認證結果 (true: 成功, false: 失敗)

autoHookRegistBegin

void autoHookRegistBegin(string &$name, string &$email, string &$sub, string &$com, array &$upfileInfo, array $accessInfo, int $isReply)

在文章送出開始處理前可以檢查文章內容作一些處理。

參數:
$name (傳址) - 文章輸入名稱 (未處理)
$email (傳址) - 文章輸入 E-mail (未處理)
$sub (傳址) - 文章輸入標題 (未處理)
$com (傳址) - 文章輸入內文 (未處理)
$upfileInfo (傳址) - 文章附加檔案資訊陣列 (['file']=> 檔案暫存路徑, ['path']=> 檔案在使用者端的上傳路徑 (計算偏移值用), ['name']=> 檔名, ['status']=> PHP 規範檔案上傳狀態值)
$accessInfo - 使用者之 IP / Hostname (['ip']=> IP, ['host']=> Hostname)
$isReply - 是否為回應模式 (0: 否, 其他: 是)

autoHookRegistBeforeCommit

void autoHookRegistBeforeCommit(string &$name, string &$email, string &$sub, string &$com, string &$category, bool &$age, string $dest, int $isReply, array $imgWH, string &$status)

在文章內容已經過處理即將儲存時可以作最後的檢查處理。

參數:
$name (傳址) - 文章輸入名稱含 (已處理,可能含 Trip 或 Admin Cap)
$email (傳址) - 文章輸入 E-mail (已處理)
$sub (傳址) - 文章輸入標題 (已處理)
$com (傳址) - 文章輸入內文 (已處理)
$category (傳址) - 文章輸入類別標籤 (已處理)
$age (傳址) - 文章是否推文處理
$dest - 文章附加檔案之儲存路徑。萬一取消儲存時記得刪除這個路徑的檔案
$isReply - 是否為回應模式 (0: 否, 其他: 是)
$imgWH - 文章附加圖檔之長寬尺寸陣列 ([0]=> 預覽圖寬, [1]=> 預覽圖高, [2] => 原圖寬, [3] => 原圖高)
$status (傳址) - 文章狀態旗標值

autoHookRegistAfterCommit

void autoHookRegistAfterCommit(int $lastno, int $resto, string $name, string $email, string $sub, string $com)

在文章儲存過後可進行統計紀錄的方法。

參數:
$lastno - 新增文章之編號
$resto - 新增文章欲回應之文章編號 (如果此新文章不為回應,此值為 0)
$name - 新增文章之名稱
$email - 新增文章之 E-mail
$sub - 新增文章之標題
$com - 新增文章之內文

autoHookPostForm

void autoHookPostForm(string &$form)

在發文表單附加新欄位原始碼。因為是直接以原始碼方式插入欄位,請注意利用 <tr></tr> 的排版。

參數: $form (傳址) - 發文表單文字附加欄位原始碼

autoHookPostOnDeletion

void autoHookPostOnDeletion(array $deletedno, string $cond)

在文章被刪除時會自動執行的方法 (時機: 使用者自行刪除、管理者刪除、文章回收機制刪除),可用來作刪除文章前的收藏動作等

參數:
$deletedno - 即將被刪除的文章編號陣列
$cond - 被呼叫時機 ('backend': 後端管理者刪除, 'frontend': 前端刪除, 'recycle': 文章回收機制刪除)

autoHookThreadOrder

void autoHookThreadOrder(int $resno, int $page_num, bool $single_page, array &$threads)

在印出文章前可以修改文章輸出順序的掛載點。

參數:
$resno - 是否為回應 (0: 否, 其他: 是)
$page_num - 目前頁面編號
$single_page - 是否為單頁模式
$threads (傳址) - 文章輸出順序陣列

autoHookAdminFunction

void autoHookAdminFunction(string $action, array &$param, string $funcLabel='', string &$message='')

在後台或前台管理時新增功能選項的掛載點,並可以在管理者送出功能要求後攔截執行對應的動作。
此函式比較特別,身兼兩種工作。一種是在頁面上的功能下拉選單增加新功能 [新增],另一種是攔截對應的功能並執行 [執行]。

參數:
$action - 目前執行動作。此值目前有兩種狀況:'add' : 新增功能選項, 'run' : 執行功能選項
$param (傳址) - 傳入處理陣列。依目前動作而有不同:
  - [新增] : 此值是下拉選單選項儲存陣列,可以動態新增選項,格式為 array(功能識別標籤, 功能說明文字)。
  - [執行] : 此值是勾選需要作動作的文章列表陣列,可能同時包含了文章首篇跟回應。
$funcLabel [執行] ONLY - 此值於執行模式才會傳入,為目前指定功能之識別標籤,供模組攔截用。比方說 [新增] 時設了一個 'mod_test_123' 標籤,當管理者選取此選項並送出時,這時此值就為 'mod_test_123',讓此模組作比對之後 (即攔截) 作進一步的動作。
$message (傳址) [執行] ONLY - 此值於執行模式才會傳入,為完成動作後於頁面顯示之訊息,讓管理者知道動作是否完成。

<?php
/**
 * autoHookAdminFunction 範例
 * 程式目的: 新增兩個管理功能選項、定義其標籤,並能讓模組攔截這兩個標籤作對應動作
 */
function autoHookAdminFunction($action, &$param, $funcLabel='', &$message=''){
    global $PIO;
    if($action=='add'){ // [新增]
        $param[] = array('mod_example_01', '新增選項 01');
        $param[] = array('mod_example_02', '新增選項 02');
        return; // 記住這個 return 是必要的,後面的[執行]還不需動作
    }
 
    switch($funcLabel){ // [執行]
        case 'mod_example_01':
            $message .= '選項 01 動作完成: 您選了 No.'.implode(', ', $param).'<br />';
            break;
        case 'mod_example_02':
            $threads = array(); // 是文章首篇的編號陣列
            foreach($PIO->fetchPosts($param) as $th){ // 抓取指定文章內容
                if($th['resto']) continue; // 是回應
                $threads[] = $th['no'];
            }
            $message .= '選項 02 動作完成: 是首篇的有 No:'.implode(', ', $threads).'<br />';
            break;
        default:
    }
}
?>
除非特別註明,本頁內容採用以下授權方式: Creative Commons Attribution-Noncommercial-Share Alike 2.5 License.