Help:TemplateData/ja

拡張機能  とはウィキテキスト テンプレートに関連するパラメーターの情報を保存し、それを取得した編集インターフェイスにテンプレート エディターを使って表示させます -- 編集者がそのテンプレートを編集したり、ページに使用しやすくするためです.

2019年4月時点ではテンプレートデータ機能はウィキメディアのすべてのウィキに既定の UX (利用者体験) として組み込まれました. アカウントを登録していてもいなくても、参加する利用者がテンプレートを追加すると適用されます. 既定のソース編集でもビジュアル編集でも適用しており、その点はスクリプトやツール、ガジェットの一部と同様です. この機能を自身のウィキで使用したい場合は、 をインストールします.

特定のテンプレートに TemplateData を組み込み、この拡張機能に対応させる手順は、テンプレートの説明文書のページに JSON の小さなコードブロックを追加します (詳細は下記の説明をご参照ください). 実行する方法は手動か、 TemplateData 編集機能を使うかです. 後者は 画像的な UI で、TemplateData 拡張機能を組み込んだウィキの、それぞれのテンプレートに対応する「/」ページから利用できます. JSON にはパラメーターの一覧が含まれ、テンプレートの個々のパラメーターの情報と、テンプレート本体の説明を添えてあります（詳細は下記をご参照ください）.

個別のテンプレートに TemplateData が設定されると、この情報は利用者がテンプレートを追加するたびユーザーインターフェースに表示されます. これを使って編集したり当該のテンプレートを追加した場合、時にはそのせいでエディタの挙動を変化させることもあり、すると当該のテンプレートを追加しようとした利用者は、手順がずっと楽になります.

歴史
テンプレートデータTemplateData の開発は2013年、 を念頭に始まり、当時は MediaWiki の試験段階に置かれました. VisualEditor はウィキメディアのウィキ群で採用するメインの視覚的な編集インターフェースで、TemplateData ではテンプレートの追加をするとき、より利便性の高いエディタとしてこれを容認しています. VisualEditor では即時に公式にサポートされました. 2013年から2016年にかけてさまざまなウィキメディアのウィキ群で VisualEditor を既定の機能として導入した結果、TemplateData もその一環となりました.

2016年12月時点で VisualEditor インターフェースはベータ機能として、ソースコード編集に使えるようになりました. これを名づけて. このとき初めて、TemplateData の機能をソース編集に導入しました.

サム・ウィルソン Sam Wilson は2018年3月に を発表、TemplateData を利用してテンプレートを追加する手順をより簡略化するために既定の Wikimedia ソースエディター  (別称2010年ウィキエディター) に GUI テンプレート エディター拡張機能を導入しました. 2019年4月には Wikimedia の全てのウィキで TemplateWizard を2010年ウィキテキスト エディターの既定部分に導入しています. これはすなわち、現状でウィキメディアのウィキ群における TemplateData は、ビジュアル編集でもソース編集でも規定の部分となったことを意味します.

テンプレートの追加/編集
TemplateData の追加手順は、まずテンプレートのページを「/Template:テンプレートの名前」から開きます.

Checking the current state
Before adding or editing TemplateData, check whether the template has a documentation subpage. Then check whether the template already contains TemplateData and, if so, whether it's located on the template page or the documentation subpage.

説明文書下位ページ
Wikimedia のほとんどのウィキでは、使い方の解説その他のデータなどテンプレート本体に書いてはいけない情報を、主に2つの方法で保存しています. 情報とはたとえばテンプレートのカテゴリなどで、保存先は次になります.


 * ほぼ全てのテンプレートは、テンプレートのメインページに書く場所のないもの（使い方の注記その他のデータ）を下位ページの解説文書ページに記しています（訳注：右は下位ページの指定例）. 「/Template:Templatename/doc」 この類のページではDocumentationテンプレートが当該の /doc のコンテンツを全てテンプレートのページに呼び出しており、これによってテンプレートのソースコードの見た目がずいぶんとスッキリします.
 * 特定のテンプレートに /doc ページがあるかさっとチェックするには、「Test Template Info-Icon - Version (2).svg テンプレートの解説文書」 (あるいは同類の) 見出しの行の端に「[表示] [編集] [履歴] [キャッシュを破棄]」のリンクがあるかどうかでわかります.


 * 一部のテンプレートはそれらの情報をそのメインページに置いています. この事例では、タグの間に記してある が書いてある箇所を探します.

