Use space settings and content byline item to implement space news

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: Space settings shows Space news app

The final contentBylineItem module looks like the following: Content byline item shows Space news app

Before you begin

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:

The latest version of Forge CLI. To update your CLI version, run npm install -g @forge/cli@latest on the command line.
An Atlassian cloud site with Confluence where you can install your app. You need to be an admin on the site to install the app.

Create your app

Create an app based on the confluence-macro template.

Navigate to the directory where you want to create the app.
Create your app by running:
```
1
2
forge create
```
Enter a name for the app. For example, space-news-tutorial.
Select the confluence-macro template from the list.
Open the app directory to see the app files.

Update the manifest with spaceSettings

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.

In the app's top-level directory, open the manifest.yml file.

Replace the macro entry under modules with the following confluence:spaceSettings.

1
2
confluence: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

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
2
forge deploy
```
Install your app by running:
```
1
2
forge 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.

View the app under space settings

With the app installed, it's time to see the entry in Space Settings.

Navigate to your Confluence Cloud site.
Select your favorite space.
Click Space Settings from the left navigation.
Click the Integrations tab.

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
2
You must have a <SpaceSettings> at the root.

Implement space settings part of the app

In terminal, navigate to the app's top-level directory and install @forge/ui-confluence and @forge/ui@latest packages by running:

1
2
npm install @forge/ui-confluence @forge/ui@latest --save

Start tunneling to view your local changes by running:
```
1
2
forge 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, { 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>
);

Refresh Space news app.
You can type and submit a test news.

In the code from this step:

The import statement lists the components and hooks to use from the UI kit. See UI kit components to learn more about these components. See useSpaceProperty to learn more about it.
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.
Exporting the run constant provides the mechanism that renders the app.

Update the manifest with contentBylineItem

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.

In the app's top-level directory, open the manifest.yml file.

Add a new entry under modules after confluence:spaceSettings with the following confluence:contentBylineItem.

1
2
confluence:contentBylineItem:
  - key: forge-space-news-byline
    function: byline
    title: Space news
    tooltip: Displays recent space news

Add a new entry under function.

1
2
- key: byline
  handler: byline.run

Your manifest.yml should look like the following, with your value for the app ID:

1
2
modules:
  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>'

Implement content byline item part of the app

Create a new file src/byline.jsx file.

Replace the contents of the file with:

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:

The import statement lists the components and hooks to use from the UI kit. See UI kit components to learn more about these components. See useSpaceProperty to learn more about it.
InlineDialog renders an inline dialog when a user clicks the Space news byline item.
Text displays the news text set by admin.
Exporting the run constant provides the mechanism that renders the app.

Build and deploy

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
2
Control + C
```
Deploy your app by running:
```
1
2
forge deploy
```

View the app under content byline item

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:

Enables admins to create news content under space settings.
Enables users to consume the news content from any page in that space.

Next steps

Check out an example app, continue to one of the other tutorials, or read through the reference pages to learn more.

See Example apps for a collection of apps we've built.
See the Automate Jira using Triggers tutorial for information on using triggers to respond to user actions in Jira.
See the reference pages to learn what else you can do with what you’ve learned.