Macro

The macro module inserts dynamic content into the user interface via an editor. Editor macros are only compatible with the Atlassian editor. All cloud sites use the Atlassian editor by default.

The macro module works in Confluence, where the macro is inserted by typing / and selecting from the quick insert menu of the editor. The macro module is implemented by a Forge function.

Manifest structure

1
2
modules {}
└─ macro []
   ├─ key (string) [Mandatory]
   ├─ resource (string) [Mandatory]
   ├─ render (string) [Optional]
   ├─ resolver {} [Optional]
   ├─ viewportSize (string) [Optional]
   ├─ title (string | i18n) [Mandatory]
   ├─ icon (string) [Optional]
   ├─ categories (string[]) [Optional]
   ├─ unlicesedAccess (List<string>) [Optional]
   ├─ description (string | i18n) [Optional]
   ├─ hidden (boolean) [Optional]
   └─ config (boolean | {} | config object) [Optional]
     ├─ icon (string) [Optional]
     ├─ title (string | i18n) [Optional]
     ├─ resource (string) [Mandatory]
     ├─ render (string) [Optional]
     ├─ viewportSize (string) [Optional]
     └─ openOnInsert (boolean) [Optional]
   ├─ adfExport {} [Optional]
   ├─ layout (string) [Optional]
   └─ autoConvert [] [Optional]
     └─ matchers [] [Mandatory]
        └─ pattern (string) [Mandatory]

resources []
├─ key (string) [Mandatory]
└─ path (string) [Mandatory]

Properties

i18n object

Dynamic module (Preview)

This module can also be declared as a dynamic module. However, this capability is currently available as a Forge preview feature.

For more details, see Dynamic Modules.

When you register a dynamic macro module, the data object uses the same properties as a static macro module in the manifest. The module key is generated server-side and returned in the create response; for updates, supply it in the URL path.

Code examples

The following examples show Dynamic Module implementations specific to this module. For more detailed information about the API used in these examples (including error handling information), see Dynamic Modules API.

Create a dynamic macro module

