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

NameTypeDescription
indexNumberThe 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

NameTypeDescription
bodyNumberThe index of the body to show (make active).
frameNumberThe 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.

The storage for parameters is shared between parameters updated with this function and parameters set with the app descriptor and updated with the side panel. Please use different keys to avoid data loss.

This method can't be used in the renderer.

Parameters

NameTypeDescription
metadataRecord<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,
    },
  ]),
});

Rate this page: