Last updated Feb 10, 2023

Rate this page:

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.

Example of configuring a Forge macro

Read on for detailed instructions, or see the example if you prefer to learn by looking at code.

Before you begin

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.

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

You must run forge deploy in order for manifest changes to be effective, even if you are using forge tunnel.

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
    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
    import ForgeUI, { render } from '@forge/ui';
    
    export const config = render(<Config />);
    

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

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
    import { useConfig } from '@forge/ui';
    
    const config = useConfig();
    
  2. Access the data by key.
    1
    2
    config.age
    

We recommend you add sensible defaults for each of your configuration values.

If it's more sensible for the macro to not have default configuration values, we recommend you display a section message with the appropriate instructions, as shown below:

1
2
<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
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 />);

Rate this page: