Add configuration to a macro with UI Kit

Configuration allows you to customize what the macro displays by adjusting settings in a form. To access these settings, you need to go into the edit mode for the macro, as demonstrated below. This gives you the ability to customize the macro's output according to your preferences.

Before you begin

Make sure you have the following:

• Confluence macro created using UI Kit or Custom UI.
• The latest version of Forge CLI. To update your CLI version, run npm install -g @forge/cli@latest on the command line.
• The latest version of UI Kit. To update your version, navigate to the app's top-level directory, and run npm install @forge/react@latest --save on the command line. If your macro uses Custom UI, navigate to the resource directory and run the same command.

Add configuration to the Confluence macro module

Create an app using a template.

1. Navigate to the directory where you want to create the app.

2. Create your app by running:

   1
   2
   forge create
   

3. Enter a name for the app.

4. Select the UI Kit category from the list.

5. Select the confluence-macro template from the list.

6. Change to the app subdirectory to see the app files

To add configuration to the Confluence macro module:

1. In the app’s top-level directory, open the manifest.yml file.
2. Add the config property with the value set to true.

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
      resource: main
      render: native
      resolver:
        function: resolver
      title: Pet
      config: true
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: "<your app id>"

1
2
modules:
  macro:
    - key: pet-facts
      resource: main
      render: native
      resolver:
        function: resolver
      title: Pet
      config:
        openOnInsert: true

UI Kit

Create the configuration

You can create a new function component that will return the configuration (Config) components.

Configuration is stored in key-value pairs corresponding to each form component.

1. In your src/frontend/index.jsx file, create a function component that constructs the configuration of the UI Kit components you're using:

1
2
import React from "react";
import { Label, Textfield } from "@forge/react";

const Config = () => {
  return (
    <>
      <Label>Pet age</Label>
      <Textfield name="age" />
    </>
  );
};

1. At the bottom of the src/frontend/index.jsx file, call the addConfig method on ForgeReconciler with your config element. Ensure you have ForgeReconciler imported at the top.

1
2
import React from 'react';
import ForgeReconciler, { Label, Textfield } from '@forge/react';

const Config = () => {
  return (
    <>
      <Label>Pet age</Label>
      <Textfield name="age" />
    </>
  );
};

const App = () => {
  ...
}

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

ForgeReconciler.addConfig(<Config />);

Use the configuration

You access the config for a macro in your app code with the useConfig hook. When the config object is resolved, it returns the key, which is the name property on the form component in configuration, and the value, which is what the user enters.

In your src/frontend/index.jsx file:

1. Add the following imports:

1
2
import React from "react";
import ForgeReconciler, {
  Label,
  Text,
  Textfield,
  useConfig,
} from "@forge/react";

1. Create a component called App and call the useConfig method to get the macro config.

1
2
const Config = () => {
...
};

const App = () => {
  const config = useConfig();

  return (
    <>
      <Text>Hello World</Text>
    </>
  );
};

1. Access the configuration data by key within the App component. Add the second text component with age to the return statement.

1
2
const App = () => {

  ...

  const config = useConfig();
  const age = config?.age;

  return (
    <>
      <Text>
        {age || 'Fetching config...'}
      </Text>
    </>
  );
}

The index.jsx file should look like this:

1
2
import React from "react";
import ForgeReconciler, {
  Label,
  Text,
  Textfield,
  useConfig,
} from "@forge/react";

const Config = () => {
  return (
    <>
      <Label>Pet age</Label>
      <Textfield name="age" />
    </>
  );
};

const App = () => {
  const config = useConfig();
  const age = config?.age;

  return <Text>{age || "Fetching config..."}</Text>;
};

ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

ForgeReconciler.addConfig(<Config />);

1
2
import ForgeReconciler, {
  Label,
  Text,
  Textfield,
  SectionMessage,
} from "@forge/react";
//Add SectionMessage to the import statement

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

Custom UI

Create the configuration

You can create a new function component that will return the configuration (Config) components.

Configuration is stored in key-value pairs corresponding to each form component.

Create an app using a template.

1. Navigate to the directory where you want to create the app.

2. Create your app by running:

   1
   2
   forge create
   

3. Enter a name for the app.

4. Select the Custom UI category from the list.

5. Select the confluence-macro template from the list.

6. Change to the app subdirectory to see the app files

1. In a static/hello-world/src/Config.js file, create a function component that constructs the configuration of the UI Kit components you're using:

