Introducing live macros to support a new editing experience in Confluence Cloud

Reading Time: 3 minutes

We’re in the midst of rolling out a new editing experience to Confluence Cloud in order to tackle some key customer pain points, and this involves significant changes to Confluence macros.

This page will outline the key differences and take Confluence macro developers through the steps to update their macros.

Live WYSIWYG (What you see is what you get) macros

One of the big improvements we're working on as part of this rollout is making the editing experience consistent with the viewing experience, so that pages look the same when editing them as they do once published.

Macros are a huge part of this. In the current editor, most of the macros display as grey boxes when a page is being edited, and only render correctly in the published version. These grey boxes don't give any indication of the size, layout, or information contained in the macro.

In the new editor, these grey boxes have been replaced with live macros, which look the same regardless of whether you're viewing or editing the page. That means you no longer have to worry about what the page will look like when you press Publish.

We’ve heard your feedback, so with this new rollout live macros will be available for third party developers as well.

How to make your macro live

To make your macro live in the new editor, your macro needs to have “outputType”: “block” and “bodyType”: “none” in the atlassian-connect.json. This then replaces the old placeholder image with an overlay displaying the macro as it would when the published page is being viewed.

"modules": {
  "dynamicContentMacros": [
    {
     "height": "500px",
      "url": "/macro?pageTitle={page.title}",
      "description": {
        "value": "Shows a configurable map"
      },
      "key": "dynamic-macro-example",
     "outputType": "block",
     "bodyType: "none"
    }
  ]
}

Controlling the size of the macro

Macro width is controlled by the editor. There are three different widths for macros: Block, wide, and full width. Don’t set any width in atlassian-connect.json or in css as it may cause the macro to work incorrectly.

The height of the macro is controlled by the CSS macro height. You can set and change it dynamically as appropriate to your use case.

Updating the macro on the view page

After editing a WYSIWYG macro in a custom macro editor, you need to update its parameters, as this is what triggers an update in the editor.

AP.require(["confluence"], function (confluence) {
    confluence.saveMacro({
        'param': version + 1
    });
    confluence.closeMacroEditor();
    return true;
  });

This can be done by storing a revision number in the parameters, or by updating any other parameter you might need to store within the macro.

Deprecation of Nested Bodied Macros

Because we want a page to look the same while editing as it does once it's published, we've decided to deprecate nested bodied macros.

Bodied macros are those such as the "tabs" macro which is popular on server, for which a user defines each individual tab inside the macro, and then on publish, the macro renders as a collection of tabs. For connect macros, these are any macros that have defined “bodyType”: “rich-text”.

You will still be able to define these macros, but you won't be able to nest other macros that have “bodyType”: “rich-text” inside them, as this makes the page look vastly different when editing to what it looks like when published.

Note: We are in the process of redefining the usage of some of Confluence’s native rich text macros like "Expand" and "Page Properties" so that it still will be possible to use other bodied macros inside them.

This deprecation is planned for the end of 2018. Until then, nested bodied macros will continue to work in the old editor, but not in the new editor.

After that date, any nested bodied macros will still display as normal when viewing a published page. However, if that page is edited, they will display as 'unsupported content' that can't be interacted with (except to be deleted).

Need help

If you need help about this change please ask in the Confluence Cloud Development forum in the Developer Community.