Macro Editor

Macro Parameters go a long way when it comes to macro configuration, but there are cases when a macro add-on needs more control over the UI.

Defining a Macro Editor allows you to implement a custom UI for the macro, by specifying a URL to a page in your add-on which will be shown in the dialog iFrame.

In order to persist custom data in your macro editor, use the Javascript Confluence API and the Dialog API. For example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
AP.require(["confluence", "dialog"], function (confluence, dialog) {
    function onSubmit() {
        var macroParams = {
            myParameter: value
        };
        confluence.saveMacro(macroParams);
        confluence.closeMacroEditor();
        return true;
    }

    dialog.getButton("submit").bind(onSubmit);
});

In order to retrieve the custom data again when the editor is opened, use confluence.getMacroData (see Confluence API):

1
2
3
4
5
AP.require("confluence", function (confluence) {
    var macroData = confluence.getMacroData(function(macroParams) {
        doSomethingWith(macroParams.myParameter);
    });
});

Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "editor": {
    "url": "/map-editor",
    "editTitle": {
      "value": "Edit Map"
    },
    "insertTitle": {
      "value": "Insert Map"
    }
  }
}

Properties

url

Type
string
Format
uri-template
Required
Yes
Description

The URL to the macro configuration page in the add-on.

cacheable

Type
boolean
Defaults to
false
Description

Returns whether the URL should be cacheable. Cacheable URLs are taken directly from the add-on descriptor, and lack all additional query parameters:

  • standard iframe query parameters
  • product context parameters
  • JWT token

editTitle

Type
i18n Property
Description

An optional title that will be shown in the edit dialog header for an existing macro.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
{
  "value": "My text"
}

Properties

value
Type
string
Required
Yes
Description

The human-readable default value. This will be used if no translation exists.

i18n
Type
string
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

height

Type
string
Max length
10
Description

The preferred height of the edit dialog, e.g. 300px.

insertTitle

Type
i18n Property
Description

An optional title that will be shown in the edit dialog header for a new macro.

Represents a string that can be resolved via a localization properties file. You can use the same i18n Property key and value in multiple places if you like, but identical keys must have identical values.

Example

1
2
3
{
  "value": "My text"
}

Properties

value
Type
string
Required
Yes
Description

The human-readable default value. This will be used if no translation exists.

i18n
Type
string
Description

The localization key for the human-readable value. Translations for the keys are defined at the top level of the add-on descriptor.

width

Type
string
Max length
10
Description

The preferred width of the edit dialog, e.g. 500px.