この翻訳は不完全です。英語から この記事を翻訳 してください。

概要

MDN を構築している Kuma プラットフォームにおいて、 wiki 上のコンテンツを自動化するテンプレートシステムは KumaScript と呼ばれています。 KumaScript はサーバー側 JavaScript で実行されており、 Node.js を使用して実装されています。この記事は、 KumaScript の使い方について基本的な情報を提供するものです。

詳細な概要や KumaScript の Q&A については、 MDN 開発チームの KumaScript Fireside Chat を見ていてください (ミーティングはビデオで10分で開始します)。 KumaScript は、以前の MDN で使われていたプラットフォームであり、 MindTouch のためのテンプレート言語であった DekiScript を置き換えました。

KumaScript とは

  • 文書間で繰り返し現れるコンテンツの再利用やローカライズを行う手段 (互換性のラベル、セクションナビゲーション、警告バナーなど)。
  • 他の文書からコンテンツを引用して文書を構築する手段。
  • 他のウェブサイトやサービス (Bugzilla など) からコンテンツを取得して含める手段

KumaScript にはないもの

  • KumaScript は、フォーム送信を受け付けるような対話型スクリプトには対応していません。
  • KumaScript には、データベースやファイルにアクセスしたり、情報を永続的に格納したりする仕組みはありません。
  • KumaScript は、ログイン中のユーザー情報に基づくサイトのパーソナライズには対応していません。
  • KumaScript は、ユーザー情報にアクセスすることはできず、コンテンツとページのメタデータにのみアクセス可能です。

基本

KumaScript は MDN で埋め込み JavaScript テンプレートに利用されています。これらのテンプレートは MDN の筆者ならば誰でも文書内で、マクロを使用して呼び出すことができます。

KumaScript のスクリプトはテンプレートであり、それぞれのテンプレートは Github の KumaScript リポジトリの macros ディレクトリに格納されているファイルです。テンプレートは以下のようなものです。

<% for (var i = 0; i < $0; i++) { %> 
Hello #<%= i %> 
<% } %>

テンプレートは wiki コンテンツのどこからでもマクロで呼び出すことができます。マクロは次のようなものです。

{{ hello("3") }}

マクロの出力は以下のようなものです。

Hello #0
Hello #1
Hello #2

マクロの構文

KumaScript のテンプレートは、以下のようにドキュメントのコンテンツの中でマクロとして呼び出すことができます。

{{ templateName("arg0", "arg1", ..., "argN") }}

マクロの構文は、以下の規則に基づいて構成されます。

  • マクロのコードは {{ より始まり、 }} で終わります。
  • マクロの最初の部分はテンプレートの名前です。この名前の小文字の値は、 KumaScript の macros ディレクトリ以下のファイル名の小文字の値に一致します。
  • テンプレートは引数を受け付けます。括弧内にコンマ区切りで複数の引数を記述する事ができます。
  • 数値以外の引数は引用符で囲む必要があります。数値は囲む必要はありません。

マクロの引数に JSON を用いる

半実験的な機能 (動作保証なし) として、以下のように引数が一つだけの場合は、引数に JSON オブジェクトを指定できます。

{{ templateName({ "Alpha":"one", "Beta":["a","b","c"], "Foo":"http:\/\/mozilla.org\/" }) }}

このマクロからのデータは、テンプレートコード内で $0 引数のオブジェクトとして利用できます (例えば、 $0.Alpha, $0.Beta, $0.Foo)。これにより、引数の単純なリストで実現することが難しい又は不可能な複雑なデータ構造を、マクロ引数で表すことができます。

なお、この引数の形はとても繊細です。 — 正確に JSON の構文に従っていなければならず、間違いを犯しやすいエスケープ文字の要件が求められます (例えば、すべてのスラッシュをエスケープするなど)。疑わしい場合は、 JSON をバリデーターに掛けてみてください