Different wikis may present all this differently. ごくまれには、上記のチェック項目を確かめたのに、それでもメインのテンプレートページに説明文書が残る場合があります. 利用者が「 」から「 」までの間にカスタム化した /doc ページ名を使い、なおかつ「 」の後にコンテンツを記入した場合に発生します.

You can also look for a notice at the bottom of the page similar to this: "The above documentation is transcluded from Template:Templatename/doc".

Templates without documentation subpages
特定のテンプレートに解説を記した下位ページがない場合、選択肢は2つあります. この処理後、解説文書の下位ページに TemplateData を追加します.

doc 下位ページの作成、解説文書のコンテンツの移動
実行するにはテンプレートのメインページで「」または「」をクリック、 タグに挟まれた記述を探します. 位置は通常、ページ最下部.

内容は以下のようになります.

もしかしたら既に、TemplateData が存在するかもしれません. その場合、内容は以下のようになります:

「 」に続き、「」より前にある記述を選択してカット（訳注＝外部エディタにペーストして仮に保存しておくのがお勧め）. 次に「 」を削除すると、次の文字列が残るはずです.

テンプレート ページを保存してください.

Now, to create the new subpage, look at your browser's address bar and add /doc to the end of the URL. Press Enter, then choose the option to create a new page.

ご利用のウィキでDocumentation subpageの通知テンプレートを採用しているなら、ページ最上部に記入しておきます. その他のテンプレートの追加も検討しましょう. ご利用のウィキで採用済みならPurge buttonやPurgeのリンクがその一例です. 詳細情報は m:Help:Template documentation を参照してください.

Insert the text you cut or saved in the previous text (beneath the notice template, if applicable).

Wrap any categories in tags so that they apply only to the template's main page:

多くのウィキでは というテンプレートがあります. Use this template here if it's likely that the template you're editing exists in a sandbox version (located at "Template:Templatename/sandbox") in order to prevent the categories from applying to the sandbox page:

最後に、ページを公開します.

解説下位ページでTemplateDataを追加または編集でき、#方法節の指示に従います.

テンプレートのメインページに TemplateData を追加もしくは編集する

/doc ページを作成できない場合は、TemplateDataをテンプレートのメインページで追加/編集できます. 手順は#方法に従います.

テンプレートに解説文書の下位ページがある場合は、すでに TemplateData があるかどうか調べ、また所在はテンプレートのページか、解説文書の下位ページか確認します.

別の方法として、TemplateData 拡張機能はこの検査を利用者に代わって実行します. どちらかのページで「」または「」をクリック. どちらかのページにテンプレートに対応する TemplateData がある場合、ページ上部に黄色の通知が現れ、内容は次のいずれかを表示します.



or

特定のテンプレートの解説下位ページに TemplateData がある場合

当該のテンプレートの TemplateData が、解説用下位ページに存在する場合、編集はそちらで行ってください. 実行するには見出し テンプレート解説文書」 (または同等), の右にある 「[編集]」ボタンをクリック、または既に/docページを開いている場合は、ページ上部の「」または「」をクリックします. TemplateDataの追加もしくは編集は、#方法に従います.

もしメインページに TemplateData がある場合

当該のテンプレートの TemplateData がメインページに存在する場合、ここでも選択肢は2つあります.


 * このとき解説文書の下位ページに移動してもかまいません. こちらの選択肢の方がお勧めです.


 * もう一つの選択肢は、テンプレートのメインページで編集する.

TemplateData を解説会ページに移動するには

実行するにはテンプレートのメインページで「」または「」をクリック、タグの位置を探し、その中の タグに挟まれた記述を見ます. 内容は以下のようになります.

タグとそれに挟まれた内容だけを指定し、コード文から切り出したらページを保存.

次に、解説会ページを編集するため見出し「 テンプレート解説文書」 (もしくは同等) の右にある「[編集]」ボタンをクリックします.

見出しを「TemplateData」のように記入し、この見出しの下に TemplateData を貼り付けます.

TemplateDataの編集ができる状態になったので、#方法節の指示に従います.

テンプレートのメインページで TemplateData を編集するには

もしメインのテンプレートページから TemplateData を解説ページ /doc に移動したくない場合は、そのままメインの方で編集が可能です. #Methods節に TemplateData の編集方法を示します.

テンプレートに/docページはあるがまだ TemplateData がない場合

もしテンプレートにまだTemplateDataがない場合には、解説下位ページに追加する必要があります.

実行するには見出し「 テンプレート解説文書」 (または同等) の右にある 「[編集]」ボタンをクリック、または既に/docページを開いている場合は、ページ上部の「」または「」をクリックします. 見出しを「TemplateData」のように記入し、この見出しの下に追加します. #Methods節に TemplateData の追加方法を示します.

TemplateData エディタの方法
これはTemplateDataの編集もしくは追加のいちばん簡略な方法で、経験が浅い利用者にも使えます.

TemplateData 拡張機能は画像で手順を示す UI を採用し、TemplateData の追加と編集を行います. It is part of the TemplateData extension, available on any template's page (or documentation subpage) by clicking "" or "".

操作として「」「」のいずれかを押すと、編集枠のページ名の上部にボタン「」が現れます.



このボタンをクリックするとTemplateData 編集機能が開きます. ページに既存のテンプレートデータがある場合、自動的に表示されます.



上述の窓には次の機能があります.


 * The top item chooses the language of the interface text. It allows you to enter text content in multiple languages, displayed to users based on their settings in Preferences, not based on the wiki's language; different wikis have entirely different template databases. If no language TemplateData exists, the interface will only offer users the wiki's own language, but users can click "" to add more inputs. The language code is displayed in brackets next to the parameters to which it can be applied, such as descriptions and labels.
 * 次の項目はテンプレートの説明です. ここにテンプレート全体の説明を記し、テンプレートの追加作業中、あちこちで利用者に表示します. このパラメータとその効果は こちらにまとめてあります.
 * 3番目の項目はテンプレートのウィキテキストの書式を制御します. このパラメータは、利用者が「」を押したときにウィキテキストをどうレイアウトするか指定し、主に2種類、 (1行表示) と   (複数行) のどちらかになります. このパラメータとその効果のまとめは、こちら.
 * 利用者が「」を選択した場合、「」のところにウィキテキストを入力します. 書式のまとめはこちらで、利用者が「」を押したときに示す、当該テンプレートに特別のレイアウトを生成します.


 * The fourth item configures a template's parameters. If parameters have already been defined in TemplateData, this area displays them in a list. If the template's source code specifies parameters for which no TemplateData exists, you may see a button labeled "". The editor extracts these suggestions from the template's source code by looking for  or  . Clicking "" will add these parameters using their names as defined in the source code. A green notice will also appear at the top, for example, "".
 * いちばん下に「パラメータを追加」があります. ここでは手動でパラメータを追加でき、自分で選んだ名前でカスタム化できます.

次の段階として、このリストにあるパラメータをどれでもクリックしてください. するとパラメータの情報を編集できます.



前述の機能もその効果も全て、#パラメータの名称の節に解説しました.

編集を終えたら、「」をクリックしてください. するとページの最下部、 タグの直前に TemplateData が自動で挿入されます. あるいはページ状に既に存在するなら、その TemplateData を上書きして更新、記入された位置は維持されます. TemplateData の記述内容は、やはり「」ボタンを押した時に反映されます.

TemplateData エディタは TemplateData の最下部に、パラメーターの  を作成 (もしくは既存であれば更新します). には TemplateData エディタに表示される順序にしたがい TemplateData パラメータを並べてあります. You can change the  by dragging the parameters up and down in the TemplateData editor using the three horizontal bars on the left. and its effects are described here.

その後、「」ボタンを押してページの改訂箇所を保存します.

手動の処理
代替の方法として、手動でTemplateDataの追加や編集ができます. 状態によってはこの方法を使いたい、もしくはそれしかない場合もあるかもしれません. テンプレートデータの構造は JSON 標準に基づいているものの、利用者は JSON がわからなくても TemplateData を配置できます. テンプレートデータは複数の非常に簡単な規則に従い、40、50件の事前に定義されたパラメーターと値に限定して対応し、通常は  の書式に従います.

TemplateData を手動で追加する

事前準備：


 * テンプレートの説明文書下位ページにTemplateData を記入する場合、当該ページのどこに配置してもかまいません. ご利用の言語版で通例となる配置場所がないかどうかご確認ください. たとえばウィキペディア英語版だと、TemplateData の配置は通常、説明文書ページの最下部です. ドイツ語版ならページ最上部です.
 * テンプレートのメインページに TemplateData を追加する場合 (処理は避けるべき理由は#Prior checksをご参照)、きちんと  タグで囲んだかどうか十分に留意する必要があります.

まず初めに、対象ページで「編集」Edit または「ソースを編集」Edit source ボタンを押し、次に TemplateData を追加する箇所にカーソルを移動したら、見出しを「TemplateData」などと記入します.

ウィキの (全てではなく) 多くではテンプレート TemplateData header を採用しており、TemplateData に関する短い通知を追加します. もしお使いのウィキでもそうであれば、目次の次の行に後者を追加します.

TemplateData の書き初めは、改行して開くタグと閉じるタグとしてとその内側に半角の波カッコで挟み、改行して次のセットを記入します.

次に、空行に弓カッコ2個を書き、インデントを挟みこんでからパラメータの記述をはじめます. パラメータごとの詳細は#TemplateData parametersの節をご参照ください. ほとんどはオプションですが、中には強く推奨されるものもあります.

パラメータの記入の順序は決まっていないものの、 TemplateData 解説文書に登場する順序に合わせ、編集者の使いやすさを優先すると、次の順序です.

またパラメータの順序は、たとえば オブジェクトがオブジェクト内に置かれたか確認し、エラーがあると保存時に「予期しないプロパティ」というメッセージが表示されます.

例

クリーンアップ用のテンプレートを想定すると、サンプルとなる TemplateData を例示します. このテンプレートは通知を表示するもので、ソースコードの設定により、当該ページはテンプレート入力時点の年と月に合わせて日付付きのカテゴリに分類されます. 通知には指定により、トークページの特定の節へのリンクを書くことができます. その場合、TemplateData の見た目は例えば次のとおりです.

対応する TemplateData 解説ページの表示を以下に例示します.

{	"description": "Use this template to indicate that an article is in need of cleanup.", "format": "inline", "params": { "date": { "label": "Month and year", "description": "The month and year that the template was added", "type": "string", "autovalue": " ", "example": "January 2013", "suggested": true },		"reason": { "aliases": ["1"], "label": "Reason", "description": "The reason the article is in need of cleanup", "type": "string" },		"talk": { "aliases": ["talksection"], "label": "Talk page section", "description": "The section of the talk page containing relevant discussion", "type": "string" }	},	"paramOrder": [ "date", "reason", "talk" ] }

TemplateDataのパラメーター
TemplateData の各パラメータを、以下に列挙して説明と例を示します. これらの一覧はExtension:TemplateData#Format節にも掲出してあります.

パラメータの名称
注記：特定のパラメータに関して      のどれも   に設定されていない場合、ステータスは TemplateData 解説文書に   として表示されます.

処理が終わったら、「」を押します. エラーがある場合には保存できません (一瞬、戸惑うかもしれませんが、破壊の予防になります). 自力でエラーを解決できないときは喜んでお手伝いしますので、フィードバック用のページに投稿して何をどうしたかったか説明をお願いします.

注記：ダイナミックなTemplateDataを作成するためにハックテンプレートの不正使用を試みようとする場合、保存前にエラーの検証はできない点にご注意ください.

注記：どの情報も半角の二重引用符で挟んであり (例外は  と  ) 、かたまりごとに半角カンマで区切る点に注意します (ならびの末尾を除く).

type パラメーター
そのあとは パラメータの役割は、テンプレートエディタに、そのパラメータ値の解釈を伝えることです. テンプレート編集機能は場合により、特定のパラメータに限定して TemplateData 値に適合するように UI を補修しており、例えば利用者が入力できる有効な値を指定のタイプに限定するなどです. このパラメータには、テンプレートのパラメータもしくはその設定値に影響する機能はありません. テンプレート編集者が編集モードでどう表示するか、パラメータをどう扱うか指定するのみです.

使い方

これを使用するには  パラメータを追加し、その後にコロン+スペースを足してから、下記の表にある引用符で挟まれた値のどれかを選んで記入します.

例:

効果

2020年2月時点でTemplateWizard が全13件の変数種別のうち8件を表示したのに対し、VisualEditor および2017年版ウィキ文エディタは5種のみでした.

特定の入力値は、それに対応するテンプレートエディタ機能の更新に従って効果が変わる場合もあります. VisualEditor ならびに 2017年版ウィキテキスト エディタの場合、そのような影響は Phabricator タスク T55613 で追跡しています. 同様のサポートをするには TemplateWizard が真偽値に対応する必要があり、T200664 で追跡しています.

現在の既知の問題は以下にまとめてあります.

特別な書式
の値を編集するときはカスタム化した書式を作成するものとし、その方法は既に定義のある規則に従いウィキテキストの記号一式を記入することです.


 * - テンプレート開始
 * - コンテンツ (例＝文字列、整数、パラメータ. ) この半角アンダーバーは、特定の値の最小値を文字数で指定し、 のように連続して使用もできます. この文字数より少ないと、足りない文字数にスペース（空白）を補います.  これはパラメータ名の後ろに続く等号（イコール）を任意の一意の位置揃えするために使えます (改行に続く新しい行で と併用した場合. )
 * - パイプ記号 (パラメータの区切り記号)
 * - 等号 (パラメータの値の前に置く)
 * またはEnterキーを押す - 新しい行を追加（入力欄に と表示）
 * - スペース (新しい行を字下げするには と併用)
 * - テンプレート終了

ウィキテキストは最小値 以上とし、足りないと文字列の書式が不適切というエラーになります.

ブランク定型
以下に示す値が空の定型を複写して使用すると、特定のテンプレートに新規にテンプレートデータを記入できます. タグは最も一般的なタグのみ提供してあります.

JSON の構文エラー、もしくは　JSON 書式の間違い
このエラーの原因は特定の無効な JSON コードを含む TemplateData を保存しようとしており、VisualEditor もしくは2017年テキストエディタ (JavaScript ベースのエディタ) で、キー (パラメータ) の重複もしくはカンマが足りない・不用、などの場合が想定されます.

「JSON の構文エラー」とは VisualEditor または2017年ウィキテキスト エディタを使い、当該のコードを保存しようとした場合、また「JSON 書式の間違い」とはTemplateData GUI エディタを使ってテンプレートページ内の当該のコードを開こうとした場合に発生します.

These errors can be difficult to detect and come in too many forms to list. The best way to avoid them is to edit template data exclusively with the TemplateData editor; the best way to detect them once they've occurred is to use an external JSON validator, such as JSONLint, which will highlight errors and aid in fixing them.

The 2010 wikitext editor does not check for invalid JSON thanks to an old, unfixed bug. Pages that contain invalid JSON may throw alarming "" messages. To fix these errors, your best bet is to use a JSON validator (see above).

必須のプロパティ「paramOrder(number)」が見つかりません.
このエラーの原因は 内のパラメータが に記述がない場合です. 半角四角カッコ内の数字は、 内に本来、あるべきなのに、そこに書かれてないパラメータを指示します. パラメータが先頭から何番目か示してあるのですが、実際の位置マイナス1で表示されていて、 はアレーだからです. つまり1位が0で始まるため、1は2位などと続きます.

修正方法は、 に記述したパラメータが全点、 にあるか確認し、記入します. 代替策として、 オブジェクトを除去するとエラーは出なくなります.

プロパティ "paramOrder(number)" の値が無効です.
このエラーの原因は 内のパラメータが に記述がない場合です. 半角四角カッコ内の数字は、 内に記述されているが、本来、そこに書くべきではないパラメータを指示します. パラメータが先頭から何番目か示してあるのですが、実際の位置マイナス1で表示されていて、 はアレーだからです. つまり1位が0で始まるため、1は2位などと続きます.

修正方法は、 に記述したパラメータが全点、 にあるか確認し、記入します. 代替策として、 オブジェクトを除去するとエラーは出なくなります.

プロパティ "params.parametername.required" の種別は "boolean" になるはずです.
このエラーは、必須 の、もしくは推奨 される値を引用符で挟んだ場合に発生します.

文字列ではなく真偽値であるため、引用符は不要です. 修正方法は、これらパラメータ または の前後の引用符を除去します.

プロパティ "format" が取る値は……
もし  パラメータは存在するが設定値が   または   以外、あるいは書式ストリングが無効の場合、次のエラーメッセージが表示されます. 「プロパティの「書式」は「inline」「block」もしくは有効な書式の文字列にしてください」.

修正するには、 直後の設定値が   もしくは   と等しく、また文字のつづりに間違いがないことを確認します. 代わりの方法としてウィキ文であること、 は最少で、かつテンプレートの障害を防ぐため構文にエラーがないことを確かめ、とくに等号「=」が連続しないか大カッコ記号「 {」と「} 」のペアが崩れて片方だけ多い・足りない状態ではないかを確認します. カスタム書式の構文の詳細は#Custom formats節をご参照ください. 代替策として、 オブジェクトを除去するとエラーは出なくなります.

予期しないプロパティ"parametername "が使われています.
エラーの原因は$2に記述のない$1内にパラメータを定義したからです. 原因はスペル間違いにあります.

別の原因としてそのオブジェクトのパラメータではないのに、TemplateData オブジェクト内にパラメータを宣言した場合です. スペル間違いか、上位のオブジェクトの下位に置かれた TemplateData オブジェクト内にそのパラメータを記入していませんか.

一例として、パラメータ をTemplateData のオブジェクト 内ではなく、ルートに書いてしまったとします.

別の方法として、 内のテンプレートのパラメータに想定外のパラメータが含まれる場合、名称はエラー内の"パラメーターparametername." 配下に表示します.

修正方法は、パラメータ名のスペル間違いの修正と、さらにパラメータを正しい位置におくことです. それに加え、TemplateData オブジェクトに該当しないパラメータを記述していないか確認します. 特定のオブジェクトにどのパラメータが設定されているか、#TemplateData parametersの節をご参照ください.

必須のプロパティ「params」が見つかりません.
エラーの原因は、 TemplateData 内に  オブジェクトが1点もないからです. このオブジェクトは必須であり、パラメータ1個ごとの詳細を含むからです. エラーの修正方法は、オブジェクトを記入することと、スペル間違いの修正です. パラメータの追加方法は、このページの前述の節をご参照ください.

制限とフィードバック

 * 不足している機能 – テンプレートデータをあえて機能を制限したツールのサンプルとして提供したのは、どんな機能を求めているか利用者に教えてもらうことで開発の支援をお願いできないかという考えがあるからです. テンプレートデータの新機能の提案がありましたら、ぜひお知らせください.
 * テンプレート表示が遅れる – テンプレートページへ TemplateData を追加後、ビジュアルエディターでテンプレートを開くと、メタデータがすぐに表示されるはずです. しかしながらメタデータの表示には数時間を要する可能性があります. 強制的に更新するには (説明文書の下位ページではなく) テンプレートページ自体に空編集をします. 空編集を行うテンプレートページを開き、「任意の変更を加えず編集要約欄は空欄のまま」ページを保存します.
 * 現在の問題 – 現在のバグや機能要求のリストはWikimedia バグトラッカーで利用可能です.

その他のツール

 * : ツールバーのダイアログウィンドウ. テンプレートデータから生成したフォームを使い、テンプレートにウィキテキストを記入するために使用.
 * TemplateData Wizard: テンプレートデータを生成するツール. インタラクティブなインターフェースを使用.
 * Skeleton TemplateData generator: テンプレートのソースウィキコードを解読するツール. 使用するすべてのパラメータ（引数）を検出し、値が空のドキュメントとパラメータの一覧を出力.
 * JSONLint: 手入力したJSONが正しいかどうか確認するツール. 構文エラーの発見に役立つ.
 * このウィキにある[ テンプレートデータを備えたテンプレートの一覧]
 * ドイツ語版ウィキペディアのテンプレートに備わったテンプレートデータでは、ボックス内にテンプレートのデータを表示. テンプレートはそのデータとともにドイツ語版ウィキペディアの特定のカテゴリに分類される
 * https://query.wikidata.org/ およびクエリ補助機能 Query Helper