ユーザー マクロ テンプレートの構文
ユーザー マクロの作成入門については、「ユーザー マクロの作成」を参照してください。
このページでは、ユーザーマクロ テンプレートに入力するコードに関する情報を提供します。
マクロ本文へのアクセス
マクロの本体でマクロに渡されるコンテンツにアクセスするには、ユーザー マクロ テンプレート内で $body オブジェクトを使用します。
マクロに body があると指定している場合 (No macro body を選択していない場合)、$body オブジェクトを使用できます。
例: マクロ名が helloworld であるとします。
テンプレートに次のコードを入力します。
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 属性自体には名前がありません。下記の 名前 セクション参照。 | 必須 |
title | パラメーターのタイトルはマクロ ブラウザーに表示されます。タイトルを指定しない場合、Confluence はパラメーター名を使用します。 | 推奨 |
type | パラメーターのフィールド タイプ。下記の タイプ セクション参照。 | 推奨 |
desc | パラメーターの説明はマクロ ブラウザーに表示されます。 | 任意 |
必須 | ユーザーがこのパラメーターの情報を入力する必要があるかどうかを指定します。既定は false です。 | 任意 |
複数 | パラメーターに複数の値を使用できるかどうかを指定します。既定は false です。 | 任意 |
default | パラメーターの既定値。 | 任意 |
パラメーター名
パラメーター名はリストの最初の属性です。name 属性自体には名前がありません。
例： 次のコードは、「foo」と「bar」という名前の 2 つのパラメーターを定義します。
## @param foo
## @param bar
パラメーター タイプ
パラメーターのフィールド タイプ。タイプを指定しない場合、既定値は string になります。
パラメーター タイプ | 説明 |
|---|---|
ブーリアン | ユーザーにチェックボックスを表示し、マクロに 「true」または「false」の値を文字列として渡します。 |
enum | 選択する値の一覧を提示します。値を指定して、マクロ ブラウザのドロップダウンに表示します。列挙型の値を指定する例： i18n に関する注意: Confluence は列挙値の国際化をサポートしていません。ユーザーに表示される値は、大文字表記されたパラメーター値としてマクロに渡される値です。この場合は、「Grey」、「Red」などです。 |
文字列 | テキスト フィールド。これが既定のタイプです。必須フィールドを持つ例： |
confluence-content | ユーザーに対してページやブログ投稿の検索を許可するコントロールを提供します。例: |
username | ユーザーを検索します。 |
spacekey | スペースを選択する一覧を提示します。マクロにスペース キーを渡します。例： |
日付 | Confluence はこのタイプを受け入れますが、「文字列」と同じように扱います。例: 日付に関する注意事項: ユーザーは任意の形式で日付を入力することができます、管理者は、ユーザー マクロの日付形式を検証する必要があります。 |
int | Confluence はこのタイプを受け入れますが、「文字列」と同じように扱います。既定値を持つ例： |
パーセンテージ | Confluence はこのタイプを受け入れますが、「文字列」と同じように扱います。例： |
マクロ コードでパラメーターを使用する
パラメーターは、テンプレートでは $paramfoo、$parambar ("foo" および "bar" という名前のパラメーターの場合) などの形式で使用できます。
通常、不足している $paramfoo などのパラメーターは、出力で '$paramfoo' などと表示されます。パラメーターが設定されていない場合に何も表示しないようにするには、ドル記号 ($) の後に感嘆符 (!) を付けて「$!paramfoo 」のようにします。
パラメーター不使用
マクロがパラメーターを許可しない場合、テンプレートで @noparams を使用する必要があります。
ユーザー マクロにパラメーターが含まれておらず、@noparams を指定していない場合、マクロ ブラウザに自由形式のテキスト ボックスが表示されます。ユーザーはそこで未定義のパラメーターを入力できます。マクロがパラメーターを許可しない場合、このことが混乱を招く場合があります。
例： テンプレートの冒頭部分に次の行を追加します。
## @noparams
マクロで使用可能なオブジェクト
次の Confluence オブジェクトをマクロで使用できます (マクロ本文とパラメーターを含む)。
変数 | 説明 | クラス リファレンス |
|---|---|---|
| マクロ本文 (マクロに本文がある場合) | 文字列 |
| マクロに渡される名前付きパラメーター（ "foo"、"bar"） | 文字列 |
| Confluence プロパティを取得するのに便利な | |
| 特に | |
| このコンテンツ オブジェクト (ページ、ブログ投稿など) が格納されている | |
| このマクロが含まれている現在の |
開発者向けドキュメントで説明したように、マクロは、既定のベロシティ コンテキストで利用可能なオブジェクトにアクセスすることもできます。
セキュリティに関する考慮事項
ユーザー マクロを作成する際は、$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" に設定されますされます (つまり、それらは表示されません)。