1
2
import { asApp } from "@forge/api";
const payload = {
  "type": "macro",
  "data": {
    "resolver": {
      "function": "resolver"
    },
    "resource": "main",
    "render": "native",
    "title": "Dynamic macro",
    "description": "A macro registered with the Dynamic Modules API",
    "autoConvert": {
      "matchers": [
        {
          "pattern": "https://www.example.com/*/about"
        }
      ]
    }
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/dynamic/module/`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'POST',
  body: JSON.stringify(payload),
});
const body = await response.text();
console.log(`Response: ${response.status} ${body}`);

Update a dynamic macro module

1
2
import { asApp } from "@forge/api";
const key = "macro-dynamic";
const payload = {
  "type": "macro",
  "data": {
    "resolver": {
      "function": "resolver"
    },
    "resource": "main",
    "render": "native",
    "title": "Updated dynamic macro",
    "description": "A macro updated with the Dynamic Modules API",
    "autoConvert": {
      "matchers": [
        {
          "pattern": "https://www.example.com/*/about"
        },
        {
          "pattern": "https://www.example.com/*/music"
        }
      ]
    }
  }
}
const response = await asApp().requestAtlassian(`/forge/installation/v2/dynamic/module/${key}`, {
  headers: {
    'Content-Type': 'application/json'
  },
  method: 'PUT',
  body: JSON.stringify(payload)
});
const body = await response.text();
console.log(`Response: ${response.status} ${body}`);

Extension context

UI Kit and Custom UI

Macro autoconvert

Macro autoconvert allows your app to automatically insert a macro into the editor when a user pastes a recognized URL. This is achieved by defining URL patterns in the manifest using the matchers property. These matchersare registered in the editor when the app is installed.

Example

1
2
modules:
  macro:
    - key: autoconvert-app
      resource: main
      render: native
      resolver:
        function: resolver
      title: Forge app for autoconvert
      description: Example for autoconvert manifest
      autoConvert:
        matchers:
          - pattern: https://www.example.com/*/about
          - pattern: https://www.example.com/*/music
          - pattern: https://*.example.com/*/movies/*
          - pattern: https://example.com/gifs/*/
          - pattern: http://*.example.com/media/*/.gif
          - pattern: customScheme:\\example:custom
          - pattern: customScheme:example:*
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: "<your app id>"

The URL patterns use wildcards to match parts of the URL that can vary, such as unique IDs. Wildcards are defined using *.

Use a new * for each segment in the URL you want a wildcard for. For example, https://www.example.com/* will match https://www.example.com/about but will not match https://www.example.com/about/contact. To match this path as well you need to include https://www.example.com/*/* as one of your matchers.

You'll need to define a separate matcher for each relevant internet protocol, such as http and https.

Creating custom URL schemes is also supported. For example, customScheme:* can be used to match any URL that starts with that custom scheme such ascustomScheme:\\example:custom. Any custom schemes will have to be registered on the system they will be used on, such as iOS, Windows or Android. Either :\\ or just : can be used as the initial separator in the URL scheme then : thereon.

Example patterns

Wildcard path

1
2
- "pattern": "https://www.example.com/*/about"

Wildcard in subdomain

1
2
- "pattern": "https://www.*.example.com/help"

Matching wildcard paths

1
2
- "pattern": "https://bitbucket.org/*/*/*"

Matching custom URL schemes

1
2
- "pattern": "customScheme:example:custom"
- "pattern": "customScheme:\\example:custom"

Matching custom URL scheme wildcard

1
2
- "pattern": "customScheme:example:*"
- "pattern": "customScheme:\\example:*"

When a pasted URL matches a defined pattern, the macro is created in the editor, and the URL is captured and inserted as a parameter into the macro body. This parameter can be accessed using the autoConvertLink property.

Macro custom configuration

Extension context in the macro editor

There are two additional extension context parameters available when you are in macro configuration editor context.

Options for submitting the configuration

This table details the options supported by view.submit() in the context of custom macro configuration.

1
2
view.submit({
  config: {
    param1: "test",
    param2: [1, 2, 3]
  }
})

1
2
view.submit({
  config: {},
  body: {
    type: "doc",
    version: 1,
    content: [
      // ADF content
    ]
  }
})

1
2
view.submit({
  config: {},
  keepEditing: true
})

Supported config payload format

The config payload only supports values that can be serialised to JSON.

The following types are allowed on the payload:

1. undefined
2. string
3. number
4. boolean
5. object (can contain any of the allowed types, including nested objects)
6. array (can contain strings, numbers, booleans, and objects; all items in the array must be of the same type).

The following types are not allowed:

• Nested arrays (arrays as direct children of arrays)
• null
• Any data types that are not serializable to JSON (e.g. Map, Set, etc.)

If you want greater control over the storage format of your configuration, such as being able to store nested arrays and nulls, we recommend serializing your configuration to JSON upfront, and storing it as a string.

Error code guide

This table details the possible error codes that may be thrown by view.submit():

Notes on layout and sizing

Inline macro width (Custom UI)

Custom UI inline macros are rendered inside an <iframe>. All major browsers apply a default minimum width of 300px to <iframe> elements, which means your inline macro will render at a minimum of approximately 300px wide even if the content inside is smaller.

To override this and allow the macro to shrink to fit its content, add the following CSS to your Custom UI app. The recommended approach is to add it in a <style> tag or an external stylesheet in your index.html:

1
2
<style>
  body {
    width: fit-content;
  }
</style>

This tells the browser to size the body to its content rather than expanding to the iframe default width. The fit-content value is supported across all browsers that Forge targets.

1
2
permissions:
  content:
    styles:
      - "unsafe-inline"

Tutorials

Add configuration to a macro with UI Kit

The app allows you to customize what the macro displays by adjusting settings in a form.

Start tutorial

Add custom configuration to a macro

The app’s configuration can be edited using a custom configuration modal.

Start tutorial

Using rich-text bodied macros

How to configure the manifest and render rich text body content.

Start tutorial