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

ユーザーマクロを書く

このページの内容

関連コンテンツ

  • 関連コンテンツがありません

お困りですか?

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

コミュニティに質問

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

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

マクロ本文へのアクセス

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

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

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

Hello World: $body

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

From Matthew

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

Hello World: From Matthew

On this page:

関連ページ

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

マクロが 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 属性自体には名前がありません。下記の 名前 セクション参照。

必須

title

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

推奨

type

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

推奨

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

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

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

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

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

ユーザー マクロを作成する際は、$content.getChildren() または $content.getDescendants() の使用は避けてください。これらのメソッドはページの制限やスペースの権限に関係なく、すべてのページを一覧表示するため、ユーザーが表示権限を持っていないページが表示されてしまう場合があります。

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

変数を使用した HTML レンダリング

変数を割り当てて HTML をレンダリングする場合は、変数名の最後に「Html」を付ける必要があります。こうすると、エスケープされる代わりに、HTML がレンダリングされます。

例: $outputHtml  $output の代替

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

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 を表示しないことを示します。

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

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

最終更新日: 2021 年 2 月 26 日

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

はい
いいえ
この記事についてのフィードバックを送信する

関連コンテンツ

  • 関連コンテンツがありません
Powered by Confluence and Scroll Viewport.