Help:TemplateData/ja



TemplateData とは
TemplateData (テンプレートデータ) とは、テンプレートとその引数 (パラメーター) に関する情報を蓄積する一つの方法です. ビジュアルエディターがテンプレートエディター内で TemplateData を取得して表示することで、テンプレートを編集しやすくします.

TemplateData により、利用者はテンプレートページに構造化されたデータのごく一部分を書けるようになり、そのテンプレートページを参照読み込みできるようになります (例えば、doc ページで). テンプレートがこのような構造化されたデータを持つことで、ビジュアルエディターの中でちゃんと表示できるようになります. 複雑そうだと感じるかもしれませんが、実際はとても単純です.



TemplateData editor
There is a built-in tool for editing TemplateData. It may not be installed on your wiki yet.

To use the TemplateData editor, go to the template's page (or its documentation subpage) and press the "Edit" button. That will give you a button that says "", just above the open editing window: Click this button to enter the GUI tool for editing TemplateData. The editor allows you to add one row per template parameter and to set the most common attributes. If the page you edited already contains a block of TemplateData, then the information already documented will automatically be shown when you open the correct page in the TemplateData editor. In the first box, you can add or update a short description of the template in plain text. After that, you can use the "Import parameters" and "Add parameters" buttons to document the names and attributes of the parameters that the template uses.

You can list the name of the parameter, any aliases for it, the label and the description that will display to users. The only required field is Name (the first field in each row), which is where you record the exact, case-sensitive name of the parameter. In the pop-up menu, you can choose the type of content that the parameter should receive, such as a string (for plain-text answers), page (for links to other pages), or dates. If the template will produce an error if this parameter is left blank, please mark it as "Required". If the parameter is commonly used or recommended, then mark it as "Suggested". The "Remove" button will delete the parameter's entry from TemplateData.

When you are finished documenting each of the parameters, click "Apply" to insert the pre-formatted TemplateData into the open editing box. You must still save the page, using the normal "Save" button underneath the editing window.

Caution: The TemplateData editor will place TemplateData on either the template page or on a documentation subpage. You determine where the TemplateData will be added by opening (editing) the page that you want the TemplateData to be placed on. However, if multiple TemplateData blocks are placed on the same template, then only one of those TemplateData blocks will be used. If there is already TemplateData on a page, then you need to edit the page where the TemplateData was previously placed to avoid accidentally creating multiple blocks of TemplateData.



TemplateData の構造
TemplateData の構造は JSON の標準に基づいており、かなりシンプルです. TemplateData 内の説明 (description) はプレーンテキスト形式に限られることにご注意ください (ウィキテキスト、リンクなどは使用できません).

最初にすべきことは、テンプレートの説明文下位ページ (/doc) 内の任意の場所に  タグを一組入力することです. 以下のように:

この記述は、ソフトウェアに対して、この一組のタグに挟まれた内容がすべて TemplateData であることを伝え、テンプレートを使用する際に参照するように指示するためのものです.



例
TemplateData 内の記述は標準的なレイアウトに従っています. ここでは「Commons」というテンプレートを例にとって説明します. このテンプレートは、ある主題に関するコモンズのカテゴリにリンクします. このテンプレートには必須の引数が1つあります (コモンズでのカテゴリ名). TemplateData はだいたい以下のようになります:

この TemplateData は、テンプレート内に、以下のように表示されます: {       "description": "記事に関連するコモンズカテゴリにリンクするテンプレート", "params": { "1": {                       "label": "コモンズのカテゴリ", "description": "リンクしたいコモンズのカテゴリ", "default": "Category:CommonsRoot", "type": "string", "required": true }       } }



説明と引数
完了したら "save" (保存) をクリックしましょう. エラーがある場合は、保存できません (保存できないことで混乱させますが、これは何も破壊できないようにするための措置です). エラーに遭遇した場合は、フィードバックページで何をしようとしていたか説明していただければ、喜んでお助けします.

それぞれの情報が「"」(二重引用符) で囲まれていることにご注意ください ( 、 を除く). また、後続のブロックとは「,」(カンマ) で区切られていることにもご注意ください (ただし最後のみカンマ不要).



引数の別名
一部のテンプレートでは、同じ引数について別の名前 (別名) を使用できる場合があります.

例えば、 は、  とも、  とも書けます.

この情報を TemplateData に加えるには、単に、別名を引数の情報に追加するだけでいいのです.



自動入力値
パラメーターには"自動入力"できる値があります. 利用者がページにテンプレートを追加するとき、値も自動的に追加されます. 例では、日付が入力される簡単なテンプレートを示しています.

このような情報をTemplateDataに付記することで、簡単にパラメーター情報の自動入力が行えます.



複数の引数
複数の引数がある場合は、各セクションを繰り返して (「1」タグから始めて) 必要に応じて情報を記入してください. テンプレートに複数の引数がある場合は、TemplateData 内で各引数をカンマ で区切る必要があることにご注意ください. 例を以下に示します:



類似の引数
テンプレートに複数の引数があるとき、同じ種類の引数がある場合があります. この場合、1 つめの引数のみにすべての情報を記述する必要がありますが、残りの引数については 1 つめの引数の情報を「継承」(inherit) できます.



空の雛形
テンプレートに新しい TemplateData を追加する際に、以下の空の雛形をコピーして使用できます. よく使用されるタグのみを記述しています.



制限と問題点

 * 機能の不足 — TemplateData は、わずかな機能しか実装していないツールの実装例に過ぎません. それは、利用者自身が望む機能の追加を助けてくれることを期待しているからです. TemplateData に新しく追加してほしい機能がある場合は、教えてください.
 * テンプレートを表示する際の遅延 — テンプレートに TemplateData を追加すると、テンプレートをビジュアルエディターで開いた際に、追加したメタデータ (TemplateData の情報) が即座に表示されるはずです. しかし、メタデータが表示されるまでに何時間も掛かる場合があります. この場合は、テンプレートページ (説明文 (doc) ページではありません) を空編集することで、強制的に更新させることができます. 空編集をするには、テンプレートの編集画面を開き、何も変更せずに 保存します.
 * 現在の問題点 — 既知のバグおよび機能の要望の一覧は Bugzilla にあります.



Other tools

 * TemplateDataEditor — TemplateData を追加する作業を簡単にするユーザー スクリプト. 現在はフランス語版 (英語版、イタリア語版、日本語版、韓国語版も含んでいます) がありますが、容易に他の言語に翻訳できます.
 * TemplateData Wizard — 対話的なインターフェイスで TemplateData を生成するツール
 * Skeleton TemplateData generator — テンプレートのソース ウィキコードを読み取り、使用されているすべての引数を可能な限り見つけて、引数が列挙された説明文書の骨組みを出力するツール
 * JSONLint — 手作業で作成した JSON を検証して構文エラーを見つけられるようにするツール