テンプレート:Ambox/doc

Ambox, Article Message Box（記事用メッセージボックス）は、{{wikify}} 等の、記事に使用するお知らせ用のテンプレートを作成するためのテンプレート（メタテンプレート）です。

元々は記事に使用するために作られたものですが、現在ではTemplate、Categoryなど、記事以外の、ノートページでない名前空間にも使用されています。

Ambox にはその用途に応じた6種類の色が用意されています。画像の指定は任意ですが、画像関連のパラメータが指定されない場合は各色ごとに規定の画像が表示されます。

このメタテンプレートは、MediaWiki:Common.css に記述された ambox 用の CSS クラスが適用された状態の雛形を提供するものです。これらの CSS クラスはこのテンプレートに限らず、パイプ構文で書かれた表内で直接使うこともできます。使用方法は w:en:Wikipedia:Ambox CSS classes を参照してください。

使い方

単純な例：

{{ambox | text = ほげほげ}}

複雑な例：

{{ambox
| type  = style
| image-file = Icon apps query.svg
| imageright-file = Icon apps query.svg
| image-size = 35
| text  = メッセージボックスの本文
}}

パラメータ

パラメータの一覧
パラメータ	指定する内容	既定値	説明
type	protection / speedy / serious / content / style / merge / notice	notice	色と既定アイコンの選択。#type パラメータと色の対応
image	画像表示の記述。例: [[画像:Some image.svg\|40px]] / none / blank		Wiki構文による画像指定。#画像指定方法の詳細
imageright	画像表示の記述。例: [[画像:Some image.svg\|40px]]		Wiki構文による右側への画像指定。#画像指定方法の詳細
image-file	画像ファイル名。例: Some image.svg		#画像の指定
image-size	ピクセル数を数値で	40	ノーマルタイプの画像サイズ。#画像指定方法の詳細
image-size-section	ピクセル数を数値で	25	節タイプの場合の画像サイズ。#画像指定方法の詳細
imageright-file	画像ファイル名。例: Some image.svg		右側に表示する画像のファイル名。#画像指定方法の詳細
imageright-size	ピクセル数を数値で	(image-size)	ノーマルタイプの右側画像サイズ。#画像指定方法の詳細
imageright-size-section	ピクセル数を数値で	(image-size-section)	節タイプの場合の右側画像サイズ。#画像指定方法の詳細
section	空白以外。1 など		節タイプへのスタイル切り替え。#section パラメータ: 節タイプとの切り替え
printable	空白以外。1 など		印刷時も表示する。#その他の設定
style	CSS の記述		CSS による外観の細かい設定。* 廃止予定 *
background	#rrggbb / #rgb / 色の名前 / transparent		背景色の設定。#その他の設定
text	任意の文章	（省略不可）	メッセージ本文。
text-section	任意の文章	(text)	節タイプの場合に表示するメッセージ本文。#section パラメータ: 節タイプとの切り替え

type パラメータと色の対応

type パラメータには以下の6種のいずれかの値を指定します。テンプレート左側の色は値により変化するので、用途によって使い分けてください。表示されている画像は、画像関連のパラメータを指定しない場合の、それぞれの値に既定のアイコン画像です。

このメッセージボックスは無効な "type=serious" パラメータを使用しており、修正が必要です。

このメッセージボックスは無効な "type=merge" パラメータを使用しており、修正が必要です。

section パラメータ: 節タイプとの切り替え

section パラメータに空白以外を指定すると、テンプレートの外観がコンパクトな、節の冒頭で使うためのもの（節タイプ）に変化します。

ひとつのテンプレートに、記事冒頭で使うタイプ（ノーマルタイプ）と節タイプの両方の機能を持たせることもできます。テンプレートが section パラメータを受け取れるようにし、そのまま ambox の section パラメータに渡すだけです。

{{ambox
| section = {{{section|}}}
| text = テンプレート本文
}}

ノーマルタイプと節タイプで文章を切り替えるには、text-section パラメータを指定します。

