Rate this page:
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.
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.
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
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.
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>
);
};
Export your configuration function using the render function component.
1 2 3
import ForgeUI, { render } from '@forge/ui';
export const config = render(<Config />);
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.
Call the useConfig
hook in your app code.
1 2 3
import { useConfig } from '@forge/ui';
const config = useConfig();
Access the data by key.
1
config.age
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 />);
Rate this page: