Create Custom Macro

Script macros allow you to include dynamic content.

Create a Custom Macro

Follow these steps to create a custom macro:

  1. Select the Cog icon, and then select General Configuration.

  2. Scroll to the ScriptRunner section in the left-hand navigation, and then select Macros.

  3. Select the Create Macro button.

  4. Select the Custom Script Macro link.

  5. Fill out the following fields:

    • Key: Enter a unique key for your macro.
    • Name: Enter a name for your macro.
    • Description: Enter a description for your macro. This appears in the macro window.

    • Body Type: Use None, Plain Text, or Rich Text to type in the body of the macro.

      If you choose Rich Text, you'll want the script to return some HTML. As noted here, use Groovy's Markup Builder and sanitize any input you get from the users, such as macro parameters.

      import groovy.xml.MarkupBuilder

def writer = new StringWriter()
def builder = new MarkupBuilder(writer)
builder.strong(body)
writer.toString()

    • Output Type: Use Block or Inline to change the layout flow of the macro.
    • Parameters: If you choose to add a parameter, select + Parameter.
      The following fields appear:
       The Parameter screen for custom macros
      1. Choose your Parameter Type. 
      2. Enter your parameter Name.
      3. Enter your parameter Label.
      4. Enter your parameter Description.
      5. Enter the parameter Default.
      6. Check Required or leave it blank if the parameter is optional. 

    • Macro Code: Use to change the content of the macro.

    • Macro JavaScript Code (optional): Use to change the behaviors of the macro.

    • Macro CSS Style (optional): Use to change the style of the macro.

      If you use the File tab here, the script directory in your home directory (or the directory you use for the CSS) needs to be set up as a web resource directory. See Web Resource for more information.

    • Lazy Loaded: Check this box if the macro takes a few seconds to load.

      Lazy Loaded Macro

      If you have a macro that takes more than a second or so to run, consider checking the Lazy Loaded box. The Lazy Loaded box means that the rendering of the page is not delayed until the macro has executed. Instead, the traditional "spinning gears" icon appears, and the macro content is loaded asynchronously via Representational State Transfer (REST). For an example of a macro that needs Lazy Loaded, check out the Macro Tips example.
  6. Select Add.
Your custom macro appears in the macro list.


Use a Custom Macro

You can choose your custom macro when you open a Confluence editor (like Create a Page) in the macro browser. 

  1. Select the macro browser, and then select Other Macros. 
    The Other Macros button selected

  2. Find your macro in the list, and click on it. 

  3. Enter any required information in the window that appears. 

    If you already had the editor open, you need to shift-refresh after editing macros definitions.

    Any parameters that you 

  4. Select Insert. 

The macro appears where you are working. For example, Test Custom Macro appears on the Testing page.

An image of how a custom macro appears on a Confluence page in edit mode.

Use Binding Variables

Your script has access to the following binding variables, without the need for them to be declared:

  • parameters: A Map<String, String> for accessing user-provided macro parameters. The map’s keys are the parameter keys, so to get the color parameter use parameters.color.

  • body: The body of the macro. The value is null if there is no body.

  • context: A ConversionContext contains information about the current page and output device type (desktop, mobile). Use this for methods of XhtmlContent.

For an example of a macro that uses binding variables, check out Create a Macro with Parameters.

Further Reading

For more information about custom macros, check out the following documentation: 


On this page