Rate this page:
This tutorial describes how to create a Forge app with two modules, where an admin can create
news content using spaceSettings
module, and make the news content available using contentBylineItem
.
The final spaceSettings
module looks like the following:
The final contentBylineItem
module 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.Create an app based on the confluence-macro template.
1 2forge create
To register the functionality of your app, add confluence:spaceSettings
and function
modules to
the manifest.
The confluence:spaceSettings
module adds a tab inside the integration settings of a Confluence space.
The function
modules contains the implementation of space settings and content byline items modules.
manifest.yml
file.macro
entry under modules
with the following confluence:spaceSettings
.
1 2confluence:spaceSettings: - key: forge-space-news function: main title: Space news
Your manifest.yml
should look like the following, with your value for the app ID:
yaml modules: confluence:spaceSettings: - key: forge-space-news function: main title: Space news 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 Space Settings.
You'll see the Space news tab 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 <SpaceSettings> at the root.
@forge/ui-confluence
and
@forge/ui@latest
packages by running:
1 2npm install @forge/ui-confluence @forge/ui@latest --save
1 2forge tunnel
src/index.jsx
file.1 2// Import required components from the UI kit import ForgeUI, { render, Form, Fragment, SpaceSettings, TextArea } from "@forge/ui"; import { useSpaceProperty } from "@forge/ui-confluence"; const App = () => { const [news, setNews] = useSpaceProperty("space-news", "No news currently."); return ( <Fragment> <Form onSubmit={async (formData) => { await setNews(formData.news) }}> <TextArea name="news" label="News" defaultValue={news}/> </Form> </Fragment> ); }; export const run = render( <SpaceSettings> <App /> </SpaceSettings> );
In the code from this step:
TextArea
provides a text area input control. It's used to collect the news entry.Form
contains the TextArea
component. It also has onSubmit
property.
onSubmit
is called with form data when a user presses the submit button.run
constant provides the mechanism that renders the app.To add more functionality to your app, add confluence:contentBylineItem
.
The confluence:contentBylineItem
module displays Forge apps in the content byline section
(the area under the page title) of a Confluence page.
manifest.yml
file.modules
after confluence:spaceSettings
with the following
confluence:contentBylineItem
.
1 2confluence:contentBylineItem: - key: forge-space-news-byline function: byline title: Space news tooltip: Displays recent space news
function
.
1 2- key: byline handler: byline.run
Your manifest.yml
should look like the following, with your value for the app ID:
1 2modules: confluence:spaceSettings: - key: forge-space-news function: settings title: Space news confluence:contentBylineItem: - key: forge-space-news-byline function: byline title: Space news tooltip: Displays recent space news function: - key: settings handler: index.run - key: byline handler: byline.run app: id: '<your-app-id>'
src/byline.jsx
file.1 2// Import required components from the UI kit import ForgeUI, { render, Text, InlineDialog, ContentBylineItem } from "@forge/ui"; import { useSpaceProperty } from "@forge/ui-confluence"; const App = () => { const [news] = useSpaceProperty("space-news", "No news currently."); return ( <InlineDialog> <Text>{news}</Text> </InlineDialog> ); }; export const run = render( <ContentBylineItem> <App /> </ContentBylineItem> );
In the code from this step:
InlineDialog
renders an inline dialog when a user clicks the Space news byline item.Text
displays the news text set by admin.run
constant provides the mechanism that renders the app.Build and deploy the app to see it in your Confluence site. The app needs to be redeployed after a manifest change.
Stop tunneling by pressing:
1 2Control + C
Deploy your app by running:
1 2forge deploy
With the app deployed again, it's time to see the entry in Content Byline Item. Navigate to your Confluence Cloud site, then open a page. You'll see the Space news entry from the app.
Congratulations! You've created a forge app with two modules that:
Check out an example app, continue to one of the other tutorials, or read through the reference pages to learn more.
Rate this page: