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

このページの内容

お困りですか?

アトラシアン コミュニティをご利用ください。

コミュニティに質問

ユーザー マクロの作成入門については、「ユーザー マクロの作成」を参照してください。 

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

マクロ本文へのアクセス

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

このページの内容:

関連ページ:

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

マクロが Confluence ページ上でどのような動作をするかを決定する情報をユーザーがマクロに渡せるようにするため、マクロのパラメーターを指定できます。

マクロのパラメーターを 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)

パラメーターの一意の名前。パラメーター名はリストの最初の属性です。name 属性自体には名前がありません。下記の 名前 セクション参照。

必須

タイトル

パラメーターのタイトルはマクロ ブラウザーに表示されます。タイトルを指定しない場合、Confluence はパラメーター名を使用します。

推奨

type

パラメーターのフィールド タイプ。下記の タイプ セクション参照。

推奨

desc

パラメーターの説明はマクロ ブラウザーに表示されます。

オプション

必須

ユーザーがこのパラメーターの情報を入力する必要があるかどうかを指定します。既定は false です。

オプション

複数

パラメーターに複数の値を使用できるかどうかを指定します。既定は false です。

オプション

default

パラメーターの既定値。

オプション

パラメーター名

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

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

## @param foo
## @param bar

パラメーター タイプ

The field type for the parameter. If you do not specify a type, the default is string.

パラメーター タイプ

説明

ブーリアン

ユーザーにチェックボックスを表示し、マクロに 「true」または「false」の値を文字列として渡します。

enum

選択する値の一覧を提示します。値を指定して、マクロ ブラウザのドロップダウンに表示します。列挙型の値を指定する例:

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

i18n に関する注意: Confluence は列挙値の国際化をサポートしていません。ユーザーに表示される値は、大文字表記されたパラメーター値としてマクロに渡される値です。この場合は、「Grey」、「Red」などです。

文字列

テキスト フィールド。これが既定のタイプです。必須フィールドを持つ例:

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

ユーザ名

ユーザーを検索します。

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

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

The parameters are available in your template as $paramfoo, $parambar for parameters named "foo" and "bar".

Normally, a parameter like $paramfoo that is missing will appear as '$paramfoo' in the output. To display nothing when a parameter is not set, use an exclamation mark after the dollar sign like this: $!paramfoo

パラメーター不使用

If your macro does not accept parameters, you should use @noparams in your template. 

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 if the macro does not accept parameters.

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

## @noparams

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

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

変数

説明

クラス リファレンス

$body

マクロ本文 (マクロに本文がある場合)

文字列

$paramfoo, $parambar, ... $param<name>

マクロに渡される名前付きパラメーター( "foo"、"bar")

文字列

$config

The BootstrapManager object, useful for retrieving Confluence properties.

BootstrapManager

$renderContext

The PageContext object, useful for (among other things) checking $renderContext.outputType

PageContext

$space

The Space object that this content object (page, blog post, etc) is located in (if relevant).

スペース

$content

The current ContentEntity object that this macro is a included in (if available).

ContentEntityObject

開発者向けドキュメントで説明したように、マクロは、既定のベロシティ コンテキストで利用可能なオブジェクトにアクセスすることもできます。

セキュリティに関する考慮事項

When creating a User Macro you should avoid using $content.getChildren() or $content.getDescendants() as these methods will list all pages, regardless of page restrictions or space permissions. This may lead to page viewers seeing pages that they do not have permission to see.

また、制約付きのページやスペース権限など、多数の権限シナリオでユーザー マクロを徹底的にテストすることをお勧めします。


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

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

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

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

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

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

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

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

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

The attribute showNameInPlaceholder specifies that the title parameter's name should not be shown.

The attribute showValueInPlaceholder specifies that the title parameter's value should be shown.

マクロ内のパラメーターのどれもが、上記のどの属性も含んでいない場合、既定の動作では、プレース ホルダーに適合するすべてのパラメーター、すなわち、フルタイトルと値が表示されます。

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

最終更新日: 2018 年 2 月 9 日

この内容はお役に立ちましたか?

はい
いいえ
この記事についてのフィードバックを送信する
Powered by Confluence and Scroll Viewport.