Jump to content

Extension:TemplateData

課題管理システム: #TemplateData
From mediawiki.org
This page is a translated version of the page Extension:TemplateData and the translation is 98% complete.
Outdated translations are marked like this.
Languages:
MediaWiki 拡張機能マニュアル
TemplateData
リリースの状態: 安定
実装 タグ , API
説明 テンプレートに関する情報の保存と取得、視覚化が可能
作者 Timo Tijhof, Moriel Schottlender, James Forrester, Trevor Parscal, Bartosz Dziewoński, Marielle Volz, ...
最新バージョン 0.2.0 (継続的な更新)
互換性の方針 MediaWiki とともにリリースされるスナップショット。 master には後方互換性がありません。
PHP 5.4+
データベースの変更 いいえ
ライセンス GNU 一般公衆利用許諾書 2.0 以降
ダウンロード
拡張機能をダウンロード
Git [?]:
パラメーター
  • $wgTemplateDataMaxFavorites
  • $wgTemplateDataEnableFeaturedTemplates
  • $wgTemplateDataEnableDiscovery
  • $wgTemplateDataEnableCategoryBrowser
  • $wgTemplateDataCategoryBrowserItem
  • $wgTemplateDataEditorNamespaces
  • $wgTemplateDataUseGUI
タグ
‎<templatedata>
使用するフック
translatewiki.net で翻訳を利用できる場合は、TemplateData 拡張機能の翻訳にご協力ください
問題点 未解決のタスク · バグを報告

TemplateData拡張機能は、エディターがテンプレートとそのパラメータの使用方法を指定できるように ‎<templatedata>タグとAPIを導入します。 この情報は、エンドユーザー向けに書式化した表として、また、VisualEditor を始めとする他のシステムがテンプレートを扱うためのインターフェースを構築できるようにするJSON APIとして利用可能です。 詳細はHelp:TemplateData をご参照ください。

インストール

この拡張機能は MediaWiki 1.35 以降に同梱されているため、ダウンロードする必要はありません。 残りの設定手順は必ず従ってください。
  • ダウンロードして、ファイルをextensions/フォルダー内のTemplateDataという名前のディレクトリ内に配置します。
    開発者とコード寄稿者は、上記の代わりに以下を使用してGitからインストールします:
    cd extensions/
git clone https://gerrit.wikimedia.org/r/mediawiki/extensions/TemplateData
  • 以下のコードを LocalSettings.php ファイルの末尾に追加します: 
    wfLoadExtension( 'TemplateData' );
  • Yes 完了 – ウィキの「Special:Version」に移動して、拡張機能が正しくインストールされたことを確認します。

データの編集

TemplateData拡張機能は、テンプレートページのウィキテキスト内に ‎<templatedata>タグが定義されていることによって機能します（なお、任意で別のページから参照読み込みも可能です）。 これは多くのウィキにおいて一般的な、別のページからテンプレートの説明文書を参照読み込みするレイアウト（必須ではありません）と互換性があるように設計されています。 ‎<templatedata> タグのこのコンテンツは以下で説明する形式を使用する有効なJSON形式でなければなりません。すべての記述はプレーンテキストでなければなりません（テンプレートデータの中でウィキテキストは使えません）。

‎<templatedata> ブロックがページに含まれるときは、TemplateData 拡張機能がぺージの保存時に次の各点を確認します。

  1. コンテンツは有効な JSON であること、
  2. その JSON 構造内の各項目は、以下に指定されているような期待される型（例：オブジェクト、配列、またはプリミティブ）であること、そして
  3. これらの項目が取りうる値の指定されたリストがあり (例 パラメーターの type)、JSON オブジェクト内の値はそのひとつに合致すること。

いずれかの確認が失敗した場合、サーバはページの保存を承認せず、編集ページの上部にエラーメッセージを表示します。

autovalue項目では、T4700によって ‎<ref> および ‎<gallery> を含むタグ内に追加されたあらゆるテンプレートの subst: 機能は阻止されます。 TemplateData ブロックは正しく保存されますが、結果として得られるウィキテキストはテンプレートを使用したときに正しく処理されません。

テンプレートデータエディターを使うことができなくなるので、 {{#tag:templatedata}} を使うことは避けてください。

書式

下記はテンプレートページ上で ‎<templatedata>‎</templatedata> タグで囲んで定義されるJSONデータを可視化したものです。 正式な仕様は TemplateData リポジトリで入手可能です。 最新版は Specification.md をご参照ください。

TemplateData オブジェクト

TemplateData オブジェクトは、テンプレートページ上の ‎<templatedata> 要素に囲まれた JSON ルート要素です。

キー 型 説明
description InterfaceText または null テンプレートの簡潔な説明。 プレーンテキストにしなければなりません。 記入すると、単一のテンプレートを編集するとき、そしておそらく利用者が検索結果で多くからひとつを選ぶときにも、キャプションとして表示できます。 既定値は null です。

→ For more details see: description

params Param オブジェクトを含むオブジェクト このオブジェクトは、テンプレート上のパラメータ名とそのプロパティを解説する Param object とをマッピング。

→ For more details see: params

paramOrder パラメーター名の文字列を含む配列 パラメーターを表示すべき論理的な順序。 配列は各パラメーターのキーを厳密に1回含みます。 各文字列は params オブジェクト内の有効なキーでなければなりません。

→ For more details see: paramOrder

sets Set オブジェクトを含む配列 セット仕様を含む配列。 セットは一緒に使うべきパラメーターのグループです。 既定値は [] です。 sets 機能はまだ開発中であることに注意してください。
format 文字列、inlineまたはblockのいずれか テンプレートのウィキテキスト表現がどのようにレイアウトされるべきか。 既定値は inline です。 その他のカスタム書式については#カスタム書式を参照してください。
maps Maps オブジェクトを含むオブジェクト このオブジェクトは、テンプレート データのサード パーティ コンシューマーの簡略名 (例: Citoid、Special:MyLanguage/Wikidata など) を、別のマップ オブジェクトに対応付けます。そのマップ オブジェクトは、コンシューマー側のパラメーター名と、対応するテンプレートのパラメーター名 (1つ以上) とを対応付けます。

Param オブジェクト

キー 型 既定 説明
label InterfaceText null （非常に）簡潔なパラメーターの名前。 20文字以下くらいにしてください。

→ For more details see: label

description InterfaceText null 利用者がオプションリストからどれを選べばいいのか知るための、パラメーターの簡潔な説明。

→ For more details see: description

required 真偽値 false パラメーターがテンプレートを機能させるために必須かどうか（このパラメーターを指定しなければならないならば true）。

→ For more details see: required

suggested 真偽値 false パラメーターがテンプレートを有用にするために推奨されるかどうか（このパラメーターを指定すべきならば true）。

→ For more details see: suggested

deprecated 真偽値または文字列 false パラメーターが非推奨かどうか。 値は利用者が代わりにできることを案内する文字列にすることも、単に true にすることもできます。

→ For more details see: deprecated

aliases 文字列を含む配列 [] 別名のリスト。 別名はパラメーターに対して、一番目の名前の代わりに（追加ではなく）使うことができる代替名です。 別名は独立したパラメーターオブジェクトで文書化されません。 さらなる情報を必要とするならば、"deprecated"とマークされた独自のプロパティ内にあるべきです。

→ For more details see: aliases

default InterfaceText null パラメーターに値が割り当てられていない場合にテンプレートによって使用される既定値、またはそれについての説明。

→ For more details see: default

autovalue 文字列 null 今日の日付や編集している利用者の名前といった、ウィキテキストで動的に生成される既定値。これはしばしば {{subst:CURRENTYEAR}} のように、ウィキテキストの置換を伴います。

→ For more details see: autovalue

example InterfaceText null 利用者が適正な値を記入するのを助ける、パラメーターに対する例示テキスト。

→ For more details see: example

type 文字列 "unknown" （ソフトな）型ヒントのための、パラメーターの型。以下のひとつ：
文字列値 パラメーターの型
"unknown" 設定なしの場合に仮定される型

→ For more details see: value ‘unknown’

"number" 任意の数字（小数点や3桁ごとの区切りなし）

→ For more details see: value ‘number’

"string" 任意のテキストの値。改行を含んでもよい。

→ For more details see: value ‘string’

"line" 短いテキスト欄 – 名前、ラベル、その他短文の欄に対して使用。 これは改行を含むことが期待されないテキストが想定されます。

→ For more details see: value ‘line’

"boolean" 真偽値（true に対して '1'、false に対して'0'、unknown に対して ''）、3値論理参照。

→ For more details see: value ‘boolean’

"date" ISO 8601 形式の日付、例えば "2014-05-09" や "2014-05-09T16:01:12Z"

→ For more details see: value ‘date’

"url" URL、プロトコルを含める、例えば "http://www.example.org", "https://example.org", や "//example.org"。

→ For more details see: value ‘url’

"wiki-page-name" 現在のウィキに対して有効な MediaWiki ページ名。 存在する必要はないですが、存在しないならば、作成できる有効なページ名であるべきです。

→ For more details see: value ‘wiki-page-name’

"wiki-file-name" 現在のウィキに対して有効な MediaWiki ファイル名。 存在する必要はないですが、存在しないならば、アップロードできる有効なファイル名であるべきです。 名前空間は含めるべきではありません（例えば "File:Foo.svg" や "画像:Foo.svg" ではなく "Foo.svg"）。

→ For more details see: value ‘wiki-file-name’

"wiki-template-name" 現在のウィキに対して有効な MediaWiki テンプレート名。

→ For more details see: value ‘wiki-template-name’

"wiki-user-name" 現在のウィキに対して有効な MediaWiki 利用者名。 存在する必要はないですが、存在しないならば、作成できる有効な利用者名であるべきです。 名前空間を含めるべきではありません（例えば "User:Foo" や "利用者:Foo" ではなく "Foo"）。

→ For more details see: value ‘wiki-user-name’

"content" テキストスタイル、リンク、画像、などといった、ウィキテキストのページコンテンツ。

→ For more details see: value ‘content’

"unbalanced-wikitext" 不均衡なので単独のコンテンツとして扱うべきではない生のウィキテキスト – 例えば、 {{echo|before=<u>|after=</u>}} のように不完全なウィキテキストをより大きな全体として結合するテンプレート。

→ For more details see: value ‘unbalanced-wikitext’

→ For more details see: type

inherits 文字列 なし
代用 		他のパラメーターの名前キー（params オブジェクト内の有効なキーでなければならない）。 現在のパラメーター オブジェクトは指定されたパラメーター オブジェクトからプロパティを継承し、ローカルなプロパティが継承されたプロパティをオーバーライドします。

→ For more details see: inherits

suggestedvalues 文字列を含む配列 [] オプションのパラメータープロパティ。 利用者が希望する値を選択するのを手助けするパラメーター値のリストを作成します。 推奨値をビジュアルエディターでコンボボックスとして表示するには、パラメーターの型が以下のひとつに設定されていなければなりません：content、 line、 string、 number、 unknown または unbalanced wikitext。

→ For more details see: suggestedvalues

Set オブジェクト

キー

オブジェクトまたはプリミティブ型

説明

label InterfaceText （非常に）簡潔なパラメーターセットに対する名前。 20文字以下くらいにしてください。
params 文字列の配列 セットに含めるひとつ以上のパラメーターの名前（それぞれが params オブジェクト内の有効なキーでなければならない）。 あるパラメーターが複数のセット内にあってもかまいません。 すべてのパラメーターがセット内にある必要はありません。

Maps 構造

Maps is a single data structure that goes multiple levels deep. It became common to call the second level a “map object”.

キー 型 既定 説明
name of consumer オブジェクト {} オブジェクトはname of a consumer（コンシューマの名前）をオブジェクトにマップし、次に特定のname of a consumer parameter （コンシューマ パラメータの名前）を対応する1つ以上のnames of template parameters （テンプレート パラメータの名前群）にマップします。

テンプレートのパラメータ名 の定義は文字列（単一の名称）、複数の文字列（複数の名称） あるいはその組み合わせ（名称群の複数のセット）のいずれかで成立します。同一のテンプレートの TemplateData では、これらの文字列はどれも params オブジェクトに規定した有効なキーにする必要があります。

特定のテンプレート・パラメータは複数のマッピング上に存在可能であり、指定されたマップ内の複数のキーの値で使用できる代わり、特定のマップ内にテンプレート・パラメータ全件が存在することは 必然 ではありません。

maps オブジェクトの構造を説明する英語版ウィキペディアの Template:Cite_news#TemplateData から短縮された例です。 

{
	"proveit": {
		"main": "title",
		"textarea": [
			"quote"
		]
	},
	"citoid": {
		"title": "title",
		"url": "url",
		"publisher": "publisher",
		"publicationTitle": "work",
		"date": "date",
		"ISSN": [
			"issn"
		],
		"ISBN": [
			"isbn"
		],
		"contributor": "others",
		"author": [
			[
				"first",
				"last"
			],
			[
				"first2",
				"last2"
			],
			[
				"first9",
				"last9"
			]
		],
		"editor": [
			[
				"editor-first",
				"editor-last"
			]
		]
	}
}

InterfaceText (文字列またはオブジェクト)

そのウィキのコンテンツ言語で自由形式のプレーンテキスト（つまりウィキテストやHTMLではない）、あるいは言語コードをキーとしてそれらの文字列を含むオブジェクト。

すべての InterfaceText フィールドに対して既定値は null です。

文字列型

文字列であるならば、それはローカルウィキのコンテンツ言語で地域化されていない文字列を含まなければなりません。

オブジェクト型

オブジェクトであるならば、そのオブジェクトはこのマッピングを持たなければなりません：

キー 型 説明
ウィキペディア言語コード 文字列 そのインターフェース言語の利用者のための地域化された文字列。

オブジェクトマッピングの例：

キー 値
"en" "Welcome to Wikipedia"
"de" "Willkommen bei Wikipedia"
"fr" "Bienvenue sur Wikipédia"
"nl" "Welkom op Wikipedia"
"it" "Benvenuti su Wikipedia"
"es" "Bienvenidos a Wikipedia"
"ru" "Добро пожаловать в Википедию"

例

テンプレートページ上のウィキテキスト内で指定された TemplateData 構造の例です。 

<templatedata>
{
    "description": "Label unsigned comments in a conversation.",
    "params": {
        "user": {
            "label": "User's name",
            "type": "wiki-user-name",
            "required": true,
            "description": "User name of person who forgot to sign their comment.",
            "aliases": ["1"]
        },
        "date": {
            "label": "Date",
            "suggested": true,
            "description": {
                "en": "Timestamp of when the comment was posted, in YYYY-MM-DD format."
            },
            "aliases": ["2"],
            "autovalue": "{{subst:#time:Y-m-d}}"
        },
        "year": {
            "label": "Year",
            "type": "number"
        },
        "month": {
            "label": "Month",
            "inherits": "year"
        },
        "day": {
            "label": "Day",
            "inherits": "year"
        },
        "comment": {
            "required": false
        }
    },
    "sets": [
        {
            "label": "Date",
            "params": ["year", "month", "day"]
        }
    ],
    "maps": {
        "ExampleConsumer": {
            "foo": "user",
            "bar": ["year", "month", "day"],
            "quux": [
                "date",
                ["day", "month"],
                ["month", "year"],
                "year"
            ]
        }
    }
}
</templatedata>

以下は上記の例がテンプレートページ上でどのように表示されるかを示したものです：

Label unsigned comments in a conversation.

Template parameters[Edit template data]

ParameterDescriptionTypeStatus
User's nameuser 1

User name of person who forgot to sign their comment.

Userrequired
Datedate 2

Timestamp of when the comment was posted, in YYYY-MM-DD format.

Auto value
{{subst:#time:Y-m-d}}
Unknownsuggested
Yearyear

no description

Numberoptional
Monthmonth

no description

Numberoptional
Dayday

no description

Numberoptional
commentcomment

no description

Unknownoptional

API

Special:ApiHelp/templatedata にある生成されたヘルプを参照してください。 呼び出し例（人間に読みやすく整形済み）は：

api.php?action=templatedata&titles=Template:Cite%20web&format=json [ApiSandbox で試用する]

これはTemplate:Cite webに対するテンプレートデータを返します。 このテンプレートに対する ‎<templatedata>...‎</templatedata> ブロックは参照読み込みされたテンプレート文書ページ、en:Template:Cite web/docにあります。

API から取得された JSON への追加と変更

API HTTP get リクエストへのレスポンスで提供される JSON 構造は ‎<templatedata>...‎</templatedata> ブロックで定義されるものとは顕著に異なります。 API リクエストへのレスポンスで、拡張機能 TemplateData は JSON オブジェクトに以下の変更を行います：

API がもたらす TemplateData JSON オブジェクトの違いを可視化

API によって配信される JSON に追加されるラッパーオブジェクト
これらはテンプレートページ上の ‎<templatedata> タグで囲まれた JSON オブジェクトでは定義されません。
JSON ルート
キー 型 説明
pages Page オブジェクト Page オブジェクト（ページ番号をひとつのキーとして含む）。 一度に複数のページをリクエストした場合、複数の Page オブジェクトがあることになります。

Page オブジェクト
キー 型 説明
(ページ番号) TemplateData オブジェクト TemplateData オブジェクトは情報ペイロードを含みます。 キーは JSON データをリクエストされたテンプレートページに対する静的なページ番号です。
TemplateData オブジェクト（APIによって追加される）
以下のキーがテンプレートページ上の ‎<templatedata> タグで囲まれた JSON オブジェクトのルートに追加されます。
キー 型 説明
title 文字列 テンプレートのページ名（例えば "Template:Cite web"）。
このキーはテンプレートページ上の JSON 構造に含まれません。 その構造に追加するには MediaWiki ソフトウェアが API 経由で送り付ける。
sets Set オブジェクトを含む配列 セット仕様を含む配列。 セットは一緒に使うべきパラメーターのグループです。
これがテンプレートページ上に存在しない場合、空の配列として API によって提供される構造に追加されます。
API からのパラメーター オブジェクト
キー 型 説明
label InterfaceText 既にその形式になっているのでない場合、 InterfaceText オブジェクトに変換される。
required 真偽値 定義されていない場合、 false の既定値が追加されます。
description InterfaceText または null 文字列として定義された場合、 InterfaceText オブジェクトに変換されます。 定義されていない場合、 null 値を持つキーが追加されます。
deprecated 真偽値または文字列 定義されていない場合、 false の既定値が追加されます。
aliases 文字列の配列 定義されていない場合、既定の空の配列（つまり [] ）が割り当てられます。
default 文字列 定義されていない場合、既定の "" が割り当てられます。
type 文字列 定義されていない場合、既定の "unknown" が割り当てられます。
inherits (除去済) このキーは除去され、すべての継承されたキーが追加されます。 現在のパラメーターに対して定義されたキーが優先され、現在のパラメーターまたは継承元のひとつで定義されていないキーは既定値を与えられます。
InterfaceText (オブジェクトまたは null):
言語コードをキーとして文字列を含むオブジェクト。
キー オブジェクトまたは
プリミティブ型		 説明
オブジェクト
（ウィキペディア言語コードによって地域化された文字列を含む）
テンプレートページ上の TemplateData フィールドが地域化された文字列を持つオブジェクトではなく、文字列を含む場合、 MediaWiki はソース Wikipedia のウィキペディア言語コードのキー名に割り当てられた文字列を持つ InterfaceText オブジェクトに変換します。 すべての InterfaceText フィールドに対する既定は null です。
（ウィキ言語コード） 文字列 そのインターフェース言語の利用者のための地域化された文字列。

API によって提供される JSON オブジェクトの例

例の節（上述）にある TemplateData 構造に対する API リクエストへのレスポンスを見ることができます：

設定

変数 既定 説明
$wgTemplateDataUseGUI true templatedata JSON の編集に使う実験的なダイアログインターフェース
$wgTemplateDataEditorNamespaces [ 10 ] The namespaces in which the template data editor appears when creating or editing a page. (T189989)
$wgTemplateDataMaxFavorites 50 The maximum number of favorite templates that can be stored. (T377460)


関連項目

Retrieved from "https://www.mediawiki.org/w/index.php?title=Extension:TemplateData/ja&oldid=7910893"