JsDoc Toolkitを使う！
JsPlateファイル
最終更新：
aias-jsdoctoolkit
JsPlateファイル
JsPlateファイルは実際に出力されるファイルの雛形となるファイルです。これらのファイルはpublish.jsによって読み込まれ、JsDoc Toolkitがソースコードからパースした様々な情報がその中に埋め込まれます。 JsPlateファイルは「テンプレートファイル」とも呼ばれます。また「テンプレート」という単語がJsPlateファイルを指すこともあります。
目次
概要
JsPlateファイルはJSPやPHPと同様に、ドキュメントとして出力されるテキストデータ内にプログラムを埋め込む形式で記述されます。例えばJsDoc Toolkitの標準テンプレートである"jsdoc"で個々のクラスの詳細情報を示すHTMLファイルの雛形となるJsPlateファイルは"class.tmpl"ですが、これを実際に出力されたHTMLと比較してみると、JsPlateの動作がよく理解できるはずです。
- JsPlateファイルの拡張子は通常 .tmpl ですが、他の拡張子を使用しても特に問題はありません。
JsPlateファイルでデータ埋め込みに使われるプログラム言語（テンプレート言語とも）は"JsPlate"と呼ばれます。JsPlateの詳細はこちらを参照してください。
その他のJsPlate記述のポイントを以下に示します。
- JsPlate内ではJavaScriptコードを使用できます。
- JsPlate内で宣言された変数のスコープは、１つのJsPlateファイル全体で有効です。JsPlateではファイルを超えた変数スコープは作成できませんが、publish.jsで宣言された変数、関数は全てのJsPlateファイルから参照可能です。
- JsDoc Toolkitが提供するテンプレートのためのグローバルオブジェクト（ JSDOC や IO など）を、JsPlateからも参照できます。
データを受け取る
publish.jsがJsPlateファイルからドキュメントを作成するシンプルな例を示します。
- publish.jsの動作に関する詳細はこちらを参照してください。
var symbol = symbolSet.getSymbol("MyClass");
var myTemplate = new JSDOC.JsPlate(SYS.pwd+"../templates/my/template.tmpl");
var output = myTemplate.process(symbol);
}
このときJsPlateオブジェクトの process メソッドの引数に指定されたオブジェクトがdataという変数として template.tmpl に渡されます。
<html><head><title>class {+ data.alias +}</title></head><body>
<h1>class {+ data.alias +}</h1><h2>methods</h2>
<for each="$" in="data.methods" >{+ $.name +}<br /></for>
</body></html>
上が template.tmpl の内容であり、 MyClass に getData() 、 setData() 、 saveData() という３つのメソッドが定義されていたとすると、生成されるドキュメントは以下のようになります。
<html><head><title>class MyClass</title></head><body>
<h1>class MyClass</h1><h2>methods</h2>
getData<br />setData<br />saveData<br />
</body></html>
JsPlateの構文
JsPlateの言語仕様はとても小さく、構文は５つしかありません。
| {+ foo +} | このブロックが記述された位置に値（左の場合はfoo）を出力します。 |
| {! doSomething(); !} | ブロック内でJavaScriptの処理を実行します。 |
| {# comment #} | コメントの構文です。 |
| <for>...</for> | 配列要素やオブジェクトのメンバに順にアクセスするためのループ構文です。 |
| <if>...</if> | 条件分岐の構文です。 |
{+ ... +}
このブロックが記述された位置にブロック内の値を出力します。値の指定は静的な変数でなくてもかまいません。例えば現在の日時を出力するには以下のようにします。
{+ new Date() +}
{! ... !}
このブロック内にはJavaScriptコードを記述できます。コードは複数行にわたることも可能です。{! !}ブロックから出力を行うには、特殊変数 output に出力したい値を設定します。ただし output の値は{! !}ブロックの終端で出力・初期化されるので、他のブロックからは設定も参照もできないことに注意してください。
{+ data.name +} is {!
if (data.isPrivate) output += "private";
if (data.isStatic) {
if (output!="") output += " and ";
output += "static";
}
!}.
{# ... #}
このブロックはコメントを表し、ブロック内の内容は全て無視されます。
<for>...</for>
<for> タグは配列要素やオブジェクトのプロパティに対しループ処理を行う際に使用します。 each 属性には値を格納する変数名を、 in 属性にはループ処理する配列またはオブジェクトを指定します。ループから配列要素をドキュメントに出力するには、以下のようにします。
<ul>
<for each="thing" in="data.things">
<li>{+thing+}</li>
</for>
</ul>
上のコードの動作はオブジェクトのプロパティにアクセスする場合も全く同じです。もし data.things が {Sue: "red", Bob: "blue"} というオブジェクトだった場合、上のコードはこのように出力されるでしょう。
<ul>
<li>red</li>
<li>blue</li>
</ul>
値ではなくキーを出力したいのであれば、組み込み関数 keys を使って以下のように記述できます。 keys はJsPlate内でだけ使用できる関数です。
<ul>
<for each="thing" in="keys(data.things)">
<li>{+thing+}</li>
</for>
</ul>
結果はこうなります。
<ul>
<li>Sue</li>
<li>Bob</li>
</ul>
in 属性はJavaScriptのコードを受け取ることが出来るので、ソートされたキーを取得したい場合は以下のようにします。
<ul>
<for each="thing" in="keys(data.things).sort()">
<li>{+thing+}</li>
</for>
</ul>
for ループの中では、ループ内の要素ごとに生成される特殊な変数を使用することができます。それらは"$(each属性の値)_(特殊変数のタイプ)"という形式の名前を持ちます。値の変数名が foo なら、特殊変数は以下のようになります。
| $foo_key | その要素のキー（オブジェクトのプロパティ名） |
| $foo_i | ループのインデックス番号。オブジェクトの場合も使用できます。 |
| $foo_last | この要素がループ終端かどうかを示すboolean値 |
以下に例を示します。
<ul>
<for each="thing" in="data.things)">
<li>{+ $thing_i+": "+$thing_key+" = "+thing +}</li>
<if test="!$thing_last">---</if>
</for>
</ul>
結果はこうなります。
<ul>
<li>0: Sue = red</li>
---
<li>1: Bob = blue</li>
</ul>
<if>...</if>
<if> タグは、 test 属性の真偽によってブロック内のデータを出力するかどうかを決定します。
<if test="thing=='Bob'">
<em>The Best</em>
</if>
上の例では変数 thing の値が"Bob"だったときだけ、"The Best"が出力されます。下のように <else> タグを使って条件分岐させることもできます。
<if test="thing=='Bob'">
<em>The Best</em>
<else />
<em>meh!</em>
</if>
もちろん、 <for> タグと <if> タグのネストに制限はありません。特定の条件のときだけループさせたり、ループの中で条件分岐を使ったりすることができます。
関連項目
