首頁‎ > ‎電子期刊‎ > ‎2007年12月號‎ > ‎

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


本篇延續擴充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 );
}
 
?>

安裝步驟

  1. 將程式碼另存為PHP檔案,建議與Tag Extension名稱一樣,本例為SampleSetup.php。
  2. 將檔案放置於MediaWiki的extensions目錄,例如筆者的為/opt/lampp/htdocs/wiki /extensions/;建議可新建目錄放置,例如完整的檔案路徑為/opt/lampp/htdocs/wiki/extensions /SampleSetup/SampleSetup.php。
  3. 在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