Mediawiki 擴展標籤

更新進度

新	舊
GoTop(跳至頁首)	LinkedImages.php
SqlTbl(秀SQL)	sqlTbl(秀SQL)

原理解說

○、必要檔

新版：必要三檔

1. extension.json
2. 實際執行的 PHP
3. i18n

舊版：必要一檔

1. 實際執行的 PHP

一、撰寫

(一)新版

1. 於 extension.json 中設定要載入的 php 以及執行的勾子(hooks)：

{
...
	"name": "GoTop",
	"descriptionmsg": "描述索引",
...
	"AutoloadClasses": {"擴展名": "php 檔相對路徑"},
	"Hooks": {"勾點": ["類別名::入口函式名"]}
...
}

如：

{
	"AutoloadClasses": {"GoTop": "includes/GoTop.php"},
	"Hooks": {"ParserFirstCallInit": ["GoTop::init"]}
}

2. 載入的 php 程式，如：

<?php
class Details {
	public static function init( Parser $parser ) {
		$parser->setHook( '標籤名', [ self::class, 'render程式名' ] );
		// 當解析器看到 <標籤> 標籤時，就執行 render程式名 (見下文)
	}
	public static function render程式名( $input, array $args, Parser $parser, PPFrame $frame ) {
		// 在本例中這個函數只是將 <mwdetails> 換成 <details> 再輸出它
		return "<details>".$input."</details>";
	}
}
?>

3. 在 i18n 中， zh-hant.json 放中文信息；找不到就用 en.json 信息。內容中，秀出查 extension.json 中「描述索引」所代表的字串。

(二)舊版

<?php
$wgExtensionFunctions[] = 'wfDetails';
function wfDetails() {
        global $wgParser;
        $wgParser->setHook('mwdetails', 'renderDetails');
}
function renderDetails($input,$args) {
	return "<details>".$input."</details>";
}	
?>

二、使用

當用戶將標籤：<擴展標籤 arg1='xxx' arg2='xxx'>...input...</擴展標籤>添加到頁面時，解析器將調用實體化函式，傳入四個參數：

1. $input：<擴展標籤>和</擴展標籤>標籤之間的輸入。如果是「開始與結束合體的標籤」，即<擴展標籤 />， $input 則輸入'null'
2. $args：標籤屬性，像 HTML 標籤屬性一樣輸入；這是一個以屬性名稱作鍵的陣列(鍵-值對)。
3. $parser：父解析器(一個解析器物件)；更上級的外掛，使用它來獲取上下文標題，解析維基文字、大括號，註冊鏈接關係和依賴關係等。
4. $frame：父框架(PPFrame物件)。它與$parser一起使用，為解析器提供有關調用外掛的上下文的更完整資訊。

三、設定

(一)新版

在 LocalSettings.php 中加

wfLoadExtension( '擴展資料夾' );

(二)舊版

MediaWiki 1.25 之前外掛名和外觀的配置是在 PHP 檔名或外觀名稱一致的，如 MyExtension.php 或 MySkin.php。

require_once "$IP/extensions/Hello/Hello.php";
require_once "$IP/extensions/FooBar/FooBar.php";
$wgFooBarEnable = true;
require_once "$IP/skins/Baz/Baz.php";

也可以寫成：

wfLoadExtensions( array( 'Hello', 'FooBar' ) );
$wgFooBarEnable = true;
wfLoadSkin( 'Baz' );

如果您將外掛放在 $IP/extensions 以外的位置，您需要重設 $wgExtensionDirectory 。如果您的皮膚未在 $IP/skins 中，您需要重設 $wgStyleDirectory 。重設必須在您載入任何外掛或皮膚前完成。

$wgExtensionDirectory = '/some/path';
wfLoadExtension('FooBar'); // 參看 /some/path/FooBar/extension.json
$wgStyleDirectory = '/my/skins';
wfLoadSkins(array('BarBaz','BazBar')); // 參看 /my/skins/BarBaz/skin.json 及 /my/skins/BazBar/skin.json

四、勾子

• ParserFirstCallInit：語法解析一開始的時候
  1. Details ，HTML5 的展開收起標籤
