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.

Properties

i18n object

Extension context

UI Kit and Custom UI

UI Kit 1

Macro Configuration

Macro configuration allows you to customize what the macro displays by adjusting settings in a form. To access these settings, you need to go into the edit mode for the macro, as demonstrated below. This gives you the ability to customize the macro's output according to your preferences.

You can use UI Kit components to build this configuration.

Manifest declaration

You will need to add config: true property in your manifest.yml. For example:

1
2
modules:
  macro:
    - key: config-example
      resource: main
      render: native
      resolver:
        function: resolver
      title: Favorite Color
      config: true
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: '<your app id>'
  runtime:
    name: 'nodejs18.x'

Configuration for a UI Kit macro app

Create the configuration

Configuration is stored in key-value pairs corresponding to each Form component.

1. In your src/frontend/index.jsx file, create a component that constructs the configuration of the UI Kit components you're using:

1
2
import React from 'react';
import { Label, Textfield } from '@forge/react';

const Config = () => {
  return (
    <> 
      <Label>First Name</Label>
      <Textfield name="firstName"/>
    </>
  );
};

2. At the bottom of the src/frontend/index.jsx file, call the addConfig method on ForgeReconciler with your config element. Ensure you have ForgeReconciler imported at the top.

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

const Config = () => {
  return (
    <> 
      <Label>First Name</Label>
      <Textfield name="firstName"/>
    </>
  );
};

ForgeReconciler.addConfig(<Config />);

Use the configuration

You access the config for a macro in your app code with the useProductContext hook. When this method resolves, it returns the product context, which will include the key-value pairs set in the config. The key is the name property on the form component in configuration, and the value is what the user enters.

The index.jsx file could look like this:

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

const Config = () => {
  return (
    <>
      <Label>First Name</Label>
      <Textfield name="firstName" />
    </>
  );
};

const App = () => {
  const context = useProductContext();
  const config = context?.extension.config;
  const name = config?.firstName;

  return (
    <Text>Hello {name || 'Fetching config...'}</Text>
  );
};

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

ForgeReconciler.addConfig(<Config />);

Configuration for a custom UI macro app

Create the configuration for a custom UI app

You can create a function component that will return UI Kit components in a custom UI app.

Configuration is stored in key-value pairs corresponding to each Form component.

1. In a static/hello-world/src/Config.js file, create a function component that constructs the configuration of the UI Kit components you're using:

1
2
import React from 'react';
import { Label, Textfield } from '@forge/react';

const Config = () => {
  return (
    <> 
      <Label>First Name</Label>
      <Textfield name="firstName"/>
    </>
  );
};

export default Config;

2. In the static/hello-world/src/index.js file, call the addConfig method on ForgeReconciler with your config element. Ensure you have ForgeReconciler imported at the top.

1
2
import React from 'react';
import ReactDOM from 'react-dom';
import App from './App';
import Config from './Config';
import ForgeReconciler from "@forge/react";

ReactDOM.render(
  <App />,
  document.getElementById('root')
);

ForgeReconciler.addConfig(<Config />);

Use the configuration for a custom UI app

To retrieve the configuration, follow the same steps as above but in your static/hello-world/src/App.js file instead. You can then use the configuration values in your app.

1
2
import React, { useState, useEffect } from 'react';
import { view } from "@forge/bridge";

const App = () => {
  const [context, setContext] = useState(undefined);

  useEffect(() => {
    view.getContext().then(setContext);
  }, []);

  const config = context?.extension.config;
  const name = config?.firstName;

  return (
    <div>
      {`Hello ${name}` || 'Fetching config...'}
    </div>
  );
}

export default App;

Supported components with limited properties

The UI Kit components available for use in the configuration come with certain limitations and have restricted properties. In the latest version of the UI Kit, we support the following components:

• Label
• Checkbox group (Preview)
• Date picker
• Radio group
• Select
• Textfield
• Text area
• User picker

Label

To label the fields in the configuration panel, use the Label component:

Checkbox group

The following subset of UI Kit Checkbox group props can be used in the configuration:

Date picker

The following subset of UI Kit Date picker props can be used in the configuration:

Radio group

The following subset of UI Kit Radio group props can be used in the configuration:

Select

The following subset of UI Kit Select props can be used in the configuration:

Textfield

The following subset of UI Kit Textfield props can be used in the configuration:

Text area

The following subset of UI Kit Text area props can be used in the configuration:

User picker

The following subset of UI Kit User picker props can be used in the configuration:

Example

A macro with configuration could look like this:

1
2
import React from "react";
import ForgeReconciler, { useProductContext } from "@forge/react";
import { Label, Text, Textfield, Select } from "@forge/react";

const options = [
  { name: 'color', value: 'red', label: 'Red' },
  { name: 'color', value: 'blue', label: 'Blue' },
  { name: 'color', value: 'yellow', label: 'Yellow' },
  { name: 'color', value: 'green', label: 'Green' },
  { name: 'color', value: 'black', label: 'Black' },
];

const Config = () => {
  return (
    <>
      <Label>Name</Label>
      <Textfield name="name" />
      <Label>Favorite color</Label>
      <Select 
        name="color" 
        options={options}  
        defaultValue={options[0]}
        placeholder="Select color"
        isRequired
      />
    </>
  )
}
const App = () => {
  const context = useProductContext();
  const config = context?.extension.config;
  const name = config?.name
  const favoriteColor = config?.color;
  
  return (
    <Text>
      {name || "Fetching name..."}'s favorite color is: ${favoriteColor || "Unselected"}
    </Text>
  )
};

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

ForgeReconciler.addConfig(<Config />);

Tutorial