Macros are small code generators that perform a task. Script macros allow you to include dynamic content.
Create a Custom Macro
Follow these steps to create a custom macro:
Select the Cog icon, and then select General Configuration.
Scroll to the ScriptRunner section in the left-hand navigation, and then select Macros.
Select the Create Macro button.
Select the Custom Script Macro link.
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.
- 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:
- Choose your Parameter Type.
- Enter your parameter Name.
- Enter your parameter Label.
- Enter your parameter Description.
- Enter the parameter Default.
- Check Required or leave it blank if the parameter is optional.
Macro Code: Use to change the content of the macro.
Macro CSS Style (optional): Use to change the style of the macro.
Lazy Loaded: Check this box if the macro takes a few seconds to load.
Lazy Loaded MacroIf 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 Display Atlassian Versions example.
- Select Add.
Use a Custom Macro
You can choose your custom macro when you open a Confluence editor (like Create a Page) in the macro browser.
Select the macro browser, and then select Other Macros.
Find your macro in the list, and click on it.
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
- Select Insert.
The macro appears where you are working. For example, Test Custom Macro appears on the Testing page.
Use Binding Variables
Your script has access to the following binding variables, without the need for them to be declared:
Map<String, String>for accessing user-provided macro parameters. The map’s keys are the parameter keys, so to get the
body: The body of the macro. The value is
nullif there is no body.
For an example of a macro that uses binding variables, check out Create a Macro with Parameters.
For more information about custom macros, check out the following documentation: