Best Practices for Writing User Macros

This section contains tips and suggestions for best practice in macro coding. To see how to write a user macro and add it to your Confluence site, take a look at our guide to writing user macros.

Add a Descriptive Header to your Macro Template

We recommend that you include a short description of your macro via comments at the top of the Template field as shown below. You can see an excellent example in the 'Image rollover' user macro.

## マクロ タイトル: マクロ名
## マクロに本文があるかどうか: Y / N
## 本文の処理: 選択した本文処理オプション
## 出力: 選択した出力オプション
##
## 開発者: My 名前
## 作成日: dd/mm/yyyy
## インストール担当者: 自分の名前

## マクロが行う動作の短い説明

Expose your Parameters in the Macro Browser

Confluence offers great options for making your macro look good in the macro browser. You can specify the macro category, link to an icon, define the parameters that the macro browser will use to prompt the user for information, and more.

In particular, read the documentation on defining the macro parameters to be displayed in the macro browser.

Supply Default Values for Macro Parameters

You cannot guarantee that a user will supply parameters, so one of the first things to do in the macro is check that you have received some value if you expect to rely on it later on in the macro code.

In the example below, the macro expects three parameters. It substitutes sensible defaults if they are not supplied:

#set($spacekey= $paramspacekey)
#set($numthreads= $paramnumthreads)
#set($numchars= $paramnumchars)

## Check for valid space key, otherwise use current
#if (!$spacekey)
  #set ($spacekey=$space.key)
#end

## Check for valid number of threads, otherwise use default of 5
#if (!$numthreads)
  #set ($numthreads=5)
#end

## Check for valid excerpt size, otherwise use default of 35
#if (!$numchars)
  #set ($numchars=35)
#end

Related Topice

ユーザーマクロを書く