定制 MediaWiki:创建及安装扩展

　　介绍

　　MediaWiki 应用最为人所知的处就是它是 Wikipedia 背后引擎很多人都发现 MediaWiki 提供了个可用环境来在工作组、甚至整个组织以及在线社区的间共享信息MediaWiki 让用户可以通过博客、wiki 以及文件来共享信息它还允许使用个标记云来保护所上载文件标记文件以便轻松定位以及定位专家

　　那么如果想要引入些不想手动更新定制信息并插入到您 wiki 页面该如何办呢？ 又如果想要为特定某种信息提供定制输出格式化又该怎样呢？这些情况正是 MediaWiki 用武的地您可以轻松地通过扩展使用来添加这些特定于站点特性

　　让我们来看看您如何创建能够和区别信息源协作 MediaWiki 扩展而同时又能通过熟悉 wiki 页用户界面来提供数据

　　MediaWiki 扩展

　　扩展可以向用来撰写文章 wiki markup 中添加新标记通过创建特殊页面添加新报告和管理特性通过格式化皮肤更改 wiki 观感甚至和外部身份验证思路方法相集成(但是身份验证不会在本文中介绍)

　　扩展用 PHP 编写并利用了 MediaWiki 各种内部 hook、类和思路方法来使其作业有效完成在您使用任何受支持 Web 服务器以及自己偏爱 PHP 开发环境开发和部署 MediaWiki 时您将会用到本文中所列如下工具:

　　Eclipse V3.5.2 — 支持大量编程语言和环境

　　PHP Development Tools (PDT) V2.2.0 — 个面向 Eclipse PHP 插件

　　MAMP Pro V1.9 — 个面向 Mac OS X 十分便利包用个有用 GUI 前端在个隔离环境中提供了 Apache、 MySQL 和 PHP虽然 OS X 自带了安装好了 Apache 和 PHP但是我更愿意使用这个包 OS X V10.6 Snow Leopard (V5.3.1) 内 PHP 版本有个明显 bug有碍于 MediaWiki 正确运行

　　MediaWiki V1.15.3 — MediaWiki 当前稳定版本

　　在深入探究区别类型扩展的前让我们先来看看为大多数扩展使用文件夹和文件布局的后是对皮肤扩展高度概览以供您更改您 MediaWiki 站点接下来将创建个可生成管理性统计数据特殊页扩展最后您将看到如何添加定制 XML 标记 markup 支持以供您在编写 wiki 页面时使用

　　扩展剖析

　　MediaWiki 扩展安装于主 MediaWiki 路径 extensions 目录大多数现代扩展都安装于其自己目录并般包含如下 3个文件(extension 是扩展名称):

　　extension/extension.php

　　extension/extension.body.php

　　extension/extension.i18n.php

　　第个文件执行化以及设置任务第 2个文件是扩展主体是实现扩展工作代码最后个文件包含国际化(i18n 是个常见缩写)串通过将您扩展消息串提取到这个 i18n 文件就可以为任何 MediaWiki 支持本地环境提供扩展本地化版本(假设您能够找到翻译文本帮助)

　　举个例子假如我创建了个名为 CHTimeStamp Hello World 扩展(有关本例源代码以及本文中其他举例源代码参见 下载)只要有人在 wiki 页面上插入了 {{CHSTAMP}}CHTimeStamp 就会插入当前日期/时间戳它包含如下文件:

　　CHTimeStamp/CHTimeStamp.php

　　CHTimeStamp/CHTimeStamp.body.php

　　CHTimeStamp/CHTimeStamp.i18n.php

图 1. Eclipse 内 CHTimeStamp 布局




　　CHTimeStamp 扩展会向 MediaWiki markup 添加个 {{CHSTAMP}} 变量每当您将 {{CHSTAMP}} 放入个页面它都会被个时间戳取代这不难理解对么？如果您有兴趣可以查看源代码(参见 下载)；我在此只给出个大概旨在为您介绍 MediaWiki 扩展总体布局和约定

　　我 CHTimeStamp.php 注册这个国际化消息文件告诉 wiki 引擎它能够在 CHTimeStamp.body.php 找到 CHTimeStamp 类并将此 CHTimeStamp::registerHooks 思路方法添加到扩展

　　在 CHTimeStamp.body.php 内定义 CHTimeStamp 类如果仔细看下此代码就会发现这完全由静态思路方法组成所以它也可以在无需更改扩展行为情况下作为系列编写CHTimeStamp registerHooks 思路方法注册这些静态思路方法来创建这个 {{CHSTAMP}} 变量以及处理使用此变量那些页面

　　最后在 CHTimeStamp.i18n.php 内我为扩展内惟静态串(它描述)创建了译文借助 Google TranslateCHTimeStamp 可支持法语、德语以及西班牙语本地语言环境但我希望这种自动翻译不会将我英语翻译成难以理解(或不适当)东西！

　　创建或下载了扩展后需要将它安装到 MediaWiki 内并激活它

　　安装个扩展

　　为您 MediaWiki 站点准备好个有趣且有用扩展后您肯定想要安装并启用它:

　　将此扩展复制并解压缩到 MediaWiki extensions 目录

　　编辑 MediaWiki 根目录内 LocalSettings.php使用您喜爱文本编辑器添加些行来配置这个新扩展然后使用 PHP require_once 语句激活它

　　比如为了安装 CHTimeStamp我已经将它 CHTimeStamp 目录复制到了 extensions 目录并将如下语句添加到了 LocalSettings.php:require_once( "$IP/extensions/CHTimeStamp/CHTimeStamp.php" );

　　通过访问 wiki Special:Version 页面可以检查扩展是否已经被成功加载除了有关所运行 MediaWiki 版本信息外这个 Special:Version 页面还会列出已成功加载扩展

图 2. Special:Version 页面显示 CHTimeStamp


　　查看原图(大图)

　　定制观感

　　MediaWiki 利用了 PHP 混合代码功能以及 HTML markup 来让您能够通过皮肤使用控制您 wiki 观感除了主要 PHP 代码的外个皮肤可以包含各种 CSS 文件以及支持图像或 JavaScript

　　个皮肤通常包含两个 PHP 文件、个内含其他支持文件目录比如著名默认皮肤 MonoBook 组成如下:

　　MonoBook.php — 主要 MonoBook 皮肤代码

　　MonoBook.deps.php — 对 PHP V5 APC opcode 缓存Cache内 bug 修复

　　monobook/ — 支持 CSS 和图片

　　皮肤命名约定非常严格要求必须是 SkinName.php、SkinName.deps.php并且以 skinname(小写)作为这个支持文件夹名称

　　在这个 skinname 文件夹内有皮肤样式所需 .css特定于浏览器样式修复也位于此处所以可以经常在这里看到 FF2Fixes.css、IE6Fixes.css、Opera6Fixes.css 等

　　SkinName.php 将开始于某些有用元数据

清单 1. MediaWiki 皮肤元数据

/**　
　*　[SkinName]　skin　
　*　
　*　@file　
　*　@ingroup　Skins　
　*　@version　[#].[#].[#]　
　*　@author　[name]　([URL]　/　[E-Mail])　
　*　@license　[URL]　[name]　
　*/　

　　可以用适合于您皮肤内容代替上述代码中方括号中内容

　　接下来需要创建 SkinTemplate 子类并覆盖 initPage 思路方法来表明您皮肤名称、样式和模板请记住用您皮肤名称替换 SkinName 和 skinname

清单 2. 扩展 SkinTemplate 来提供个新皮肤

//　inherit　　code　from　SkinTemplate,　　the　CSS　and　template　filter　
　SkinSkinName　extends　SkinTemplate　{　
　　　　function　initPage(　OutputPage　$out　)　{　
　　　　　　　　parent::initPage(　$out　);　
　　　　　　　　$this->skinname　=　'skinname';　
　　　　　　　　$this->stylename　=　'skinname';　
　　　　　　　　$this->template　=　'SkinNameTemplate';　
　　　　}　
}　

　　您皮肤主要工作将位于您 QuickTemplate 子类中

清单 3. 大多数工作都是在这个模板中完成

　SkinNameTemplate　extends　QuickTemplate　{　
...　
　　　　/**　
　　　　　*　Template　filter　callback　for　this　skin.　
　　　　　*　Takes　an　associative　.gif' />　of　data　　from　a　SkinTemplate-based　
　　　　　*　,　and　a　wrapper　for　MediaWiki's　localization　database,　and　
　　　　　*　outputs　a　formatted　page.　
　　　　　*/　
　　　　public　function　execute　{　
　　　　　　　　global　$wgUser,　$wgSitename;　
　　　　　　　　$skin　=　$wgUser->getSkin;　
　
　　　　　　　　//　retrieve　site　name　
　　　　　　　　$this->(　'sitename',　$wgSitename　);　
　
　　　　　　　　//　suppress　warnings　to　prevent　notices　about　missing　indexes　
　　　　　　　　//　in　$this->data　
　　　　　　　　wfSuppressWarnings;　
　
　　　　　　　　/*　compose　XHTML　output　*/　
　
?><!DOCTYPE　html　PUBLIC　"-//W3C//DTD　XHTML　1.0　Transitional//EN"　
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">　
...　

　　在 QuickTemplate 子类内部通过覆盖这些思路方法可以随心所欲地格式化和样式化类别列表和交叉引用等这个类 execute 思路方法将整个页面布局为个 XHTML 文档让您得以完全控制页面组织和样式化

　　在这里您不能进行 XHTML 和 CSS 页面布局和样式化但可以先看下您 MediaWiki skins 文件夹内举例并立即尝试

　　添加特殊页

　　MediaWiki 内特殊页是按需生成目是做某些特定并且对 wiki 可能有用事情比如让您编辑系统范围消息文本、列出所安装扩展或获得外部链接列表

　　除非特别指定否则特殊页将对所有人可用并会出现在 Special:SpecialPages 特殊页列表内此外还可以设置特殊页以便使用 {{Special:YourPageName}} 语法就能将它包含在页面上

　　和其他扩展类似特殊页也作为个目录安装在 extensions 文件夹内它们通常包含如下 4 个文件:

　　specialpage/specialpage.php — 扩展设置文件

　　specialpage/specialpage.aliases.php — 特殊页名称别名

　　specialpage/specialpage.body.php — 特殊页主要代码

　　specialpage/specialpage.i18n.php — 特殊页国际化串

　　例如如果要创建个名为 CHStats 特殊页那么它布局将类似于图 3

图 3. Eclipse 内 CHStats




　　CHStats.php 内代码会为此扩展添加更多功能注册别名、主体和 i18n 文件并告诉这个 wiki 引擎在需要时自动加载 CHStats 类

清单 4. 设置 CHStats 特殊页

<?php　
#　This　is　not　a　valid　entry　po　to　MediaWiki.　
(　!d(　'MEDIAWIKI'　)　)　{　
　　echo　<<<EOT　
To　　CHStats,　put　the　following　line　in　LocalSettings.php:　
require_once(　"\$IP/extensions/CHStats/CHStats.php"　);　
EOT;　
　　exit(　1　);　
}　
　
#　Take　credit　for　this　extension.　
$wgExtensionCredits['specialpage']　=　.gif' />(　
　　'name'　=>　'CHStats',　
　　'author'　=>　'Chris　Herborth　([email protected])',　
　　'url'　=>　'http://www.pobox.com/~chrish/CHStats/',　
　　'description'　=>　'A　simple　special　page　demonstration,　showing　some　DB　stats.',　
　　'descriptionmsg'　=>　'chstats-desc',　
　　'version'　=>　'1.0.0',　
);　
　
$dir　=　dirname(　__FILE__　)　.　'/';　
　
#　Register　the　extension's　　code/.　
$wgAutoloadClasses['CHStats']　=　$dir　.　'CHStats.body.php';　
　
#　Register　our　ernationalization　files.　
$wgExtensionMessagesFiles['CHStats']　=　$dir　.　'CHStats.i18n.php';　
$wgExtensionAliasesFiles['CHStats']　=　$dir　.　'CHStats.aliases.php';　
　
#　Let　MediaWiki　know　about　the　　special　page.　
$wgSpecialPages['CHStats']　=　'CHStats';　
　
?>　

　　在 CHStats.body.php 内创建个新类 CHStats这个新类扩展了 SpecialPage 类在这个构造内化父类然后通过 wfLoadExtensionMessages 加载国际化消息有关 SpecialPage 类构造(利用它可限制访问、隐藏页面等)更多信息请查阅特殊页开发指南页面

　　覆盖 execute 思路方法是为了生成这个页面

清单 5. 生成 CHStats 特殊页

#　This　is　where　the　special　page's　output　is　created.　
function　execute(　$par　)　{　
　　global　$wgOut;　
　
　　#　Initialize　the　output　page.　
　　$this->Headers;　
　
　　#　Do　stuff.　
　　$wgOut->addWikiText(　"Some　stats　about　this　'''Wiki''':"　);　
　
　　$db　=　wfGetDB(　DB_SLAVE　);　
　　//　SELECT　...　FROM　site_stats　
　　$result　=　$db->select(　'site_stats',　
　　　　　　　　　　　　　　.gif' />(　'ss_total_views',　'ss_total_edits',　
'ss_total_pages',　'ss_users'　)　);　
　　$statList　=　.gif' />;　
　　foreach(　$result　as　$row　)　{　
　　　　$statList　=　'*　Total　page　views:　'　.　$row->ss_total_views;　
　　　　$statList　=　'*　Total　page　edits:　'　.　$row->ss_total_edits;　
　　　　$statList　=　'*　Total　#　of　users:　'　.　$row->ss_users;　
　　}　
　
　　$wgOut->addWikiText(　implode(　"\n",　$statList　)　);　
　
　　$wgOut->addWikiText(　"That's　it."　);　
}　

　　在 execute 思路方法内$par 参数是子页面例如如果加载 Special:CHStats/foo$par 将会被设为 foo

　　首先您使用 Headers 思路方法来设置页面 header然后 $wgOut->addWikiText 来编写某些 markup 到输出流您还能够使用 $wgOut->addHTML 来直接编写格式化了 HTML 但我在输出中使用了 wiki markup有关更多信息以及如何向特殊页正确添加 wiki markup 和/或 HTML请查阅特殊页开发指南

　　CHStats 页使用了 wfGetDB 来获得对数据库个引用(使用 DB_SLAVE 进行只读操作使用 DB_MASTER 进行写操作)然后从 site_stats 数据库选择几个字段并使用 wiki markup 将结果格式化为项目符号格式列表

　　此特殊页输出将类似于图 4

图 4. 实际运行中 CHStats




　　CHStats.i18n.php 内国际化串包含个针对每个受支持语言(在本例中为英语、法语、德语和西班牙语)各有项每项中都有个将串 IDs 映射到它们本地文本(希望如此)法语、德语和西班牙语翻译是利用 Google Translate 完成

　　CHStats.aliases.php 具有个类似包含了 CHStats 页面名称本身本地化版本这可让法国用户(比如)以 Spécial:StatsCH 访问此页面

　　添加标记

　　扩展 MediaWiki 另个流行方式是向 markup 添加对新 XML 标记支持这些标记可以基于标记属性或内容生成区别输出并且对于插入内联 HTML 甚至大块格式化了输出非常有用

　　Tag 扩展安装于 extensions 文件夹内其自己目录并使用在本文开始时给出这 3个文件约定让我们来看由我虚构个名为 CHUser 简单扩展:

　　CHUser/CHUser.php — 扩展设置

　　CHUser/CHUser.body.php — 主要扩展代码

　　CHUser/CHUser.i18n.php — 国际化数据

　　CHUser.php 内进行扩展设置类似于我们已经看到过那些只不过这里使用了 $wgHooks 来向 ParserFirstCallInit 列表添加此扩展 init 思路方法首次使用时将会 CHUser::init

清单 6. 设置标记扩展

#　Let　MediaWiki　know　about　the　　tag.　
$wgHooks['ParserFirstCallInit']　=　'CHUser::init';　

　　在 CHUser.body.php 内init 思路方法注册了两个标记:<chuser> 和 <bz>(参见清单 7)这个扩展可在个扩展内提供两个区别标记如果愿意可以轻松组合本文中讨论所有扩展这里并没有任何拆分开来要求(除非您自己愿意)

清单 7. 注册 <chuser> 和 <bz> 标记

public　　function　init(　&$parser　)　{　
　　#　Add　our　<chuser>　tag　handler,　the　continue.　
　　$parser->Hook(　'chuser',　'CHUser::render'　);　
　　$parser->Hook(　'bz',　'CHUser::renderBugzilla'　);　
　　　true;　
}　

　　只要 wiki markup 引擎遇到个 <chuser> 标记它就会 CHUser::render 思路方法而 <bz> 标记将会 CHUser::renderBugzilla

　　<chuser> 呈现思路方法选择指定用户全名和电子邮件地址并将其格式化成围绕用户全名(如果有话) mailto: 链接形式从清单 8 可以看出大多数逻辑只是为了处理在数据库中未出现用户全名或电子邮件地址情况(比如我 wiki 上 Admin 帐户)

延伸阅读