ユーザーマクロテンプレートの構文

See Writing User Macros for an introduction to writing a user macro.

このページでは、ユーザーマクロテンプレートに入力するコードに関する情報を提供します。

マクロ本文へのアクセス

マクロの本体でマクロに渡されるコンテンツにアクセスするには、ユーザーマクロテンプレート内で $body オブジェクトを使用します。

マクロに body があると指定している場合 (No macro body を選択していない場合)、$body オブジェクトを使用できます。

例: マクロ名が helloworld であるとします。
テンプレートに次のコードを入力します。

Hello World: $body

ユーザーは、Confluence ページを編集集中にマクロブラウザーでマクロを選択してから、編集ビューに表示さえたマクロプレースホルダーに以下を入力します。

From Matthew

Wiki ページには次のように表示されます。

Hello World: From Matthew

On this page:

関連ページ

ユーザーマクロを書く

ユーザーマクロでパラメーターを使用する

You can specify parameters for your macro, so that users can pass it information to determine its behaviour on a Confluence page.

マクロのパラメーターを Confluence ページ上で使用する方法

Confluence ページにマクロを追加すると、マクロブラウザが各マクロパラメーターの入力フィールドを表示します。フィールドタイプは、指定したパラメーターの種類によって決まります。

パラメーターを定義する

テンプレートのパラメーター定義には、次の項目が含まれます。

@param
パラメーター名
属性の数（オプション）。

形式:

## @param MYNAME:title=MY TITLE|type=MY TYPE|desc=MY DESCRIPTION|required=true|multiple=true|default=MY DEFAULT VALUE

追加情報：

テンプレート内のパラメーターの順序によって、マクロブラウザがパラメーターを表示する順序が決まります。
テンプレートの冒頭部分でパラメーターを定義することをお勧めします。
指定したパラメーターの種類に応じて、追加の属性がある場合があります。

以下のセクションでは、それぞれの属性の詳細を示します。

属性名	説明	必須/推奨/オプション
(an unnamed, first attribute)	A unique name for the parameter. The parameter name is the first attribute in the list. The name attribute itself does not have a name. See the section on name below.	必須
title	パラメーターのタイトルはマクロブラウザーに表示されます。タイトルを指定しない場合、Confluence はパラメーター名を使用します。	推奨
type	The field type for the parameter. See the section on type below.	推奨
desc	パラメーターの説明はマクロブラウザーに表示されます。	任意
必須	ユーザーがこのパラメーターの情報を入力する必要があるかどうかを指定します。既定は false です。	任意
複数	パラメーターに複数の値を使用できるかどうかを指定します。既定は false です。	任意
default	パラメーターの既定値。	任意

パラメーター名

パラメーター名はリストの最初の属性です。name 属性自体には名前がありません。

例：次のコードは、「foo」と「bar」という名前の 2 つのパラメーターを定義します。

## @param foo
## @param bar

パラメータータイプ

パラメーターのフィールドタイプ。タイプを指定しない場合、既定値は string になります。

パラメータータイプ	説明
ブーリアン	ユーザーにチェックボックスを表示し、マクロに「true」または「false」の値を文字列として渡します。
enum	選択する値の一覧を提示します。値を指定して、マクロブラウザのドロップダウンに表示します。列挙型の値を指定する例： ## @param colour:title=Colour\|type=enum\|enumValues=Grey,Red,Yellow,Green Note about i18n: Confluence does not support internationalisation of the enum values.The value the user sees is the one passed to the macro as the parameter value, with the capitalisation given. In this case 'Grey', 'Red', etc.
文字列	テキストフィールド。これが既定のタイプです。必須フィールドを持つ例： ## @param status:title=Status\|type=string\|required=true\|desc=Status to display
confluence-content	ユーザーに対してページやブログ投稿の検索を許可するコントロールを提供します。例: ## @param page:title=Page\|type=confluence-content\|required=true\|desc=Select a page do use
username	ユーザーを検索します。 ## @param user:title=Username\|type=username\|desc=Select username to display
spacekey	スペースを選択する一覧を提示します。マクロにスペースキーを渡します。例： ## @param space:title=Space\|type=spacekey
日付	Confluence はこのタイプを受け入れますが、「文字列」と同じように扱います。例: ## @param fromDate:title=From Date\|type=date\|desc=Date to start from. Format: dd/mm/YYYY 日付に関する注意事項: ユーザーは任意の形式で日付を入力することができます、管理者は、ユーザーマクロの日付形式を検証する必要があります。
int	Confluence はこのタイプを受け入れますが、「文字列」と同じように扱います。既定値を持つ例： ## @param numPosts:title=Number of Posts\|type=int\|default=15\|desc=Number of posts to display
パーセンテージ	Confluence はこのタイプを受け入れますが、「文字列」と同じように扱います。例： ## @param pcent:title=Percentage\|type=percentage\|desc=Number of posts to display

