Confluence 6 User Macro Best Practices

This page contains tips and advice on best practices for creating user macros.

Add a short description to your macro

We encourage you to add a comment to the Template for your macro , as shown below:

## Macro title: My macro name
## Macro has a body: Y or N
## Body processing: Selected body processing option
## Output: Selected output option
##
## Developed by: My Name
## Date created: dd/mm/yyyy
## Confluence version: Version it was developed for
## Installed by: My Name

## Short description of what the macro does

Show your parameters in the macro browser

The Macro Browser is the easiest way to configure your macros for your users. You can specify the category of your macro, the link of the icon defines the parameters of the information displayed to the user in the macro browser, etc.

Provide default values for macro parameters

Generally speaking, you can't guarantee that the user can provide the user's parameters completely. If a macro checks whether the correct parameters are received, you can specify the parameters in your macro and use them later.

Please refer to the example below, there are 3 parameters in this macro, when the user does not provide parameters, the default values of these parameters will be used.

 
         #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

Consider safety tips

We recommend that you do some permission testing for the macros you define. For example, restrict page and space permissions to avoid possible inadvertent display by users without permissions. Check out the Writing User Macros page.

https://www.cwiki.us/display/CONFLUENCEWIKI/Writing+User+Macros