擴充MediaWiki功能，如何撰寫Tag Extension

內容

1 前言
2 Tag Extension
1. 2.1 Tag Extension範例
2. 2.2 Tag Extension範例（加上參數）
3 安裝步驟
4 使用說明
5 注意事項
6 結語

前言

本篇延續擴充MediaWiki功能，大局觀的文章，與讀者分享如何撰寫MediaWiki中主要的外掛功能；下列表格再將前文所提主要的擴充功能表列如下，本文主要介紹Tag Extension的撰寫方式：

名稱	用途
Tag Extension	擴充MediaWiki語法，用XML格式來方式，其語法為<語法名稱參數一="參數值" 參數二="參數值">傳入內容</語法名稱> ；Tag Extension傳回內容只能是Wiki所接受的HTML語法。
Parser Function	擴充MediaWiki語法，其語法為{{ #函式名稱: 參數一 \| 參數二 \| 參數三 }}；Parser Function傳回的內容可以是Wiki語法並且參數能夠傳入MediaWiki的變數在函式中處理，例如{{{CURRENTDATE}}}。
Hook	Hook可以用來欄截MediaWiki軟體中的事件，例如儲存頁面、上傳檔案、登入…等等；在使用Hook時要指定由哪個函式來執行，語法為$wgHooks['event'][] = 'function';。其中的function會根據每個Hook的不同而有不同的型式，例如傳入兩個參數或是需指定一個物件，下面為傳入兩個參數的函式範例someFunction($param1, $param2);。
Special Page	在MediaWiki中有Special Page，意思是特殊頁面，例如帳號登入、網站統計、權限管理…等較特殊的功能都會在Special Page中實作。

Tag Extension

Tag Extension如上述所提只是將參數傳入Tag Extension當中，而函式中對於參數進行處理最後傳回HTML語法給MediaWiki Parser，MediaWiki Parser再原封不動的輸出至Wiki頁面。

Tag Extension傳入的參數不能是MediaWiki的參數，例如目前頁面名稱的參數為{{FULLPAGENAME}}，所以只是單純的輸出HTML 語法而不會與MediaWiki Parser有深入互動，讀者需瞭解此一特性。以下以兩個簡單的範例來說明Tag Extension的用法。

Tag Extension範例

 <?php
 
#新增Extension函式
 
$wgExtensionFunctions[] = 'efSampleSetup';
 
#將Parser掛上sample這個Hook，由efSampleRender函式執行。
 
function efSampleSetup() {
    global $wgParser;
 
    //sample為extension name，實際寫法為<sample> </sample>
    $wgParser->setHook( 'sample', 'efSampleRender' );
}
 
#Callback Function，$為使用者輸入內容、$args為參數、$parser為Parser。
function efSampleRender( $input, $args, $parser ) {
 
    //在回傳時將HTML語法轉換成特殊的編碼。
    return htmlspecialchars( $input );
}
 
?>

Tag Extension範例（加上參數）

 <?php
 
$wgExtensionFunctions[] = 'efSampleSetup';
 
function efSampleSetup() {
    global $wgParser;
    $wgParser->setHook( 'sample', 'efSampleRender' );
}
 
function efSampleRender( $input, $args, $parser ) {
    $attr = array();    
 
    //解析傳入Tag Extension的參數
    foreach( $args as $name => $value )
        $attr[] = '<strong>' . htmlspecialchars( $name ) . '</strong> = ' . htmlspecialchars( $value );
    return implode( '<br />', $attr ) . "\n\n" . htmlspecialchars( $input );
}
 
?>

安裝步驟

將程式碼另存為PHP檔案，建議與Tag Extension名稱一樣，本例為SampleSetup.php。
將檔案放置於MediaWiki的extensions目錄，例如筆者的為/opt/lampp/htdocs/wiki /extensions/；建議可新建目錄放置，例如完整的檔案路徑為/opt/lampp/htdocs/wiki/extensions /SampleSetup/SampleSetup.php。
在MediaWiki的設定檔LocalSettings.php最後加入引用Tag Extension的語法。

  require_once('extensions/SampleSetup/SampleSetup.php');

使用說明

上述第一個範例的使用方法如下，在標籤中可鍵入內容。

 <sample>於此鍵入內容</sample>

第二個範例除了在標籤中可鍵入內容外，另可傳入多組參數，傳入的參數名稱及內容視每個Tag Extension的規範而定。

 <sample key1="value1" key1="value2">於此鍵入內容</sample>

注意事項

在撰寫Tag Extension時，注意若要忠實的呈現使用者的輸出內容要使用PHP的htmlspecialchars函式，以使內容能在瀏覽器上能正常顯示。

另一個需要注意的是使用Tag Extension的重新執行時機，我們需要在Wiki頁面的網址加上參數action=purge來重新呼叫extension並產生頁面，清除已有的快取；底下的連結給讀者參考，您可直接將此連結放置於有呼叫Tag Extension的頁面，讓使用者在需要時自行更新頁面。

 [{{SERVER}}{{SCRIPTPATH}}/index.php?title={{FULLPAGENAMEE}}&action=purge 更新本頁]

結語

在本文中我們用兩個簡單的範例來說明Tag Extension的撰寫、安裝及使用方式，並且提醒讀者在開發Tag Extension時的注意事頁；若您想自行撰寫Tag Extension來擴充MediaWiki的功能，本文應可縮短您在摸索的時間，若您主要是想尋找現有的Tag Extension來加強MediaWiki的功能，本文應可給您觀念讓您瞭解其運作原理，在使用上會更順手或是可自行動手修改Tag Extension以符合您的需求。

在MediaWiki網站上有許多的Tag Extension可供讀者參考，這篇文章只是引子帶您看到更多的MediaWiki應用；更多的應用請您參考http://www.mediawiki.org/wiki/Category:Extensions。

Comments