Add configuration to a macro

This page describes how to add configuration to a Confluence macro created with Forge. Configuration enables users to customize what displays in the macro by setting values in a form. Users access the configuration by editing the macro, as shown below.

This guide assumes you’ve created a Confluence macro using Forge and need to add configuration to it. If you haven’t already created a macro, see Getting started for step-by-step instructions on setting up Forge and creating a macro.

Before you begin

Make sure you have the latest version of the UI kit. To update your version, navigate to the app's top-level directory, and run npm install @forge/ui@latest --save on the command line.

Add configuration to the module

To add configuration to a macro, you need to introduce a new function to the macro module in your manifest.yml file. You should add this function as a property to a config property in your macro module.

After doing this, your manifest.yml should look like the following, with your own values for each of the properties.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

modules:
  macro:
    - key: pet-facts
      function: main
      title: Pet
      description: Inserts facts about a pet
      config:
        function: config-function-key
  function:
    - key: main
      handler: index.run
    - key: config-function-key
      handler: index.config
app:
  id: "<your app id>"
  name: pet-facts-macro

Create the configuration

You can create the configuration with a MacroConfig component. The MacroConfig component can contain certain form components, which determine how the user can configure the macro. Configuration is stored in key-value pairs corresponding to each form component.

1. Using the MacroConfig component, create a function that constructs the configuration of the UI kit components you're using.

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10

   import ForgeUI, { MacroConfig, TextField } from '@forge/ui';
   
   const Config = () => {
     return (
       <MacroConfig>
         {/* Form components */}
         <TextField name="age" label="Pet age" />
       </MacroConfig>
     );
   };

2. Export your configuration function using the render function component.

   1
   2
   3

   import ForgeUI, { render } from '@forge/ui';
   
   export const config = render(<Config />);

Use the configuration

You access the configuration for a macro in your app code with the useConfig hook. When a macro is invoked, the useConfig hook returns the key-value pairs set in the configuration. The key is the name property on the form component in configuration, and the value is what the user enters.

1. Call the useConfig hook in your app code.

   1
   2
   3

   import { useConfig } from '@forge/ui';
   
   const config = useConfig();

2. Access the data by key.

   1

   config.age

1
2
3
4
5
6
<SectionMessage title="You need to configure this macro" appearance="warning">
  <Text>
    While editing the page, select the macro, and click on the pencil icon
    to display configuration options.
  </Text>
</SectionMessage>

Example

A macro that displays the name and age of a pet. By default, the macro displays Unnamed Pet is 0 years old. A user can edit the macro to set the name and age. For example, if a user submits the name Fluffy and age 2, the macro displays Fluffy is 2 years old.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

import ForgeUI, {
  render,
  Macro,
  MacroConfig,
  Text,
  TextField,
  useConfig
} from "@forge/ui";

const defaultConfig = {
  name: "Unnamed Pet",
  age: "0"
};

const App = () => {
  // Retrieve the configuration
  const config = useConfig() || defaultConfig;

  // Use the configuration values
  return <Text>{config.name} is {config.age} years old.</Text>;
};

export const run = render(
  <Macro app={<App />} />
);


// Function that defines the configuration UI
const Config = () => {
  return (
    <MacroConfig>
      <TextField name="name" label="Pet name" defaultValue={defaultConfig.name} />
      <TextField name="age" label="Pet age" defaultValue={defaultConfig.age} />
    </MacroConfig>
  );
};

export const config = render(<Config />);