マクロコードでパラメーターを使用する

パラメーターは、テンプレートでは $paramfoo、$parambar ("foo" および "bar" という名前のパラメーターの場合) などの形式で使用できます。

通常、不足している $paramfoo などのパラメーターは、出力で '$paramfoo' などと表示されます。パラメーターが設定されていない場合に何も表示しないようにするには、ドル記号 ($) の後に感嘆符 (!) を付けて「$!paramfoo」のようにします。

パラメーター不使用

マクロがパラメーターを許可しない場合、テンプレートで @noparams を使用する必要があります。

ユーザーマクロにパラメーターが含まれておらず、@noparams を指定していない場合、マクロブラウザに自由形式のテキストボックスが表示されます。ユーザーはそこで未定義のパラメーターを入力できます。マクロがパラメーターを許可しない場合、このことが混乱を招く場合があります。

例：テンプレートの冒頭部分に次の行を追加します。

## @noparams

マクロで使用可能なオブジェクト

次の Confluence オブジェクトをマクロで使用できます (マクロ本文とパラメーターを含む)。

変数	説明	クラスリファレンス
`$body`	マクロ本文 (マクロに本文がある場合)	文字列
`$paramfoo`、`$parambar`、... `$param<name>`	マクロに渡される名前付きパラメーター（ "foo"、"bar"）	文字列
`$config`	Confluence プロパティを取得するのに便利な `BootstrapManager` オブジェクト。	BootstrapManager
`$renderContext`	特に `$renderContext.outputType` のチェックに有用である `PageContext` オブジェクト	PageContext
`$space`	このコンテンツオブジェクト (ページ、ブログ投稿など) が格納されている `Space` オブジェクト (関連する場合)。	スペース
`$content`	このマクロが含まれている現在の `ContentEntity` オブジェクト (存在する場合)。	ContentEntityObject

Macros can also access objects available in the default Velocity context, as described in the developer documentation.

エディターのプレースホルダーに表示するパラメーターの制御

Confluence エディターのプレースホルダーに、どのマクロパラメーターを表示するかを決定できます。

既定では、次のように、収まるだけのパラメーターをプレースホルダーに表示することができます。

最も関連性の高い情報が作者に表示されるよう、ここに表示するパラメーターを制御できます。

たとえば、Confluence 警告マクロには、タイトルとアイコンの 2 つのパラメーターがあります。最も関心の高いパラメーターはタイトル パラメーターである見なし、タイトル パラメーターの値のみを表示するよう警告マクロを設定しました。

作者がページに警告マクロを追加して、「The title of the warning」というタイトルを付けたとします。マクロ構成を行うと、プレースホルダーは次のようになります。

ユーザーマクロのマクロプレースホルダーを設定するには、テンプレートの @param エントリに属性を追加します。

たとえば、警告マクロがユーザーマクロである場合、タイトル パラメーターの設定は次のようになります。

## @param title:type=string|option-showNameInPlaceholder=false|option-showValueInPlaceholder=true

属性 showNameInPlaceholder は、title パラメーターの name を表示しないことを示します。

showValueInPlaceholder 属性は、title パラメーターの value を表示しないことを示します。

If none of the parameters in a macro include any of the above attributes, then the default behaviour is to show all the parameters that fit in the placeholder: full title and value.

1 つ以上のパラメーターに属性セットがある場合、属性を含まないすべてのパラメーターは既定で "false" に設定されますされます (つまり、それらは表示されません)。

ページツリー

ユーザー マクロ テンプレートの構文