Rate this page:
This tutorial describes how to create a Forge app that displays the number of macros in a Confluence page. The app retrieves the body of the page, counts the number of macros, then displays the result in a modal dialog. A user triggers the action from an entry in the more actions (...) menu.
The final app looks like the following:
This tutorial assumes you're already familiar with developing on Forge. If this is your first time using Forge, see Getting started for step-by-step instructions on setting up Forge.
To complete this tutorial, you need the following:
npm install -g @forge/cli@latest
on the command line.npm install @forge/ui@latest --save
on the command line.The app retrieves the body of the page, counts the number of macros, then displays the result in a modal dialog.
1 2forge create
To register the functionality of your app, add confluence:contentAction
and function
modules to
the manifest. The confluence:contentAction
module adds an entry to the more actions (...) menu,
with the value of title
. The function
module contains the logic to count and display the number
of macros.
manifest.yml
file.macro
entry under modules
with the following confluence:contentAction
.
1 2confluence:contentAction: - key: macro-counter title: Macro count function: main
Your manifest.yml
should look like the following, with your value for the app ID:
1 2modules: confluence:contentAction: - key: macro-counter title: Macro count function: main function: - key: main handler: index.run app: id: '<your-app-id>'
Build, deploy, and install the app to see it in your Confluence site.
Navigate to the app's top-level directory and deploy your app by running:
1 2forge deploy
Install your app by running:
1 2forge install
Select your Atlassian product using the arrow keys and press the enter key.
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.
Running the forge install
command only installs your app onto the selected product.
To install onto multiple products, repeat these steps again, selecting another product each time.
Note that the Atlassian Marketplace
does not support cross-product apps yet.
You must run forge deploy
before running forge install
in any of the Forge environments.
With the app installed, it's time to see the entry in the more actions (...) menu.
You'll see the Count macros entry from the app.
If you select the menu item, the following error displays because you haven't implemented the app logic yet. You'll do this in the next step.
1 2You must have a <ContentAction> at the root.
Add the UI kit components that render when a user views the app. You'll use a static value for the number of macros in the page.
In terminal, navigate to the app's top-level directory and install the runtime API package by running:
1 2npm install @forge/api
Start tunneling to view your local changes by running:
1 2forge tunnel
Open the src/index.jsx
file.
Replace the contents of the file with:
1 2// Import required components from the UI kit import ForgeUI, { ContentAction, ModalDialog, render, Text, useAction, useProductContext, useState } from "@forge/ui"; import api, { route } from "@forge/api"; // You'll implement getContent and countMacros later const getContent = async (contentId) => { return {}; }; const countMacros = (data) => { return 10; }; const App = () => { const [isOpen, setOpen] = useState(true); if (!isOpen) { return null; } const { contentId } = useProductContext(); const [data] = useAction( () => null, async () => await getContent(contentId) ); const macroCount = countMacros(data); return ( <ModalDialog header="Macro count" onClose={() => setOpen(false)}> <Text>{`Number of macros on this page: ${macroCount}`}</Text> </ModalDialog> ); }; export const run = render( <ContentAction> <App/> </ContentAction> );
Refresh a Confluence page on your site, open the more actions (...) menu, and select Count macros.
A modal dialog displays with:
1 2Number of macros on this page: 10
In the code from this step:
isOpen
keeps the state of ModalDialog
, setOpen
is called when the ModalDialog
closes.useAction
awaits the asynchronous getContent
function to complete. See
UI kit hooks to learn more about useState
, useAction
,
and useProductContext
.getContent
function gets the contents of a page from Confluence.countMacros
function returns the number of macros in the page. At this stage, the function
always returns 10.ModalDialog
displays the number of macros in the page.run
constant provides the mechanism that renders the app.Turn the static app into a dynamic app by making an API call to Confluence to retrieve the contents of the page.
src/index.jsx
file.getContent
function with:
1 2const getContent = async (contentId) => { const response = await api.asUser().requestConfluence(route`/wiki/rest/api/content/${contentId}?expand=body.atlas_doc_format`); if (!response.ok) { const err = `Error while getContent with contentId ${contentId}: ${response.status} ${response.statusText}`; console.error(err); throw new Error(err); } return await response.json(); };
countMacros
function with:
1 2const countMacros = (data) => { if (!data || !data.body || !data.body.atlas_doc_format || !data.body.atlas_doc_format.value) { return 0; } const { body: { atlas_doc_format: { value } } } = data; const { content: contentList } = JSON.parse(value); const macros = contentList.filter((content) => { return content.type = "extension"; }); return macros.length; };
Edit the page to add macros and select Count macros again to see the number update.
After confirming the app works locally, deploy the app so that it continues to work when you close the tunnel.
1 2forge deploy
That’s it. You've built an app that retrieves the contents of a page, counts the number of macros, then displays the result in a modal dialog.
Check out an example app, continue to one of the other tutorials, or read through the reference pages to learn more.
Rate this page: