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.

For UI Kit 1, see the Macro component documentation for more information.

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]
   ├─ description (string | i18n) [Optional]
   └─ config (boolean | {} | config object) [Optional]
     ├─ title (string | i18n) [Optional]
     ├─ resource (string) [Mandatory]
     ├─ render (string) [Optional]
     ├─ viewportSize (string) [Optional]
     └─ openOnInsert (boolean) [Optional]
   ├─ export {} [Optional]
   ├─ adfExport {} [Optional]
   ├─ layout (string) [Optional]
   └─ autoconvert [] [Optional]
     └─ matchers [] [Mandatory]
        └─ pattern (string) [Mandatory]

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

Properties

i18n object

Extension context

UI Kit and Custom UI

UI Kit 1

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
            
  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.

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/*/*/*"

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.

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

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

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():

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