Help:テンプレートデータ
 |
注意: このページを編集すると、編集内容が CC0 のもとで公開されることに同意したと見なされます。詳細はパブリック・ドメインのヘルプ ページを参照してください。
|
|
TemplateDataでウィキテキストテンプレートとそのパラメーターの情報を保存するとVisualEditorがそれを取得してテンプレートエディタに表示するため、そのテンプレートを使用したページの編集がしやすくなります。
テンプレートデータ拡張機能はウィキメディア財団が実施するどのウィキにもインストールされています。 自分自身のwikiで使用したい場合は、Extension:テンプレートデータをインストールする必要があります。
テンプレートデータ構文により利用者は小規模な構造化データをテンプレートページに書き込んだり、あるいは書いた構造化データをそのテンプレートページ（例えばテンプレートの解説ページ）に参照読み込みさせることができます。テンプレートが受け取ったこのような構造化データは、ビジュアルエディターに正しく表示されます。これは複雑に聞こえるかもしれませんが、実際には非常に簡単です。
Contents
テンプレートデータ編集ツール
テンプレートデータをもっと簡単に編集できる組み込みツールがあります。
テンプレートデータ編集ツールを使用するには、テンプレートのページ（またはその解説下位ページ）を開き「編集」ボタンを押します。すると編集ウィンドウの上に 「テンプレートデータを管理」（訳注:図ではManage TemplateData）というボタンが表示されます。
このボタンをクリックするとGUI ツールが開き、テンプレートデータが編集できます。
編集ツールを使うとテンプレートの引数の記入と最も一般的な属性の設定ができます。編集したページに既存の一連のテンプレートデータがある場合、該当するページをテンプレートデータ編集ツールで開くと登録済みのデータが自動で表示されます。 1番目のボックス (訳注：図のTemplate description (en)の欄) ではテンプレートの簡略な説明を平文で書いたり更新したりします。 その次の欄では「提案パラメータを追加」または「引数を追加」ボタンを使って、テンプレートに使用するパラメータの名前と属性を登録します（ボタンは図中に "Add suggested parameter(s)" および "Add parameter" と表示）。
テンプレートページが保護されている場合、下位ページにテンプレートコードを複写できます。まずテンプレートページの「提示されたパラメータを追加」ボタンを使ってテンプレートデータの内容をコピーします。次に下位ページに戻って既存のテンプレートコードを削除してから、先ほどコピーしたテンプレートデータの内容をペーストします。 テンプレートデータの内容を下位ページのどの位置にペーストするか確認するには、テンプレートデータを空編集します。その後、タグの<templatedata>と</templatedata>及びその間に挟まれた内容を、先ほどコピーしたテンプレートデータで上書きします。
引数の名前、その引数の別名、ラベルと利用者に表示される説明文を一覧表示できます。また、引数の使用例を提示できます。唯一の必須入力欄は名前（各行の初めにある入力欄）です。そこには、大文字・小文字を区別して正確に引数の名前を記録します。"型"ドロップダウンメニューには、引数が受け取るべき内容の種類（例えば平文の回答には「文字列」、他ページへのリンクには「ページ」、あるいは「日時」など）を選択することができます。空白にするとテンプレートにエラーを起こす引数には、「必須」とマークします。また、よく使われる、あるいは推奨される引数には「推奨」とマークします。「引数情報を除去」ボタンは、テンプレートデータに入力された引数を削除します。
各引数の記述が終わったら「適用」ボタンをクリックし、空いている編集ボックスに整形済みのテンプレートデータを挿入します。編集ツールのウィンドウが閉じても作業はまだ終わりではなく、通常の「投稿」ボタンを忘れずに押して必ずページを保存します。
注意：テンプレートデータ編集ツールがテンプレートデータを配置する先は、テンプレートページか、その解説下位ページのいずれか片方です。テンプレートデータを追加する場所は、それを配置するためにどのページを開く（編集する）かによって決まります。ただし、1件のテンプレートに複数ブロックのテンプレートデータが存在しても、実際にはそれらのブロックのうちの1つしか使われません。ページにテンプレートデータが既にある場合は、テンプレートデータを複数ブロック作るエラーを避けるために、ページ内の既存のテンプレートデータを編集する必要があります。
制限と質問
- 不足している機能 — テンプレートデータをあえて機能を制限したツールのサンプルとして提供したのは、どんな機能を求めているか利用者に教えてもらうことで開発の支援をお願いできないかという考えがあるからです。テンプレートデータの新機能の提案がありましたら、ぜひお知らせください。
- テンプレート表示が遅れる — テンプレートページへ TemplateData を追加後、ビジュアルエディタでテンプレートを開くと、メタデータがすぐに表示されるはずです。しかしながらメタデータの表示には数時間を要する可能性があります。強制的に更新するには (説明文書の下位ページではなく) テンプレートページ自体に空編集をします。空編集を行うテンプレートページを開き、「任意の変更を加えず編集要約欄は空欄のまま」ページを保存します。
- 現在の問題 — 現在のバグや機能要求のリストはWikimedia バグトラッカーで利用可能です。
テンプレートデータの位置
テンプレートデータはそれを説明する対象のページに配置するか、もしくはそこに参照読み込みします。
テンプレート内では常に<noinclude>タグで挟みます。
ページの通常のレンダリングでは#例に示したように自動生成された説明文書を表示します。
テンプレートデータの構造
テンプレートデータの構造は JSON 標準に基づいています。テンプレートデータ内のすべての記述は、平文つまりプレーンテキストでなければならない (ウィキテキストやリンクその他を使えない) ことに気をつけてください。
はじめにやることは、テンプレートの説明文書下位ページのどこかに <templatedata> タグを対になるように記入することです。例えば:
<templatedata>
{
... // テンプレートデータの内容はここに書きます。
}
</templatedata>
こうすると2つのタグの間のすべてがTemplateDataであり、ソフトウェアがテンプレートを使用する際に必ず参照するよう指示します。
例
テンプレートデータ内の説明は標準的な配置に従います。仮に「コモンズ」という名前のテンプレートがあり、特定のトピックに関するコモンズのカテゴリとリンクさせるとします。これに対応する既定のパラメータは1件で、コモンズのカテゴリ名ということにします。その場合のテンプレートデータは次のようになります。
<templatedata>
{
"description": "これは記事についてコモンズカテゴリにリンクするためのテンプレートです。",
"params": {
"1": {
"label": "コモンズのカテゴリ",
"description": "リンクするコモンズのカテゴリ。",
"default": "Category:CommonsRoot",
"type": "string",
"required": true
}
}
}
</templatedata>
記入すると、例えば以下のようにテンプレートページに表示されます。
これは記事についてコモンズカテゴリにリンクするためのテンプレートです。
| Parameter | Description | Type | Status | |
|---|---|---|---|---|
| コモンズのカテゴリ | 1 | リンクするコモンズのカテゴリ。
| String | required |
説明とパラメーター
| description | 最初のタグ"description"はテンプレートの役割を説明します。
|
"description": "これはテンプレートについてコモンズカテゴリにリンクするためのテンプレートです。",
|
|---|---|---|
| format | その次にあるのが "format"です。このテンプレートがウィキテキストの中でどのようなレイアウトで表示されるべきかを説明します。 これには "inline" (既定) と "block" の標準設定にするか、カスタム書式にするか選べます。詳細は下記を参照してください。
パラメータを
パラメータを {{Foo
| bar = baz
| qux = quux
}}
|
"format": inline
|
| params | 次にある "params" タグは、これ以降のセクションでテンプレート内の各パラメータを説明すると示します。
続く全てのパラメータは |
"params": {
... // パラメータをここに記入
}
|
| それぞれのパラメータの下位節では、1番目のタグにはテンプレート内のパラメータ名が入ります。
パラメータに パラメータに "名前がない"、つまり このパラメータに関する情報はすべてパラメータの名前で始まるセクションに含まれます。 |
"1": { // パラメータの名前
... // パラメータに関する情報はここに。
}
| |
| label | 次の"label"に人間が読めるパラメータのタイトルを指定すると、テンプレート編集ツール内に表示します。
|
"label": "コモンズのカテゴリ",
|
| description | それから "description"の箇所は、テンプレート全体の説明ではなく、パラメータの説明です。
|
"description": "リンクするコモンズのカテゴリ。",
|
| default | 次は"default"です。一部のテンプレートは利用者が何も入力しなくても既定値を使います。このパラメータの既定値を利用者に示す項目です。
既定値がない場合はこのパラメーターを無視することが出来ます。 |
"default": "Category:CommonsRoot",
|
| type | そのあとは"type"で、テンプレートエディタがそのパラメータを解釈する方法を制御します。最も一般的なものは以下のとおり。
その他の使用できる型:
|
"type": "string",
|
| required | 続いて "required" があります。true か false のどちらか一方を設定できます。
これは、単にこのパラメータの記入が必須かどうかを決めます。選択しなければ |
"required": true
|
| suggested | "suggested" には、true か false のどちらか一方を設定します。
これはテンプレートの利用に際して当該パラメータが'必須'ではないものの強く推奨される（が強制ではない）状態です。選択しなければ |
"suggested": true
|
| deprecated | 最後の、"deprecated" は true か false、または代わりにすべきことの説明を設定します。
これはパラメータの使用が既に推奨されないものの、いまだに存在していることを示すものです。
この現象は、テンプレートを使用は
するパラメータの組み合わせが変更された場合に起こりえます。
指定しなければ、 |
"deprecated": "代わりに'publicationDate'を使用してください。"
|
処理が終わったら、「保存」を押します。エラーがある場合には保存できません (一瞬、戸惑うかもしれませんが、破壊の予防になります) 。自力でエラーを解決できないときは喜んでお手伝いしますので、フィードバック用のページに投稿して何をどうしたかったか説明をお願いします。
注記：ダイナミックなTemplateDataを作成するためにハックテンプレートの不正使用を試みようとする場合、保存前にエラーの検証はできない点にご注意ください。
注記：どの情報も半角の二重引用符で挟んで (例外は true と false) 、かたまりごとに半角カンマで区切ります (ならびの末尾を除く) 。
特別な書式
テンプレートデータ編集ツールでカスタム書式を編集する場合は\nと入力するか、改行キーを押して新しい行を表現します。どちらも入力欄の表示は↵です。
| 目的 | 書式文字列 | 出力 |
|---|---|---|
| インラインの書式設定 | {{_|_=_}} inline
|
{{Foo|bar=baz|qux=quux}}{{Bar}}
|
| ブロックの書式 | {{_\n| _ = _\n}} block
|
{{Foo
| bar = baz
| qux = quux
}}{{Bar
}}
|
| パラメータ名の前に空白（スペース）を入れない。テンプレートごとに改行 | \n{{_\n|_ = _\n}}\n
|
{{Foo
|bar = baz
|qux = quux
}}
{{Bar
}}
|
| パラメータの位置をインデントで揃える | {{_\n |_ = _\n}}
|
{{Foo
|bar = baz
|qux = quux
}}{{Bar
}}
|
| パラメータ名をすべて一定の文字数に調整 | {{_\n|_______________ = _\n}}\n |
{{Foo
|bar = baz
|qux = quux
|veryverylongparameter = bat
}}
{{Bar
}}
|
| 前の行の終わりにパイプ記号を置く | {{_|\n _______________ = _}}
|
{{Foo|
bar = baz|
qux = quux}}{{Bar}}
|
| インラインの書式。半角スペースを多用、行頭の典型 | \n{{_ | _ = _}}
|
{{Foo | bar = baz | qux = quux}}
{{Bar }}
|
| 行頭に置くテンプレート。パイプ記号に続けてパラメータを置き、インデントで位置を揃える | \n{{_ |\n _______________ = _}}
|
{{Foo |
bar = baz |
qux = quux}}
{{Bar}}
|
パラメーターの別名
テンプレートによっては同一のパラメータに複数の異なる名前が使えます。
例えば、{{Commons|category=Apples}} を別表記で {{Commons|Apples}} あるいは {{Commons|link=Apples}} とすることができるテンプレートがあります。
この情報をテンプレートデータに加えるには、別名をパラメータの情報に記入するだけです。
"params": {
"カテゴリ": {
...
"aliases": ["1", "リンク"]
}
自動値
パラメータには "autovalue" つまり自動値を設定できます。利用者がページにテンプレートを用いる場合、この値を自動で付与します。例えばクリーンアップのテンプレートの多くには日付の記入が必須で、テンプレートの日付パラメータにあらかじめ自動値を設定しておくと、日付にその値を自動で付与できます。
この情報をテンプレートデータに加えるには、自動値をパラメータの情報に記入するだけです。
値に接頭辞のsubst:を付けると、配置が揃います：
"params": {
"日付": {
...
"autovalue": "{{subst:CURRENTMONTHNAME}} {{subst:CURRENTYEAR}}"
}
複数のパラメータ
複数のパラメーターを与えるには、各セクションを単純に (タグの "1" から順に) 繰り返し必要なだけ記入します。注記: テンプレートに複数のパラメーターを含めるには、以下の例の通り、テンプレートデータ内で必ずカンマで区切ります:
"params": {
"1": {
...
}, // このカンマを見落とさないこと
"2": {
...
}, // こちらにもあります:
"3": {
...
}
}
同様のパラメーター
テンプレート複数のパラメータが含まれる場合、いくつかが同種という可能性があります。同種のパラメータがあるなら、1番目だけに属性をすべて与えれば充分で、2番目以降はそれを「引き継ぐ」ことになります。
"params": {
"トピック1": {
"label": "トピック",
"description": "曖昧さ回避ページにあげたトピック",
"type": "string"
},
"トピック2": {
"inherits": "トピック1"
},
"トピック3": {
"inherits": "トピック1"
},
}
ブランク定型
以下に示す値が空の定型を複写して使用すると、特定のテンプレートに新規にテンプレートデータを記入できます。タグは最も一般的なタグのみ提供してあります。
<templatedata>
{
"description": "",
"params": {
"1": {
"label": "",
"description": "",
"type": ""
},
"2": {
"label": "",
"description": "",
"type": ""
}
}
}
</templatedata>
エラー
Syntax Error in JSON / Bad JSON format
Due to a long standing bug, users using the old wikitext editor are able to save pages which have certain types of invalid JSON, such as duplicate keys or trailing commas (details: タスク T128029). However if you attempt to save this page in a JavaScript based editor, such as VisualEditor or the 2017 Wikitext editor, you will see an error message "Syntax error in JSON," as the JavaScript parser is stricter and doesn't allow invalid JSON. Additionally, if you attempt to open up such invalid JSON with the Template Data GUI editor, you will see the error message, "Bad JSON format." To fix these errors, you can enter the JSON block into an external JSON validator, such as https://jsonlint.com/, and it will highlight the problematic commas and keys so they can be removed.
その他のツール
- Help:Extension:TemplateWizard
- ツールバーのダイアログウィンドウ。テンプレートデータから生成したフォームを使い、テンプレートにウィキテキストを記入するために使用。
- TemplateData Wizard
- テンプレートデータを生成するツール。インタラクティブなインターフェースを使用。
- Skeleton TemplateData generator
- テンプレートのソースウィキコードを解読するツール。使用するすべてのパラメータ（引数）を検出し、値が空のドキュメントとパラメータの一覧を出力。
- JSONLint
- 手入力したJSONが正しいかどうか確認するツール。構文エラーの発見に役立つ。
- このウィキにあるテンプレートデータを備えたテンプレートの一覧
- ドイツ語版ウィキペディアのテンプレートに備わったテンプレートデータでは、ボックス内にテンプレートのデータを表示。テンプレートはそのデータとともにドイツ語版ウィキペディアの特定のカテゴリに分類される
