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

The macro configuration feature was added to Forge UI in version 0.2.0. You'll need to update your Forge UI if the version is out of date.

1

npm install @forge/ui@latest --save

Create the configuration

You create the configuration with a ConfigForm. The ConfigForm can contain any form component and returns key-value pairs on submit. See Form for a list of form components.

Use configuration to store general data, but not sensitive information. The configuration data is stored in plaintext, so other users and apps can modify the values.

1. Export your macro using the Macro component.

   1

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

2. Add a config prop to include the configuration.

   1

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

3. Create a function that constructs the Forge UI for the configuration.

   1
   2
   3

   const Config = () => {
     // Your ConfigForm...
   };

4. Create the ConfigForm using form components.

   1
   2
   3
   4
   5
   6
   7

   const Config = () => {
     return (
       <ConfigForm> 
         // Form components
       </ConfigForm>
     );
   };

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, and the value is what the user enters.

1. Call the useConfig hook in your app code.

   1

   const config = useConfig();

2. Access the data by key.

   1

   config.age

1
const { name, age } = useConfig();

Set default configuration (optional)

Default configuration enables you to supply values that define the initial state of the macro. The useConfig hook returns the default configuration values until a user sets new values. Note, default configuration values passed to a macro in the defaultConfig prop override the defaultValue prop on the form components.

1. Add a defaultConfig prop to the Macro component.

   1
   2
   3
   4
   5
   6
   7

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

2. Create an object that sets the default configuration.

   1
   2
   3
   4
   5
   6
   7
   8
   9

   export const run = render(
     <Macro
       app={<App />}
       config={<Config />}
       defaultConfig={{
         key: "value"
       }}
     />
   );

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
39

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

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

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

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

// A macro containing props for the app code, configuration,
// and default configuration values.
export const run = render(
  <Macro
    app={<App />}
    config={<Config />}
    defaultConfig={{
      name: "Unnamed Pet",
      age: "0"
    }}
  />
);