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

擴充MediaWiki功能,如何撰寫Parser Function


前言

本篇延續擴充MediaWiki功能,大局觀一 文,與讀者分享如何撰寫Parser Fucnion,Tag Extension與Parser Function是想擴充MediaWiki功能最常用到的兩種方式,剛開始接觸可能混洧兩者用法,底下再錄摘上述文中對於Tag Extension與Parser Function的介紹。

名稱 用途
Tag Extension 擴充MediaWiki語法,用XML格式來方式,其語法為<語法名稱 參數一="參數值" 參數二="參數值">傳入內容</語法名稱> ;Tag Extension傳回內容只能是Wiki所接受的HTML語法。
Parser Function 擴充MediaWiki語法,其語法為{{ #函式名稱: 參數一 | 參數二 | 參數三 }};Parser Function傳回的內容可以是Wiki語法並且參數能夠傳入MediaWiki的變數在函式中處理,例如{{{CURRENTDATE}}}

Parser Function最大的特色是可以與MediaWiki Parser來做緊密結合,在函式中可以傳入MediaWiki變數,並且在呼叫Parser Function上也是每次根據瀏覽器的更新來進行更新,而不需使用MediaWiki特有的更新模式(網址後面加上action=purge)。

另外Parser Function與Tag Extension最大的差異在於Parser Function能夠接受回傳Wiki語法,而Tag Extension只能夠回傳限制的HTML語法;所以讀者應可清楚的瞭解兩者間的差異,若您想要開發的功能是想能傳入MediaWiki變數並且回傳Wiki語法,那麼Parser Function是您的選擇

Parser Function

Parser Function在架構上與Tag Extension相似,但是主要多了別名的用法,所以撰寫會稍複雜,讓我們來一一拆解其寫法;筆者所用的範例是再談Semantic MediaWiki(下)中的Semantic Template多值輸入問題,用以解決此問題所寫得Parser Function程式。

定義

在以下的程式碼,我們在MediaWiki內建的變數$wgExtensionFunctions中新增一個 wfSMWMultiValueParserFunction_Setup函式告訴MediaWiki我們要新增一個Extension,而此 Extension的細節在wfSMWMultiValueParserFunction_Setup中說明。

 
$wgExtensionFunctions[] = 'wfSMWMultiValueParserFunction_Setup';

在wfSMWMultiValueParserFunction_Setup函式中我們告訴MediaWiki的Parser變 數$wgParser要掛上兩個Parser Function分別是multiattribute及multirelation,它們所實際實行的內容是 wfMultiAttributeValueParserFunction_Render及 wfMultiRelationValueParserFunction_Render;前述multiattribute及multirelation 也就是我們在編輯Wiki頁面語法時所會實際鍵入的Parser Function名稱。

 
$wgParser->setFunctionHook( 'multiattribute','wfMultiAttributeValueParserFunction_Render' );

完整的程式碼如下:

 
<?php
 
#定義Extension函式,在wfSMWMultiValueParserFunction_Setup掛上Hook所對應到的Callback Function。
 

$wgExtensionFunctions[] = 'wfSMWMultiValueParserFunction_Setup';
 
#在函式中掛上Hook
 
function wfSMWMultiValueParserFunction_Setup() {
global $wgParser;
 
#將multiattribute這個Hook對應實際執行的函式為wfMultiAttributeValueParserFunction_Render。
#將multirelation這個Hook對應實際執行的函式為wfMultiRelationValueParserFunction_Render。

 
$wgParser->setFunctionHook( 'multiattribute','wfMultiAttributeValueParserFunction_Render' );
 
$wgParser->setFunctionHook( 'multirelation','wfMultiRelationValueParserFunction_Render' );
 
}

別名

Parser Function可以取別名以利於多國語言的使用,在$wgHooks中掛上wfSMWMultiValueParserFunction_Magic函式在其中詳細說明函式的別名。

 
#新增Magic Word的函式
$wgHooks['LanguageGetMagic'][]='wfSMWMultiValueParserFunction_Magic';
 
function wfSMWMultiValueParserFunction_Magic( &$magicWords, $langCode ) {
 
#將magic word對應到hook function
 
$magicWords['multiattribute'] = array( 0, 'multiattribute' );
$magicWords['multirelation'] = array(1,'multirelation');
$magicWords['多屬性值'] = array( 2, 'multiattribute' );
$magicWords['多關係值'] = array( 3,'multirelation');
 
return true;
}

實作

下面為實作的程式碼,在傳入參數的部份視Parser Function的規格可傳入任意的參數個數;在函式的最後面傳回處理完的Wiki語法,函式中實作的部份讀者可忽略只需瞭解整體的函式架構即可。

 
function wfMultiAttributeValueParserFunction_Render( &$parser, $param1 = '', $param2 = '' ) {
 
$output="";
$tok = strtok($param2, ",");
 
while ($tok!=false)
{
 
$line = explode("*", $tok);
 
if (count($line) >= 2) {
$output.="[[$param1:=$line[0]|$line[1]]],";
}else
$output.="[[$param1:=$line[0]]],";
 
$tok = strtok(",");
 
}
 
//在下行傳回Wiki語法。
 
return substr($output,0,strlen($output)-1);
}
 
 
function wfMultiRelationValueParserFunction_Render( &$parser, $param1 = '', $param2 = '' ) {
 
$output="";
$tok = strtok($param2, ",");
 
 
while ($tok!=false)
{
 
$line = explode("*", $tok);
 
if (count($line) >= 2) {
$output.="[[$param1::$line[0]|$line[1]]],";
}else
$output.="[[$param1::$line[0]]],";
 
$tok = strtok(",");
 
}
 
//在下行傳回Wiki語法。
 
return substr($output,0,strlen($output)-1);
}
 
?>

安裝步驟

Parser Function與Tag Extension的安裝方式一樣:

  1. 將程式碼另存為PHP檔案,建議與Parser Function名稱一樣,本例為MultiRelationAndMultiAttribute.php。
  2. 將檔案放置於MediaWiki的extensions目錄,例如筆者的為/opt/lampp/htdocs/wiki /extensions/;建議可新建目錄放置,例如完整的檔案路徑為/opt/lampp/htdocs/wiki/extensions /MultiRelationAndMultiAttribute.php/MultiRelationAndMultiAttribute.php。
  3. 在MediaWiki的設定檔LocalSettings.php最後加入引用Tag Extension的語法。
 
 require_once('extensions/MultiRelationAndMultiAttribute.php/MultiRelationAndMultiAttribute.php');

使用說明

本範例的使用方法如下:

 
{{#multiattribute:屬性名稱|屬性值*顯示屬性值,屬性值*顯示屬性值}}

{{#multirelation:關係名稱|關係名稱*顯示關係值,關係名稱*顯示關係值}}

而Parser Function的一般格式如下:

 
{{#:ParserFunction:參數一|參數二}}

結語

在本文中介紹了Parser Function的語法,Parser Function比Tag Extension好用的地方在於可以回傳Wiki語法,並且Parser Function的執行是隨著瀏覽器的更新而重新執行的;藉由Parser Function的應用可以更大幅簡化Wiki語法的難度以及提升其便利性。

更多關於Parser Function的資訊可參考MediaWiki的官方連結,或是讀者可直接來信與筆者討論。

Comments