The Adaptavist Group LogoDocumentation

Custom Macros

Use this feature to create your own macros.

To see examples of custom macros, check out these pages:

Choose a macro type

Static Content macros render directly in the page and use the page's styling.

Dynamic Content macros render in their own i-frame, separate from the page, and you can customize them with CSS and JavaScript.

Say you're building a Confluence page where people sign up for a company picnic.

  • To show a list of who's bringing which food, pulled from another Confluence page, use a Static Content macro.

  • To show the weather forecast from an external website, in a block element, use a Dynamic Content macro.

    • You can use the CSS field to create custom styling, like displaying the temperature in an italic, blue font.

    • You can use the JavaScript field to add custom behaviors to the macro, like a button that would toggle the temperature reading between Farenheit and Celcius when clicked.

Comparison table

Static Content MacroDynmaic Content Macro (default)
Best forShow Confluence content so it looks like part of the pageShow external content, or output that needs custom styling or behavior
FormattingInlineBlock
Where it renders/where data is storedDirectly in the pageIn its own i-frame, separate from the page
StylingUses the page's stylingDoesn't use the page styling. Custom CSS applies only inside the i-frame.
CSS and JavaScriptNot availableOptinal CSS and JavaScript fields appear when this type is selected
External URLsDo not render; display as plain textLoad after the page, so users may briefly see a loading state
Performance-Each macro loads in its own i-frame; rendering multiple on a single page can cause performance issues. A page with 100 Dynamic macros loads 100 i-frames, which uses a lot of resources*

* If a macro will appear many times on one page, such as a template or table row, use Static Content macros as much as possible.

Warning: You can change a macro's type after you create it, but features specific to the old type stop working. For example, if you change a macro from Dynamic to Static, any previously created CSS and JavaScript no longer apply.

Notes for all macro types

Create a custom macro

  1. Select Create Custom Macro.
  2. Fill out the fields that appear:
    1. Macro Name: Enter a name to identify your macro for you and your users. This is the title that users will search for to find the macro in the Browse window.
    2. Description: Explain what your macro accomplishes.
    3. Enabled (radio button): Control whether your macro can be made available to your users.
    4. Macro Type: Select Static Content Macro or Dynamic Content Macro (Default). See Choose a macro type for more.

      1. If Dynamic Content Macro is selected, two additional optional fields appear:

        1. The CSS field which allows custom styles to be applied to the macro output.

        2. The JavaScript field where a script can be entered and executed when the macro output is rendered.

    5. Body Type: Set the body type of the macro.
      • Rich Text: The macro allows Rich Text content to be inserted and formatted.
      • Plain Text: The macro allows Plain Text, which is unformatted, to be inserted.
      • None: No body.
      • Output Type: Choose how the macro appears on the screen.
        • Block: The macro will be on its own line on the Confluence page.
        • Inline: The macro will be inline with other content on the Confluence page.
      • Script to Execute: Enter the script for the macro here.
      Note: Different macro editing experiences.

      The Body Type you select for your custom macro determines how a user can edit the macro when they apply it to a page.

      • If you select Rich Text, your user can edit the body of the macro directly on the page.
      • If you select Plain Text, your user is directed to macro editor to enter their body of the macro.
      • If you select None, your user sees their macro without a body to edit.
  3. Add any parameters you need for the macro's functionality by clicking Add Parameter.
    Tip: Implicit parameters

    The parameters that are available for use that you don't have to add using this method are:

    • pageVersion

    • macroId

    • spaceKey

    • pageId

    Implicit parameters are stored in the same map array as user-defined parameters and can be used in the same way. Avoid giving user-defined parameters the same name as these implicit parameters. You cannot have two items in a map array with the same name.

    For each parameter that you add, a modal appears where you fill out the Type, Name, Description, Required, and Hidden fields.

    Tip: More parameter information

    For more information on adding macro parameters, visit Macro Parameters.

  4. Select Save.

    The macro now appears on the main macro screen, where you can see macro information and enabled status.

Search documentation

Start typing to search the docs.