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.
Read on for detailed instructions, or see the example if you prefer to learn by looking at code.
This tutorial assumes you're already familiar with the basics of Forge development. If this is your first time using Forge, see Getting started first.
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 2modules: 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
.
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.
MacroConfig
component, create a function that constructs the configuration of the
UI kit components you're using.
1 2import ForgeUI, { MacroConfig, TextField } from '@forge/ui'; const Config = () => { return ( <MacroConfig> {/* Form components */} <TextField name="age" label="Pet age" /> </MacroConfig> ); };
1 2import 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.
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.
useConfig
hook in your app code.
1 2import { useConfig } from '@forge/ui'; const config = useConfig();
1 2config.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>
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 2import 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: