Manual:HTML 模板

MediaWiki版本：

≥ 1.25 Gerrit change 187728

从 MediaWiki 1.25 开始，MediaWiki 可以从服务器和客户端上的 Mustache 模板生成 HTML 内容。 服务器端模板解析是通过 TemplateParser 类在 PHP 中实现的，该类充当 lightncandy 库的包装器。 客户端模板通过 mediawiki.template* 的 ResourceLoader 模块和 mustache.js 库得到支持。

这与在 wikitext 中的 MediaWiki 模板 的使用无关（例如本文中的 {{MW file/zh }}）。 此处的模板构建的是网页的 HTML，而不是其中的 wiki 内容。

创建模板

若要在代码中使用 HTML 模板，请首先创建一个文件扩展名为 .mustache（例如 MyWidget.mustache）的 Mustache 模板文件。 模板应包含尽可能少的编程逻辑，以便它们易于阅读并提供适当的 关注点分离。 如果您的模板是 MediaWiki 软件核心的一部分，请将其放在 core 的 includes/templates 目录中。 如果它是扩展的一部分，则应在扩展的目录中创建一个专用的 templates 目录来保存它。 模板应遵循 Mustache-5 规范。

模板解析器（服务端）

MediaWiki文件： TemplateParser.php
位置：	includes/Html/
源代码：	master • 1.42.3 • 1.41.4 • 1.39.10
类：	TemplateParser

Before MW 1.40.1:

MediaWiki文件： TemplateParser.php
位置：	includes/
源代码：	master • 1.42.3 • 1.41.4 • 1.39.10
类：	TemplateParser

This class finds template files, reads them, compiles them into PHP code, and expands tags in the template using data you provide to produce the output HTML. MediaWiki compiles templates as needed, and uses caching to store the compiled templates if available (see #Caching below). This avoids developers having to compile templates into PHP files during development or as a build step, or the server writing them to the file system during operation.

To use TemplateParser, first create a new instance of the class:

$templateParser = new TemplateParser();

If your Mustache templates do not reside in core's includes/templates, you need to pass the path to where they reside as the first parameter to the constructor (either relative to your MediaWiki root or relative to the calling file's directory with __DIR__):

$templateParser = new TemplateParser(  __DIR__ . '/templates' );

You then parse templates into HTML by invoking the processTemplate() function. The first parameter to this is the name of your template (the part of the filename before .mustache). The second parameter is an array providing the values needed by the Mustache tags in your template. For example,

echo $templateParser->processTemplate(
    'MyWidget',
    [
        'username' => $user->getName(),
        'message' => 'Hello!'
    ]
);

This replaces any instances of {{username}} and {{message}} tags in the "MyWidget" mustache template with the values you provided, and returns the resulting HTML. (The echo simply prints the generated HTML in the current output context.)

As an example of HTML templating, see includes/templates/NoLocalSettings.mustache as used by includes/Output/NoLocalSettings.php.

缓存

TemplateParser attempts to cache the compiled PHP template. It prefers to use CACHE_ACCEL (See Manual:APC ), but falls back to CACHE_ANYTHING (a general object cache like Memcached or Redis, see Manual:Caching ).

CACHE_ACCEL requires the "apc" extension in PHP 5.4 or earlier, and the "apcu" extension for PHP 5.5+. HHVM has it built-in.

部分

The cache is keyed on a hash of the template file's contents, so if you change a template file, the compiled template will update (you may need to clear your wiki's front-end cache using ?action=purge). However, this does not notice changes to "partial" templates that you include with {{>SubTemplateName}} (bug T113095). So if you change a partial, you need to make cosmetic changes to the parent templates that include it, or restart your cache.

mw.template（客户端）

To use a Mustache template on the client-side, add it to your 资源加载器 module definition first:

'ext.coolExtension.interface' => [
	'templates' => [
		'foo.mustache' => 'templates/foo.mustache',
	],
	'scripts' => [
		'resources/interface.js',
	],
],

The template definition above consists of two pieces, a file path (templates/foo.mustache) and an optional alias (foo.mustache). The alias must be suffixed with the name of the templating language (e.g. '.mustache') so that it knows which compiler to use. ResourceLoader automatically serves the supporting mediawiki.template.xx JavaScript modules, so you don't need to mention anything in dependencies. Once you have added the template to your module, you can retrieve it in JavaScript using mw.template.get():

myTemplate = mw.template.get( 'ext.coolExtension.interface', 'foo.mustache' );

To render the template and data into HTML output, call the compiled template's render() function:

data = {
	username: mw.config.get( 'wgUserName' ),
	message: 'Hello!'
};
$html = myTemplate.render( data );

部分

MediaWiki版本：

≥ 1.27 Gerrit change 206490

Partials are also supported on the client-side. See https://mustache.github.io/mustache.5.html#Partials for more information.

参见

• 手册:SkinMustache.php
• 手册:如何制作MediaWiki皮肤
• Skins:
  • Skin:Vector
• Extensions:
  • Extension:SemanticMustacheFormat (unmaintained)
  • Extension:Mustache i18n (unmaintained)
• Requests for comment/HTML templating library (closed)