「{{」を記述する方法

{{」という文字の並びはマクロの開始を示すため、実際にページ内で「{{」及び「}}」を使用したい場合は問題になります。おそらく DocumentParsingError メッセージが発生するでしょう。

この場合、 \{ のように最初の中括弧をバックスラッシュでエスケープすることができます。

テンプレートの構文

それぞれの KumaScript テンプレートは、 KumaScript の macros ディレクトリに格納されているファイルです。これらのファイルは GitHub 上の何らかのオープンソースプロジェクトのファイルとして作成したり編集したりします (詳しくは the KumaScript README をご覧ください)。

KumaScript テンプレートは、いくつかの簡単な規則で、組込み JavaScript テンプレートエンジンによって処理されます。

  • Within a template, the parameters passed in from the macro are available as the variables $0, $1, $2, and so on. The entire list of parameters is also available in a template as the variable arguments.
  • Most text is treated as output and included in the output stream.
  • JavaScript の変数や式は、以下のブロックを用いて出力ストリームに挿入可能です。
    • <%= expr %> — JavaScript の評価値を HTML エスケープして出力(※ <&lt; となる)
    • <%- expr %> — JavaScript の評価値をそのまま表示(※テンプレート内での動的なマークアップ作成に適している)
    • このブロック直下にセミコロンを含めるとエラーとなる(※エラーが発生する例: <%= expr; %>
  • <%%> の間は JavaScript として解釈される。即ち、ループ、条件文、関数などを含める事が可能。
  • <% %> ブロック内は出力ストリームに含まれない。ブロック内の変数などをブロック外で使用する場合は <%= %> を用いる。
    <% for (var i = 0; i < $0; i++) { %>
    Hello #<%= i %>
    <% } %>
    

    ※ 2 行目の行頭でそれまでのブロックが一旦閉じられ、出力ストリームに "Hello" と 変数 i を配置。行末から新しいブロックが開始、3 行目で for 文を閉じて、再びブロックが閉じられています。

  • EJSの構文の詳細については、上流モジュールのドキュメントでご確認ください。

Tips

You can see a list of macros and how they are used on MDN on the macros dashboard.

より高度な機能

KumaScript には前章までに紹介したもの以外に、より高度な機能もあります。

環境変数

When the wiki makes a call to the KumaScript service, it passes along some context on the current document that KumaScript makes available to templates as variables:

env.path
現在の wiki 文書へのパス
env.url
現在の wiki 文書への 絶対 URL
env.id
現在の wiki 文書のユニーク ID
env.files
An array of the files attached to the current wiki document; each object in the array is as described under File objects below.
env.review_tags
An array of the review tags on the article ("technical", "editorial", etc.)
env.locale
現在の wiki 文書のロケール
env.title
現在の wiki 文書のタイトル
env.slug
現在の wiki 文書の URL スラッグ
env.tags
現在の wiki 文書に付与されたタグの名称のリスト
env.modified
現在の wiki 文書の最終更新日を示すタイムスタンプ
env.cache_control
Cache-Control header sent in the request for the current wiki document, useful in deciding whether to invalidate caches

File オブジェクト

個々の file オブジェクトは以下の様なフィールドを持ちます。

title
添付ファイルのタイトル
description
現行版の添付ファイルに関する説明
filename
添付ファイルのファイル名
size
添付ファイルのサイズ(※単位 = bytes )
author
添付ファイルをアップロードした人のユーザ名
mime
添付ファイルの MIME type
url
添付ファイルの URL

タグリストでの作業

The env.tags and env.review_tags variables return arrays of tags. You can work with these in many ways, of course, but here are a couple of suggestions.

Looking to see if a specific tag is set

You can look to see if a specific tag exists on a page like this:

if (env.tags.indexOf("tag") != −1) {
  // The page has the tag "tag"
}
Iterating over all the tags on a page

You can also iterate over all the tags on a page, like this:

env.tag.forEach(function(tag) {
  // do whatever you need to do, such as:
  if (tag.indexOf("a") == 0) {
    // this tag starts with "a" - woohoo!
  }
});

API とモジュール

KumaScript offers some built-in methods and APIs for KumaScript macros. Macros can also use module.exports to export new API methods.

KumaScript では、ビルトインのユーティリティ API だけでなく、wiki 文書として編集可能なモジュール内で新規の API を定義する機能も提供されています。

ビルトインメソッド

This manually-maintained documentation is likely to fall out of date with the code. With that in mind, you can always check out the latest state of built-in APIs in the KumaScript source. But here is a selection of useful methods exposed to templates:

md5(string)
与えられた文字列の MD5 16 進ダイジェストを返す
template("name", ["arg0", "arg1", ..., "argN"])
Executes and returns the result of the named template with the given list of parameters.
Example: <%- template("warning", ["foo", "bar", "baz"]) %>.
Example using the domxref macro: <%- template("domxref", ["Event.bubbles", "bubbles"]) %>.
This is a JavaScript function. So, if one of the parameters is an arg variable like $2, do not put it in quotes. Like this: <%- template("warning", [$1, $2, "baz"]) %>. If you need to call another template from within a block of code, do not use <% ... %>. Example: myvar = "<li>" + template("LXRSearch", ["ident", "i", $1]) + "</li>";
require(name)
Loads another template as a module; any output is ignored. Anything assigned to module.exports in the template is returned.
Used in templates like so: <% var my_module = require('MyModule'); %>.
cacheFn(key, timeout, function_to_cache)
Using the given key and cache entry lifetime, cache the results of the given function. Honors the value of env.cache_control to invalidate cache on no-cache, which can be sent by a logged-in user hitting shift-refresh.
request
Access to mikeal/request, a library for making HTTP requests. Using this module in KumaScript templates is not yet very friendly, so you may want to wrap usage in module APIs that simplify things.
log.debug(string)
Outputs a debug message into the script log on the page (i.e. the big red box that usually displays errors).

組込み API モジュール

There's only one API built in at the moment, in the kuma namespace. You can see the most up to date list of methods under kuma from the KumaScript source code, but here are a few:

kuma.inspect(object)
Renders any JS object as a string, handy for use with log.debug(). See also: node.js util.inspect().
kuma.htmlEscape(string)
Escapes the characters &, <, >, " to &amp, &lt;, &gt;, &quot;, respectively.
kuma.url
See also: node.js url module.
kuma.fetchFeed(url)
Fetch an RSS feed and parse it into a JS object. See also: InsertFeedLinkList

モジュールの作成

ビルトインメソッドの require() を用いると、テンプレート内の変数やメソッドを複数のテンプレート内で使用できるようにモジュール化する事が出来ます。モジュールの定義は、テンプレート内に以下の様に記述する事によって可能です。

<%
module.exports = {
    add: function (a, b) {
        return a + b;
    }
}
%>

Assuming this template is saved under https://github.com/mdn/kumascript/tree/master/macros as MathLib.ejs, you can use it in another template like so:

<%
var math_lib = require("MathLib");
%>
The result of 2 + 2 = <%= math_lib.add(2, 2) %>

このテンプレートの出力は以下の様になるでしょう。

The result of 2 + 2 = 4

自動ロードモジュール

There are a set of modules editable as wiki templates that are automatically loaded and made available to every template. This set is defined in the configuration file for the KumaScript service - any changes to this requires an IT bug to edit configuration and a restart of the service.

For the most part, these attempt to provide stand-ins for legacy DekiScript features to ease template migration. But, going forward, these can be used to share common variables and methods between templates:

Note: You might notice that the DekiScript modules use a built-in method named buildAPI(), like so:

<% module.exports = buildAPI({
    StartsWith: function (str, sub_str) {
        return (''+str).indexOf(sub_str) === 0;
    }
}); %>

The reason for this is because DekiScript is case-insensitive when it comes to references to API methods, whereas JavaScript is strict about uppercase and lowercase in references. So, buildAPI() is a hack to try to cover common case variations in DekiScript calls found in legacy templates.

With that in mind, please do not use buildAPI() in new modules.

Tips and caveats

デバッグ

A useful tip when debugging. You can use the log.debug() method to output text to the scripting messages area at the top of the page that's running your template. Note that you need to be really sure to remove these when you're done debugging, as they're visible to all users! To use it, just do something like this:

<%- log.debug("Some text goes here"); %>

You can, of course, create more complex output using script code if it's helpful.

キャッシュ

KumaScript templates are heavily cached to improve performance. For the most part, this works great to serve up content that doesn't change very often. But, as a logged-in user, you have two options to force a page to be regenerated, in case you notice issues with scripting:

  • Hit Refresh in your browser. This causes KumaScript to invalidate its cache for the content on the current page by issuing a request with a Cache-Control: max-age=0 header.
  • Hit Shift-Refresh in your browser. This causes KumaScript to invalidate cache for the current page, as well as for any templates or content used by the current page by issuing a request with a Cache-Control: no-cache header.

検索キーワードを使用してテンプレートページを開く

When using templates, it's common to open the template's code in a browser window to review the comments at the top, which are used to document the template, its parameters, and how to use it properly. To quickly access templates, you can create a Firefox search keyword, which gives you a shortcut you can type in the URL box to get to a template more easily.

To create a search keyword, open the bookmarks window by choosing "Show all bookmarks" in the Bookmarks menu, or by pressing Control-Shift-B (Command-Shift-B on Mac). Then from the utility ("Gear") menu in the Library window that appears, choose "New Bookmark...".

This causes the bookmark editing dialog to appear. Fill that out as follows:

Name
A suitable name for your search keyword; "Open MDN Template" is a good one.
Location
https://github.com/mdn/kumascript/blob/master/macros/%s
Tags Optional
A list of tags used to organize your bookmarks; these are entirely optional and what (if any) tags you use is up to you.
Keyword
The shortcut text you wish to use to access the template. Ideally, this should be something short and quick to type, such as simply "t" or "mdnt".
Description Optional
A suitable description explaining what the search keyword does.

The resulting dialog looks something like this:

Then click the "Add" button to save your new search keyword. From then on, typing your keyword, then a space, then the name of a macro will open that macro in your current tab. So if you used "t" as the keyword, typing t ListSubpages will show you the page at ListSubpages.

クックブック

This section will list examples of common patterns for templates used on MDN, including samples of legacy DekiScript templates and their new KumaScript equivalents.

Force templates used on a page to be reloaded

It bears repeating: To force templates used on a page to be reloaded after editing, hit Shift-Reload. Just using Reload by itself will cause the page contents to be regenerated, but using cached templates and included content. A Shift-Reload is necessary to invalidate caches beyond just the content of the page itself.

「不明なエラー」からの回復

ページ読込時に、時折、このようなスクリプティング・メッセージが表示される事があります。

Kumascript service failed unexpectedly: <class 'httplib.BadStatusLine'>

これはおそらく、KumaScript サービスの一時的な障害です。ページの再読込みでこの問題が解決する事があります。これで問題が解決しない場合はスーパーリロード(shift + F5)を試してみて下さい。これらの試みの後もエラーが解消されない場合は、file an IT bug for Mozilla Developer Network to ask for an investigation.

Broken wiki.languages() マクロ

幾つかのページで、以下の様なスクリプトエラーメッセージを見かける場合があるでしょう。

Syntax error at line 436, column 461: Expected valid JSON object as the parameter of the preceding macro but...

その様なページを編集状態にした場合、ページ下部に以下の様なマクロが見つかるかもしれません。

{{ wiki.languages({ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }) }}

To fix the problem, just delete the macro. Or, replace the curly braces on either side with HTML comments <!-- --> to preserve the information, like so:

<!-- wiki.languages({ "zh-tw": "zh_tw/Core_JavaScript_1.5_教學/JavaScript_概要", ... }) -->

Because Kuma supports localization differently, these macros aren't actually needed any more. But, they've been left intact in case we need to revisit the relationships between localized pages. Unfortunately, it seems like migration has failed to convert some of them properly.

ページの言語の取得

In KumaScript, the locale of the current document is exposed as an environment variable:

var lang = env.locale;

The env.locale variable should be reliable and defined for every document.

Reading the contents of a page attachment

You can read the contents of an attached file by using the mdn.getFileContent() function, like this:

<%
  var contents = mdn.getFileContent(fileUrl);
  ... do stuff with the contents ...
%>

or

<%-mdn.getFileContent(fileObject)%>

In other words, you may specify either the URL of the file to read or as a file object. The file objects for a page can be accessed through the array env.files. So, for example, to embed the contents of the first file attached to the article, you can do this:

<%-mdn.getFileContent(env.files[0])%>
Note: You probably don't want to try to embed the contents of a non-text file this way, as the raw contents would be injected as text. This is meant to let you access the contents of text attachments.

If the file isn't found, an empty string is returned. There is currently no way to tell the difference between an empty file and a nonexistent one. But if you're putting empty files on the wiki, you're doing it wrong.

テンプレートのローカライズ

Templates are not translated like wiki pages, rather any single template might be used for any number of locales.

So the main way to output content tailored to the current document locale is to pivot on the value of env.locale. There are many ways to do this, but a few patterns are common in the conversion of legacy DekiScript templates:

If/else ブロックを用いる例

The KumaScript equivalent of this can be achieved with simple if/else blocks, like so:

<% if ("fr" == env.locale) { %>
<%- template("CSSRef") %> « <a title="Référence_CSS/Extensions_Mozilla" href="/fr/docs/Référence_CSS/Extensions_Mozilla">Référence CSS:Extensions Mozilla</a>
<% } else if ("ja" == env.locale) { %>
<%- template("CSSRef") %> « <a title="CSS_Reference/Mozilla_Extensions" href="/ja/docs/CSS_Reference/Mozilla_Extensions">CSS リファレンス:Mozilla 拡張仕様</a>
<% } else if ("pl" == env.locale) { %>
<%- template("CSSRef") %> « <a title="Dokumentacja_CSS/Rozszerzenia_Mozilli" href="/pl/docs/Dokumentacja_CSS/Rozszerzenia_Mozilli">Dokumentacja CSS:Rozszerzenia Mozilli</a>
<% } else if ("de" == env.locale) { %>
<%- template("CSSRef") %> « <a title="CSS_Referenz/Mozilla_CSS_Erweiterungen" href="/de/docs/CSS_Referenz/Mozilla_CSS_Erweiterungen">CSS Referenz: Mozilla Erweiterungen</a>
<% } else { %>
<%- template("CSSRef") %> « <a title="CSS_Reference/Mozilla_Extensions" href="/en-US/docs/CSS_Reference/Mozilla_Extensions">CSS Reference:Mozilla Extensions</a>
<% } %>

Depending on what text editor is your favorite, you may be able to copy & paste from the browser-based editor and attack this pattern with a series of search/replace regexes to get you most of the way there.

My favorite editor is MacVim, and a series of regexes like this does the bulk of the work with just a little manual clean up following:

%s#<span#^M<span#g
%s#<span lang="\(.*\)" .*>#<% } else if ("\1" == env.locale) { %>#g
%s#<span class="script">template.Cssxref(#<%- template("Cssxref", [#
%s#)</span> </span>#]) %>

Your mileage may vary, and patterns change slightly from template to template. That's why the migration script was unable to just handle this automatically, after all.

文字列値と switch

Rather than switch between full chunks of markup, you can define a set of strings, switch them based on locale, and then use them to fill in placeholders in a single chunk of markup:

<%
var s_title = 'Firefox for Developers';
switch (env.locale) {
    case 'de':
        s_title = "Firefox für Entwickler";
        break;
    case 'fr':
        s_title = "Firefox pour les développeurs";
        break;
    case 'es':
        s_title = "Firefox para desarrolladores";
        break;
};
%>
<span class="title"><%= s_title %></span>

mdn.localString() の使用

A recent addition to the MDN:Common module is mdn.localString(), used like this:

<%
var s_title = mdn.localString({
  "en-US": "Firefox for Developers",
  "de": "Firefox für Entwickler",
  "es": "Firefox para desarrolladores"
});
%>
<span class="title"><%= s_title %></span>

p>これは switch 文による分岐よりも簡潔であり、テンプレート内で一種類や二種類程度の文字列のみの翻訳が必要なケースなどでは、switch 文より良い選択となるかもしれません。ロケールにより多くの文字列を切り替える必要がある場合(※例: Template:CSSRef | MDN)は、switch 文 を用いた方が良いでしょう。 if 文を用いた場合が良い場合もあります。適切なものを選択して御利用下さい。

 

When the object does not have the appropriate locale, the value of "en-US" is used as the initial value.

関連情報

ドキュメントのタグと貢献者

タグ: 
このページの貢献者: mfuji09, wbamberg, hamasaki, ethertank
最終更新者: mfuji09,