Guide to User Macro Templates

Accessing your Macro's Body

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

A user, when editing a Confluence page, chooses your macro in the Macro Browser and then enters the following in the macro placeholder that is displayed in the edit view:

From Matthew

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

Hello World: From Matthew

Using Parameters in your User Macro

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.

Defining the Parameters

Briefly, a parameter definition in the template contains:

• @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

追加情報：

• The order of the parameters in the template determines the order in which the Macro Browser displays the parameters.
• テンプレートの冒頭部分でパラメーターを定義することをお勧めします。
• 指定したパラメーターの種類に応じて、追加の属性がある場合があります。

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

Parameter Name

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

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

## @param foo
## @param bar

Parameter Type

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

## @param colour:title=Colour|type=enum|enumValues=Grey,Red,Yellow,Green

## @param status:title=Status|type=string|required=true|desc=Status to display

## @param page:title=Page|type=confluence-content|required=true|desc=Select a page do use

## @param user:title=Username|type=username|desc=Select username to display

## @param space:title=Space|type=spacekey

## @param fromDate:title=From Date|type=date|desc=Date to start from. Format: dd/mm/YYYY 

## @param numPosts:title=Number of Posts|type=int|default=15|desc=Number of posts to display

## @param pcent:title=Percentage|type=percentage|desc=Number of posts to display 

Using the Parameters in your Macro Code

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

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

Using No Parameters

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

Objects Available to your Macro

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

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

Controlling Parameter Appearance in the Editor Placeholder

A macro developer (or author of a user macro) can control which fields of the macro should appear in the placeholder in the Confluence Editor.

Plugin Macro Metadata

The macro metadata for a plugin macro now has parameter options as shown in the following example:

<macro name="panel" documentation-url="help.panel.macro">
            <category name="formatting"/>
            <parameters>
                <parameter name="title" type="string">
                    <option key="showNameInPlaceholder" value="false" />
                    <option key="showValueInPlaceholder" value="true" />
                </parameter>
                <parameter name="borderStyle" type="string"/>
                <parameter name="borderColor" type="color"/>
<snip

The option showNameInPlaceholder specifies that in the above example the 'title' parameters name should not be shown.

The option showValueInPlaceholder specifies that the user entered value for this parameter should be shown.

So, for the above example, the macro placeholder could show something like 'panel | my panel title'.
If showNameInPlaceholder was true instead of false it would show something like 'panel | title = my panel title'.

If a macro has neither option on any of it's parameters then the default behaviour is to show all parameters: full title and value. If one or more parameters has either option set then all parameters without the options set will default to false (i.e. will not be shown).

User Macro Metadata

The behaviour for a user macro is as described above, however the method of configuration is within the @param entry in the template.
So, the example from above would look something like:

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

関連トピック

Writing User Macros
Examples of User Macros