• BeforePageDisplay：顯示之前
  1. BoilerPlate 鍋爐板，用來示範的空擴展

參考資料

1. 鉤子說明手冊
2. 開發擴展手冊
3. 外掛標籤手冊
4. 外掛如何註冊
5. 各類外掛手冊
6. 常見的穩定擴展說明
   1. poem的用法
   2. BoilerPlate 鍋爐板，用來示範的空擴展
   3. Examples 一些用來擴展 BoilerPlate 的小擴展的集合
   4. ChangeUserPasswords 改密碼，密碼由系統生成，無法自訂。「特殊頁面 / 使用者與權限 / 更改使用者密碼」
   5. CSS 允許將串接樣式表載入到特定頁中。在目標頁中加入{{#css:樣式檔路徑或樣式定義}}

自行撰寫的外掛標籤

一、點圖跳連結

用於讓圖產生連結，是非常好的撰寫範例。

這在 mediawiki 中有多種實作方法，請參見 手冊:鏈接圖像

(一)mediawiki 原生語法

1. MediaWiki 1.14 版之後支援語法 [[Image:圖名|寬px|link=目的頁]]，如

   

   上述語法中，若 link= 留空，則該圖像將不再可點擊。

(二)使用 CSS

請參考：https://www.mediawiki.org/wiki/Manual:Linked_images/zh#Site_CSS

(三)啟用允許外部圖像

有伺服器權限時，去啟用 $wgAllowExternalImages(允許來自任何域的外部圖像)或 $wgAllowExternalImagesFrom(限制域的列表)，然後創建到「外部」圖像的「外部」鏈接。要使用完整 URL 而不是本地鏈接。
也可以用 CSS plainlinks 類別來消除圖像，只留下該圖像的「外部鏈接」，如：

http://jendo.org/wiki1231/images/4/49/Go_top.gif

(四)使用 Raw HTML

請參考：https://www.mediawiki.org/wiki/Manual:Linked_images/zh#Raw_HTML

(五)標籤白名單

修改 /includes/Sanitizer.php (HTML標籤白名單在其中)，然後將<img />添加到允許的標籤列表中。

(六)擴展的舊式引入(福留子孫採用)

最原初的原始碼可參考 Extension:LinkedImage ，已無法用於 Mediawiki 1.35 版。

可用於 Mediawiki 1.35 版的新寫外掛，在 LocalSettings.php 中加「require_once("$IP/extensions/LinkedImages/LinkedImages.php");」，程式碼為：

<?php
$wgHooks['ParserFirstCallInit'][] = function ( $parser ) {
	// 定義 <linkedimage> 標籤行為
	$parser->setHook( 'linkedimage', function ( $input, $args, $parser ) {
		return "<a href='".getBoxOption($input,'wikipage')."'".(getBoxOption($input,'tooltip')?" title='".getBoxOption($input,'tooltip')."'":"")."><img src='".wfLocalFile(getBoxOption($input,'img_src'))->getURL()."'".(getBoxOption($input,'img_alt')?" alt='".getBoxOption($input,'img_alt')."'":"").(getBoxOption($input,'img_width')?" width='".getBoxOption($input,'img_width')."'":"").(getBoxOption($input,'img_height')?" height='".getBoxOption($input,'img_height')."'":"").(getBoxOption($input,'img_border')?" border='".getBoxOption($input,'img_border')."'":"")."></a>";
	});
	function getBoxOption(&$input,$name,$isNumber=false) {
		if(preg_match("/^\s*$name\s*=\s*(.*)/mi",$input,$matches)) {
			return $isNumber?intval($matches[1]):htmlspecialchars($matches[1]);
		}else{return false;}
	}
}
?>

使用範例「跳至頁首」內容如下：

<p align='right'><linkedimage>
wikipage=#top
img_src=Go_top.gif
tooltip=跳頁首
img_alt=跳頁首
</linkedimage></p>

(七)擴展的新式引入(跨校選修採用)

在 LocalSettings.php 中加「wfLoadExtension( 'GoTop' );」，增加一檔二資料夾：

extension.json 內含：

	"MessagesDirs": {"GoTop": ["i18n"]},
	"Hooks": {"ParserFirstCallInit": ["GoTop::init"]},
	"AutoloadClasses": {"GoTop": "includes/GoTop.php"},

多國語言說明在「i18n」資料夾之下，一種語言說明一檔 en.json,zh-hant.json

真正的程式在「includes」資料夾之下的 GoTop.php ，程式碼為：

<?php
class GoTop {
	public static function init( Parser $parser ) {
		$parser->setHook( 'goTop', [ self::class, 'rendergoTop' ] );
	}
	public static function rendergoTop( $input, array $param, Parser $parser, PPFrame $frame ) {
		return "<p align='right'><a href='#top' title='跳頁首'><img src='/wellBeingNg/images/4/49/Go_top.gif' alt='跳頁首'></a></p>";
	}
}
?>

使用範例「跳至頁首」內容如下：

<goTop/>

二、videoflash.php(舊式呼叫，可用於alWiki)

在 videoflash.php 最前面的多行註解中，有使用範例。

適應 HTML4 和 5 ，是解析標籤所夾內容與標籤屬性的參考範例。

三、details.php(丁丁所寫)

用來使 HTML5 的 details、summary 兩標籤生效，會將 wiki 頁中的 mwdetails 標籤換成 details 標籤。

(一)在 mwdetails 標籤內部

1. 所有的 HTML 標籤不會再被過濾掉，如： summary 標籤
2. 可以在內部再放入巢狀的 details 標籤。如果外掛標籤名選用 details 而非 mwdetails 就無法在內部使用巢狀功能，因為外掛標籤結束和內層的 details 標籤結束，兩者會相混肴。
3. 列點 wiki 語法，「#,*,:」均會被解譯
   • 2024.02.02芸伍註：單層中括號包網址、等號轉標題、單引號已可以被解譯
4. 其他 wiki 語法：雙層中括號不會被解譯

(二) details 標籤參考資料

• 借助HTML5 details,summary無JS實現各種交互效果

四、PDFViewer.php(AI所寫)

• 相容於舊版呼叫法 與 新版語法，值得研究用以改寫舊版「擴展標籤」，適應新呼叫法
• 程式說明
  • 用 iframe 直接嵌入 PDF，依賴瀏覽器的 PDF 內建支援顯示。
  • 擴充透過 ParserFirstCallInit Hook 註冊

五、test.php(丁丁所寫)

1. 用來研究新舊版本 mediawiki 的全域變數與相關物件之用。
2. 把要研究的東西賽進 renderTest 函式中
3. 去不錯學群/01/晨課/週三頁面觀察結果。
4. 須要登入後，重按「編輯」與「儲存變更」，才會顯示新的結果。

六、sqlTbl.php(丁丁所寫)

1. 把資料表以 select 指令，輸出為 wiki 表格
2. 將參考 平台化討論.html 中 CSS .wikiInCell 類別的運用，改善表格內解析
3. 參考 home.jendo.org 中 ET 類別 wiki 資料夾中 wikiInCell.php ，將表格內的列點 doBlockLevels 解析，並將#,*解析成對 .wikiInCell 適應的形式。
4. 用平台化/簡表當作開發測試對象

使用說明：

1. tblextra：加於 table 標籤的額外屬性
2. dbname：指定資料庫
3. tblhead：首列欄名指示，如無則不秀
4. groupByColName：欄名同值會 rowspan
5. sql：撈資料指令
6. rowSpanColName：功能暫時抑制、待修改
7. firstName：暫未使用

使用例子：

1. alWiki::資訊基礎應用
2. alWiki::福留子孫/作業系統/首輪提案(用於印領清冊)
3. alWiki::2025與2026年中央政府教育補助

七、projectSchedule.php(丁丁所寫)

1. 外觀請參考 討論:「推動我國跨校選修平台」計畫書之「projectSchedule」段。

撰寫格式：

<projectSchedule>
年=第一年;第二年
第一年=幾月;幾月
第二年=幾月;幾月;幾月;幾月;幾月
項目=第一個工作項目;第二個工作項目;第三個工作項目;…
第一個工作項目=第幾年/幾月;第幾年/幾月;第幾年/幾月
第二個工作項目=第幾年/幾月;第幾年/幾月;第幾年/幾月
第三個工作項目=第幾年/幾月;第幾年/幾月;第幾年/幾月
列高=…(預設25)
項目寬=…(預設130)
月份寬=…(預設42)
…
</projectSchedule>

可用屬性：

1. font-family=字體(預設標楷體)
2. font-size=字體大小(預設10pt)
3. background=著色的色碼或顏色名稱(預設#aaccf2)

八、projectBudget.php(丁丁所寫)

1. 外觀請參參考 討論:「推動我國跨校選修平台」計畫書之「projectBudget」段。
2. 使用 DS218+ 上面 wiki 資料庫的「計畫經費」表，由「專案名稱」欄控制。

撰寫格式：

<projectBudget>
專案名稱=○○○○○○○○○○
計畫期程=□□□年□□月□□日至□□□年□□月□□日
列高=…(預設20)
</projectBudget>

可用屬性：

1. tWidth=預算表寬度(預設510pt，印出為 18cm )
2. font-family=字體(預設標楷體)
3. font-size=字體大小(預設10pt)
4. background=著色的色碼或顏色名稱(預設#f2f0aa)

九、embedVideo/VideoService.php(芸伍所改)

修改「classes/VideoService.php」，此檔案為embedVideo下重要的轉換檔案，可以決定那些service可用，與要如何轉換網址。

芸伍更動部分：

• 原本只能embed YT 影片，現在把它改為任意網址皆可
  • 維度：可以使用 dimensions="480" 或 dimensions="480x320" 或 dimensions="x320" 來更改寬、寬x高、x高
  • 可以使用 youtube 等 34 個網站影片(含 FB,spotify,ted,土豆,推特…)，而每一個網站還可能有多種影片播放服務，如 youtube 有三種服務，分述如下：
    1. youtube：播放單一影片
    2. youtubeplaylist：播放「播放清單」
    3. youtubevideolist：省略協定播放單一影片，實體化為「<iframe src='//www.youtube.com/embed/…'」而非「<iframe src='https://www.youtube.com/embed/…'」。省略的協定會依網頁本身的協定補回，如網頁本身的協定是 http:// 就會補回 http:// 。會有這項服務是因為早期的 youtube 同時支援 HTTP 和 HTTPS (過渡期），如果：網頁是 https 而 iframe 還寫死 http ，瀏覽器會出「Mixed Content（混合內容）錯誤」，而 MediaWiki、WordPress 的舊版範本就需要這麼寫。到 2025 年，它已經完成歷史任務，不再須要這麼寫了。
  • 可以使用service="youtube" 新增YT影片
    • 範例<embedvideo service='youtube' dimensions="480x320" >https://www.youtube.com/watch?v=nfFmzaszANw</embedvideo>
  • 或是使用service="jendo" 新增其他網址影片
    • 範例<embedvideo service='jendo' w='480' h='360'>http://jendo.org/uploadFiles/跨校選修/205/用手機慢動作拍攝日光燈管，看到明暗轉換1.mp4</embedvideo>
• 新增如下：
  • 562行 'jendo.org' => 'jendo'//對應表
  • 458行 (YT) 'embed' => '<iframe title="%4$s" src="https://www.youtube.com/embed/%1$s?%5$s" width="%2$d" height="%3$d" frameborder="0" allowfullscreen="true"></iframe>', //更改 iframe src
  • 466行 (YT)'url_regex' => ['#(?:youtube\\.com/watch\\?v=|youtu\\.be/|youtube\\.com/embed/)([\\w-]{11})#i'],//更改 url 正則轉換式
  • 513-519行

'jendo' => ['embed'=> '<iframe title="%4$s" src="%1$s" width="%2$d" height="%3$d" frameborder="0" allowfullscreen="true" autoplay="false"></iframe>',<br/>
			'default_width'	=> 640,<br/>
			'default_ratio'	=> 1.6,<br/>
			'https_enabled'	=> false,		]