Create a Macro with Parameters

You can set up a macro that accepts parameters. For example, follow these steps to create a macro that outputs an AUI message.

1. Create a new script macro by selecting the Custom Script Macro link.

2. Set the following fields:

   • Key: message-macro

   • Name: Message

   • Description: Renders an AUI message

   • Body Type: Rich text

   • Output Type: Black

     The completed fields appear in the following image:

     

3. Select the + Parameter button and set the following fields on the form that appears:

   • Parameter Type: string

   • Name: title

   • Label: Title

   • Tick the checkbox for Required

   • Parameter Type: enum

   • Name: level

   • Label: level

   • Tick the checkbox for Required

     The completed fields appear in the following image:

     

4. Select the + Enum Value to add the third enum value and fill out the following fields:

   • Parameter Type: enum

   • Name: level

   • Label: level

   • Tick the checkbox for Required

     Steps 3 and 4 determine the body and two arguments of the macro, which allow you to determine the following components of the message:

     • the title of the message

       • A string

     • the severity of the message (info, warning, error)

       • An enum because only a finite list of level types are accepted

     • the body of the message

       • An enum because only a finite list of level types are accepted

     Find out more about the different parameter types here.

5. For the script, you can type in the following code or put it in a file and enter the relative path to the file, under the script root (as usual).
   
   

   import groovy.xml.MarkupBuilder
   
   def writer = new StringWriter()
   def builder = new MarkupBuilder(writer)
   builder.div('class': "aui-message aui-message-${parameters.level}") {
       p('class': 'title') {
           strong(parameters.title)
       }
       mkp.yieldUnescaped(body)
   }
   writer.toString()

   Copy

   The mkp.yieldUnescaped method is dangerous and should only be used with trusted data. In this particular case, the use of mkp.yieldUnescaped is safe because Confluence does not allow script tags or other potentially malicious HTML in the macro’s body variable. Other user inputs like the ones you specify as macro parameters are not checked in the same way and should not be trusted. It’s imporant that these inputs are handled securely, as discussed in our documentation on custom macros and security.

6. (Optional) Experiment with changing the parameters in the Edit 'Message' Macro dialog box that appears. This screen appears because parameters were marked as required in steps 3 and 4.