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

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

內容

1 前言
2 Parser Function
3 安裝步驟
4 使用說明
5 結語

前言

本篇延續擴充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的安裝方式一樣：

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