The Macro Javascript module, an early access feature, is subject to change and is only available to participants in the Early Access Program (EAP). For additional information, please refer to the Multi-Bodied Macro Extensibility for Confluence Cloud EAP announcement.

Macro (EAP)

Overview

The Macro Javascript module is designed to manage multi-bodied macros (macros that have a multi-body-rich-text bodyType). This module enables you to manipulate the macro bodies and allows for the storage and retrieval of macro parameters. The module is available in both the editor and renderer, however, modifications to the macro are not possible in the renderer (further details are provided below).

For a more comprehensive understanding of multi-bodied macros and a guide on how to utilize some of these methods, please refer to the tutorial.

Methods

addBody()

Add a new body to the multi-bodied macro. At the moment, the total number of bodies cannot exceed 5. When a new macro is added to the page, it comes with a single body by default. This body becomes active and visible to users.

This method can't be used in the renderer.

Returns

Promise<Boolean>

Example

1
2
await AP.macro.addBody();

removeBody(index)

Remove a specified body from the multi-bodied macro. All bodies located to the right shift to the left after the body is removed. If the body being removed is the last, the multi-bodied macro is removed from the page.

This method can't be used in the renderer.

Parameters

Name	Type	Description
index	Number	The index of the body to remove.

Returns

Promise<Boolean>

Example

1
2
await AP.macro.removeBody(1);

showBody({ body, frame })

By default, the first body of the multi-bodied macro is active (visible to users). This function brings a specified body to the front. Use this function while a user interacts with a macro or to show a specific body by default.

Parameters

Name	Type	Description
body	Number	The index of the body to show (make active).
frame	Number	The index of the frame in which the body should be shown. (The current value of this parameter is disregarded. However, it is intended to be utilized in future releases.)

Returns

Promise<Boolean>

Example

1
2
await AP.macro.showBody({
  body: 4,
  frame: 0,
});

getBodyCount()

Returns the number of bodies created in the macro.

Returns

Promise<Number>

Example

1
2
const numberOfBodies = await AP.macro.getBodyCount();

getParameters()

Returns the macro parameters in the form of a collection of key/value pairs.

Returns

Promise<Record<string, string>>

Example

1
2
const macroParams = await AP.macro.getParameters();

updateParameters(metadata)

Update macro parameters. Use this function to store any metadata associated with bodies.

To ensure that parameters are used and stored correctly, they should be defined in the module's parameters section. For those parameters not intended to be altered via the configuration panel, they should be marked as hidden.

This method can't be used in the renderer.

Parameters

Name	Type	Description
metadata	Record<string, string>	The collection of key/value pairs

Returns

Promise<Boolean>

Example

1
2
await AP.macro.updateParameters({
  tabs: JSON.stringify([
    {
      title: "Tab 1",
      isActive: true,
      bodyIndex: 0,
    },
    {
      title: "Tab 2",
      isActive: false,
      bodyIndex: 1,
    },
  ]),
});