{{ambox
| section = {{{section|}}}
| text = ノーマルタイプの本文
| text-section = 節タイプの本文
}}

画像の指定

上記の既定アイコンは簡便のために用意されていますが、多くの場合はより目的に合う画像を選んだ方が適切です。以下の例では image-file パラメータを指定し、既定アイコン以外の特定の画像を表示しています。

このメッセージボックスは無効な "type=merge" パラメータを使用しており、修正が必要です。

画像指定方法の詳細

画像の指定には、image-file パラメータを使用する方法と、image パラメータを使用する方法があります。

image-file: 画像のファイル名を指定します。画像サイズは image-size パラメータと image-size-section パラメータでピクセル数を指定し、節タイプの場合は自動的に -section の指定値が反映されます。既定値はそれぞれ、40 と 25 です。image と image-file が同時に指定された場合、基本的に image-file が優先されます。
image: [[画像:Unbalanced scales.svg|40px]] のように、普段画像を表示するのと同じ方法で指定します。画像サイズも含めて指定するので、節タイプでサイズを切り替えることはできません。

{{ambox
| image-file = Icon apps query.svg
| image-size = 50
| image-size-section = 15
| text = ノーマルタイプ
| text-section = 節タイプ
| section = {{{section|}}}
}}

{{ambox
| image = [[画像:Icon apps query.svg|50px]]
| text = ノーマルタイプ
| text-section = サイズが個別に指定できず、節タイプはレイアウトが崩れる
| section = {{{section|}}}
}}

image パラメータに特定のキーワードを指定することで、画像を非表示にできます。

image = none: 画像を非表示にし、ボックス内をすべてテキスト用の領域とします。このキーワードのみ、image-file パラメータの指定よりも優先されます。
image = blank: 画像を非表示にしますが、本来の表示領域をそのまま空白として残します。複数の ambox を並べたときに、テキストの左揃えの位置を一致させることができます。

画像を右側にも表示させられます。

imageright-file, imageright-size, imageright-size-section: image-file パラメータと同様の使い方です。節タイプで画像サイズが自動で変わるのも同様で、サイズは省略した場合 image-size と image-size-section の値がそれぞれ既定値となります（これらも省略していた場合は 40 と 25）。
imageright: image パラメータと同様の使い方ですが、キーワード指定はありません。

その他の設定

background パラメータを指定すると、ambox の背景色を変更できます。テンプレート間の外観の統一に支障をきたすため、強い警告以外での使用は推奨されていません。#rrggbb 形式や色名での指定など、CSS で色として指定できる文字列を設定します。

printable パラメータに空白以外を指定すると、印刷時にもテンプレートが表示されるようになります。通常、お知らせ用のテンプレートは印刷時には必要ないものですが、法的・医学的な注意など印刷される必要のあるものも中には存在するので、そのような場合はこのパラメータを指定してください。

style パラメータには、CSS を自由に記述可能です。このパラメータはテンプレート間の外観の統一に支障をきたすため、廃止が予定されています。

技術情報

特殊な文字を text パラメータで使う場合は注意が必要です。中括弧 ( { } ) やパイプ ( | ) を使用する際は、<nowiki></nowiki> で囲むか、文字参照 ( { } -> { }, | -> |) を使うか、もしくは特定のテンプレートを使って ( | -> {{!}}) 、テンプレートの一部と見なされないようにする必要があります。中括弧は単独であれば（2つ以上連続したり、パイプと組み合わさったりしなければ）特に影響はありません。
このテンプレートの外観の大部分は CSS クラスで指定されているので、このテンプレートを使っているテンプレートは type パラメータの指定を変更するだけで枠線の色などを一括変更することが可能です。
テンプレート内部では、パイプ文法ではなく <table> タグ等を使用した XHTML マークアップを使っています。条件文中でパラメータ区切りのパイプと干渉するなど、パイプ文法にはいくつかの欠点があるので、メタテンプレートの作成には XHTML マークアップを使うのが通例です。

この他の技術的詳細はノートページや関連項目以下にあるリンク先を参照してください。