1
2
import React from "react";
import { Label, Textfield } from "@forge/react";

const Config = () => {
  return (
    <>
      <Label>Pet Age</Label>
      <Textfield name="age" />
    </>
  );
};

export default Config;

1. In the static/hello-world/src/index.js file, call the addConfig method on ForgeReconciler with your config element. Ensure you have ForgeReconciler imported at the top.

1
2
import React from "react";
import ReactDOM from "react-dom";
import App from "./App";
import Config from "./Config";
import ForgeReconciler from "@forge/react";

ReactDOM.render(<App />, document.getElementById("root"));

ForgeReconciler.addConfig(<Config />);

Use the configuration

To retrieve the configuration, follow the same steps as above by using the useConfig hook in the @forge/react package.

1
2
import React, { useState, useEffect } from "react";
import { useConfig } from "@forge/react";

const App = () => {
  const config = useConfig();
  const age = config?.age;

  return (
    <>
      <div>Hello World</div>
      <div>{age || "Fetching config..."}</div>
    </>
  );
};

export default App;

Add default pet configuration

In this example, by default, the macro displays Unnamed Pet is 0 years old.

Create a default configuration for the pet's name and age, and then add defaultConfig variable as a fallback in case config is not set.

In your src/frontend/index.jsx file outside the Config and App components, add:

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

Then replace the const config inside the App component with the following:

1
2
const actualConfig = useConfig();
const config = actualConfig || defaultConfig;

Add dynamic input values for the pet's name and age.

Now that we have created configurations (name and age) for your macro, we can now enhance this feature to include dynamic input for the pet's name and age.

For example, if a user submits the name Fluffy and age 2, the macro displays Fluffy is 2 years old.

In your index.jsx file:

Add function that defines the config UI for the pet's name and age

1
2
const Config = () => {
  return (
    <>
      <Label>Pet name</Label>
      <Textfield name="name" defaultValue={defaultConfig.name} />
      <Label>Pet age</Label>
      <Textfield name="age" defaultValue={defaultConfig.age} />
    </>
  );
};

Display the pet's name and age using the configuration values

In the return statement of the App component:

Replace

1
2
<Text>Hello World</Text>
<Text>
  {age || 'Fetching config...'}
</Text>

with

1
2
return (
  <Text>
    {config.name} is {config.age} years old.
  </Text>
);

Your main file containing the application's root component (here index.jsx) should look like this:

1
2
import React from "react";
import ForgeReconciler, {
  Label,
  Textfield,
  Text,
  useConfig,
  SectionMessage,
} from "@forge/react";

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

// Function that defines the configuration UI for the pet's name and age
const Config = () => {
  return (
    <>
      <Label>Pet name</Label>
      <Textfield name="name" defaultValue={defaultConfig.name} />
      <Label>Pet age</Label>
      <Textfield name="age" defaultValue={defaultConfig.age} />
    </>
  );
};

const App = () => {
  const actualConfig = useConfig();
  const config = actualConfig || defaultConfig;
  // Displaying the pet's name and age using the configuration values. SectionMessage component is optional.
  return (
    <>
      <Text>
        {config.name} is {config.age} years old.
      </Text>
      <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>
    </>
  );
};

// Adding the Config function to the ForgeReconciler to allow for configuration changes
ForgeReconciler.render(
  <React.StrictMode>
    <App />
  </React.StrictMode>
);

ForgeReconciler.addConfig(<Config />);

Install your app

Build, deploy, and install the app to see it in your Confluence site.

To use your app, it must be installed onto an Atlassian site. The forge deploy command builds, compiles, and deploys your code; it'll also report any compilation errors. The forge install command then installs the deployed app onto an Atlassian site with the required API access.

1. Navigate to the app's top-level directory and deploy your app by running:

   1
   2
   forge deploy
   

2. Install your app by running:

   1
   2
   forge install
   

3. Select your Atlassian product using the arrow keys and press the enter key.

4. Enter the URL for your development site. For example, example.atlassian.net. View a list of your active sites at Atlassian administration.

Once the successful installation message appears, your app is installed and ready to use on the specified site. You can always delete your app from the site by running the forge uninstall command.

View your app

1. Edit a Confluence page in your development site.
2. Select from the toolbar.
3. Find the macro by name and select it. The app is displayed on the page.
4. Click the pencil icon to open the app's config panel on the right side of the page.
5. Type the Pet age, Pet name, and then close the configuration page. The config values are saved automatically.

You should now see the config values displayed within the app.