Using rich-text bodied macros

This tutorial demonstrates how you can use rich-text bodied macros in Forge. It shows how to configure your manifest and render rich body content, using the ADF Renderer React component, or the Confluence convert content body APIs.

You can add simple configuration to a macro using UI Kit components, as described here.

You can add custom configuration to a macro, as described here.

You can also see a sample implementation of a rich-text bodied macro in the rich-text-custom-config-macro sample app.

Before you begin

Make sure you have the following:

• A Forge app with a Confluence macro created using UI Kit or Custom UI.
• The latest version of Forge CLI. To update your CLI version, run npm install -g @forge/cli@latest on the command line.

Step 1: Configure the manifest

To set your macro as a bodied macro, navigate to the app's manifest.yml file and add the line layout: bodied in the macro module properties.

1
2
macro:
  - key: my-macro
    ...
    layout: bodied

Step 2: Extract the macro body

The macro body is the content that the user enters in the editor. This can be retrieved from the context provided by useProductContext() or view.getContext().

1
2
import React from 'react';
import ForgeReconciler, { useProductContext } from '@forge/react';

const App = () => {
  const context = useProductContext();
  const macroBody = context?.extension?.macro?.body;
  // ...
}

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

Step 3: Render rich body content

The ADF body can be rendered in two ways; using the renderer components, or by rendering the raw HTML.

Comparison between using renderer components or HTML export

The following content types are supported by the HTML export, but not supported by the ADF renderer component:

• Embedded static Connect macros
• Embedded Forge macros defining an adfExport function

The following content types are not supported at all by the HTML export or the ADF renderer component:

• Embedded dynamic Connect macros
• Embedded Forge macros without an adfExport function
• Custom emojis

See detailed documentation for the AdfRenderer.

Using renderer components

For UI Kit, you can use the AdfRenderer component, while for custom UI, you can use the ReactRenderer component. Both the AdfRenderer and ReactRenderer component require the prop document, which is an ADF document with the following structure:

1
2
"body": {
  "type": "doc",
  "version": 1,
  "content": [
    // ADF content
  ]
}

We can pass the macro body that we extracted previously into the document prop of AdfRenderer and ReactRenderer components for UI Kit and custom UI respectively.

1
2
import { AdfRenderer } from "@forge/react";

const App = () => {
  // ...
  return macroBody && <AdfRenderer document={macroBody} />
}

Using the Confluence API to export to HTML

Alternatively, you can use requestConfluence() to make a request to the Confluence Cloud platform REST API to convert the macro body into HTML. We can render this HTML directly in our Forge app.

The following code imports requestConfluence, and extracts contentId and macroBody from the context obtained in step 2.

Next, we can construct the async API call for the macro body in HTML form using the Asynchronously convert content body call.

If we want to support rendering embedded content, we must also provide the following query parameters:

• contentIdContext: The content ID for resolving embedded content in the content body
• expand: Return CSS and JavaScript tags in the response for rendering embedded content

Note that this embedded content includes core Confluence macros, but does not support other Connect or Forge macros.

Also note the ADF body (value) is stringified again. This is because the API accepts bodies in various formats, including XML, so it cannot make any assumptions about the format of the body.

1
2
import { requestConfluence } from "@forge/bridge";

async function convertMacroBody(to, macroBody, contentId) {
  const params = new URLSearchParams({
    contentIdContext: contentId,
    expand: "webresource.tags.all,webresource.superbatch.tags.all",
  }).toString();

  const response = await requestConfluence(
    `/wiki/rest/api/contentbody/convert/async/${to}?${params}`,
    {
      method: "POST",
      headers: {
        Accept: "application/json",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        value: JSON.stringify(macroBody),
        representation: "atlas_doc_format",
      }),
    }
  );

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return (await response.json()).asyncId;
}

const macroBody = context?.extension?.macro?.body;
const contentId = context?.extension?.content?.id;

if (macroBody) {
  const asyncId = await convertMacroBody(
    "styled_view",
    macroBody,
    contentId
  );
}

We can obtain the HTML body from the id that is returned from convertMacroBody() using the Get asynchronously converted content body from the id or the current status of the task call.

Note that we inject the expanded CSS and JavaScript tags into the HTML body.

1
2
async function fetchConvertedMacroBody(id) {
  const response = await requestConfluence(
    `/wiki/rest/api/contentbody/convert/async/${id}`,
    {
      headers: {
        Accept: "application/json",
      },
    }
  );

  const { status, error, value, webresource } = await response.json();
  if (status === "FAILED") {
    throw new Error(`Conversion failed: ${error}`);
  } else if (status === "COMPLETED") {
    const scripts = webresource.superbatch.tags.all + webresource.tags.all;
    const html = value.replace("</head>", `${scripts}</head>`);
    return html;
  }
  // Keep polling until completed
  return fetchConvertedMacroBody(id);
}


const htmlBody = await fetchConvertedMacroBody(asyncId);

Rendering the export HTML

Finally, we can directly render the HTML.

1
2
resources:
  ...
  - key: html-frame
    path: resources/html-frame/build

1
2
import { events } from "@forge/bridge";

events.on("PROPS", ({ html }) => {
// Create a fragment, allowing any embedded content scripts to be executed when appended
const documentFragment = document
  .createRange()
  .createContextualFragment(html);
document.body.innerHTML = "";
document.body.appendChild(documentFragment);
});

1
2
import { events } from "@forge/bridge";
import { Frame } from "@forge/react"

const App = () => {
  useEffect(() => {
    events.emit("PROPS", { html: htmlBody });
  }, [htmlBody]);

  return <Frame resource="html-frame" />
}

Additionally, if we want to render embedded content, we must specify the following permissions in the manifest.yml file:

1
2
permissions:
  content:
    styles:
      - "unsafe-inline" # Required for styled_view inline styles in the converted HTML
    scripts:
      - "unsafe-inline" # Rendering embedded content when converted to HTML with expand
  external:
    fetch:
      client:
        - "*.atlassian.net" # Embedded content can call back to Atlassian sites
    images:
      - "*" # Required for images in the converted HTML
    styles:
      # Rendering embedded content when converted to HTML with expand
      - "*.atl-paas.net"
      - "*.cloudfront.net"
    scripts:
      # Rendering embedded content when converted to HTML with expand
      - "*.atl-paas.net"
      - "*.cloudfront.net"

Use the body in an adfExport function

When the page is exported to PDF, Word, or viewed in the page history, you can specify how the macro should be displayed. This is done by specifying an adfExport function, and referencing it in your app's manifest.yml file.

When there is no export function defined, by default, the macro body will be returned.

Accessing the rich text body is done via the extensionPayload.macro.body property.

If you would like to customise the export:

1. Create a new ADF document
2. Insert any extra ADF nodes for customisation (such as paragraphs, shown in the sample code)
3. Insert the rich-text body content from the macro into the document

See the full adfExport tutorial here.

1
2
import { doc, p } from '@atlaskit/adf-utils/builders';

export function adfExport(payload) {
  const macroBody = payload.extensionPayload.macro.body;

  return doc(
    p("This is my export function. Here's the macro content:"),
    ...macroBody.content
  )
}

Troubleshooting