Guide to User Macro Templates

You can create a user macro in Confluence by typing it into a screen in the Confluence Administration Console. The 'template' is one of the fields that you define when writing a user macro. (See the rest of the guide to writing user macros.) This page gives you guidelines about the code you can enter in a user macro template.

Quick guide to user macro templates:

Use HTML and Confluence-specific XML elements in the macro template. Details of Confluence's storage format are in Confluence Storage Format.
You can use the Velocity templating language. Here is more information on the Velocity project.
マクロに本文がある場合、"$body" を指定することでテンプレートでマクロの本文のテキストを参照できます。
Each parameter variable you use must have a matching metadata definition. Use @param to define metadata for your macro parameters.
When using the information passed using parameters, refer to your parameters as $paramXXX where 'XXX' is the parameter name that you specifed in the @param metadata definition.
Use @noparams if your macro does not accept parameters.

On this page:

関連ページ

The information on this page does not apply to Confluence OnDemand.

マクロ本文へのアクセス

Use the $body object within your user macro template to access the content passed to your macro in the macro body.

The $body object is available if you have specified that your macro has a body (in other words, if you have not selected No macro body).

Example: Let's assume your macro is called helloworld.
Enter the following code in your template:

Hello World: $body

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

From Matthew

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

Hello World: From Matthew

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

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

How your macro's parameters are used on a Confluence page

When adding a macro to a Confluence page, the macro browser will display an input field for each of your macro's parameters. The field type is determined by the parameter type you specify for each parameter.

パラメーターを定義する

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

@param
パラメーター名
A number of attributes (optional)

形式:

## @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	パラメーターの説明はマクロブラウザーに表示されます。	任意
必須	Specifies whether the user must enter information for this parameter. Defaults to 'false'.	任意
複数	Specifies whether the parameter accepts multiple values. Defaults to '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 accepts this type, but currently treats it in the same way as 'string'. Example with a default value: ## @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」のようにします。

パラメーター不使用

If your macro does not accept parameters, you should use @noparams in your template. That will let Confluence know that it need not display a parameter input field in the macro browser.

If the user macro contains no parameters and does not specify @noparams, then the macro browser will display a free-format text box allowing users to enter undefined parameters. This can be confusing, especially if the macro does not accept parameters.

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

## @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" に設定されますされます (つまり、それらは表示されません)。

ページツリー