Build a book management app with Forge.

Photo by Iñaki del Olmo on Unsplash

Introduction

In this tutorial, you will build a Forge application that works on the Confluence page. You will learn how to use the Forge UI Kit to create user interfaces and learn how to use the Storage API to store information.

What is Forge?

If you are new to Atlassian products you might be asking “what is Forge?”. Forge is an app development platform designed to revolutionize how Atlassian cloud products are customized, extended, and integrated. Atlassian announced Forge at the beginning of 2020. With Forge, you don’t need to have your own infrastructure for building Atlassian applications.

Tutorial Key Concepts

This tutorial will cover the following key concepts:

• How to build UI with Forge UI KIT
• How to manage information with the Forge Storage API

What You’ll Build

This tutorial will guide you in a step-by-step process to create a book management application with Forge. By the end of the tutorial, we should have an application running on a Confluence page that is able to save, read, update and delete book information.

Book Management Forge Application

Getting Started

Before you begin building the book management application you need to set up your development environment, to do that follow this quick Getting started guide before working through this tutorial.

Create your app

Navigate to the directory where you want to create the app. A new subdirectory with the app’s name will be created there. Create your app by running:

forge create

1. Enter a name for your app as forge-app-crud.
2. Select the UI kit category.
3. Select the confluence-macro template.
4. Change to the app subdirectory to see the app files:

cd forge-app-crud

Install your app

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

forge deploy

2. Install your app by running:

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.

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.

With your app installed, it’s time to see the app on a page.

1. Edit a Confluence page on your development site.
2. Open the quick insert menu by typing /your macro title on the page. Once you start typing the title /Forge app for, the macro with your name will appear in the quick insert menu.
3. Select your macro from the menu to add it to the page.
4. Publish the page.

Your hello world app is now installed on your development site. The app should display on the page like the image below.

Building UI with UI Kit

Once your Forge application has been installed we can start witing some code first let’s create 2 files in the src directory BooksTable.jsx and BookDialog.jsx. Your directory should look like this:

Added 2 files

Open BooksTable.jsx and add the following code:

In the code above we have created a component called BooksTable that returns Forge UI components, we have Buttons to add, edit, delete Books and a Table to display book information.

Next, open the BookDialog.jsx file and add the following code:

From the code above we have created a component called BookDialog that returns a ModalDialog with a Form. In the onSubmit function, we save the book information from the form to the books array.

Next open index.jsx and add the following code:

In the code above we import BooksTable and BookDialog into the index file, we then create the isOpenModal state to keep track of the modal and the books array to store our book information.

Next run forge deploy in your terminal to deploy your changes, once deployment completes refresh your Confluence page and you should see an empty table.

Empty table

Next click the Add Book button, you should see a modal open with a form.

Add book modal

Enter some book information in the text field and hit the submit button, you should see the table gets populated with the information you entered.

Updated table

Currently, we are able to save the information to an array, However, this information is not persisted when we refresh the page the information will be lost. This brings us to the next part of this tutorial.

Managing Information with the Storage API

The app Storage API is an untyped key-value storage API that allows your app to store data. The app storage API stores data partitioned by Atlassian product and site and is accessible only to your app.

To use the Storage API you first need to install forge/api, in the root directory of your app run the following command.

npm i @forge/api

Next, we will need to install an npm package called uuid-random this will allow us to generate a unique key for each book we save in our Storage API.

npm i uuid-random

Setting up the Storage API

The App storage API requires your app to have the storage:app scope. App scopes must be defined in the manifest file prior to deploying the app. Navigate to the top-level directory of your app, open the manifest.yml file and add the following code.

Changes to the app’s scopes won’t take effect until the app is upgraded. If you’ve previously deployed your app, and you change the scopes in your manifest file, you also need to redeploy your app before installing it. To do that navigate to your app’s top-level directory and run:

forge deploy

Start the upgrade by running:

forge install — upgrade

Once the upgrade completes we are ready to start using the App Storage API!

Saving information to the Storage API

Now that our Storage API is all set up we are going to save a new book to the Storage API using the storage.set method. Open BookDialog.jsxand update the code like this:

From the updated code above we have imported storage and uuid, storage.set on line 8 is used to save the book information from the form to the Storage API and on line 7 we create a book ID using uuid and pass it to the storage.set method.

Next, let’s update BooksTable.jsxwith the following code:

From the code above we have imported storage and startsWith from @forge/api. The startsWith method allows us to find keys that start with a specific string, in our app all the book IDs start with “book_”. On line 18 we have a useEffect hook that runs the storage.query method, this enables you to query the app storage API and returns filtered results. On line 23 we set the returned results in the setBooks state, lastly from lines 54 to 63 we update the code by adding value before each attribute.

Next, let’s update the index.jsx file like this:

We have just cleaned up the code a bit, next run:

forge deploy

On your Confluence page, you should see that after adding a new book and refreshing the page the information is persisted.

Updating information

Now let’s see how we can update the book information, when the user clicks the update button a dialog should open with the selected book information filled in. First let’s add two states to the index.jsx file like this:

Next, in the index.jsx file update the props with the states we just created like this:

Next open BooksTable.jsx and update the code like this:

From the code above we have included the props we passed down from index.js on lines 18 & 19. On line 38 we set isUpdating to false when the user clicks the add book button, on line 80 we set isUpdating to true when the user clicks the update button, we also set setSelectedBook with the current book information.

Next open BookDialog.jsx add update the code like this:

From lines 12 to 17 in the code above we first check the value of isUpdating, it is true we use the selected book’s id as the bookID otherwise we create a new bookID. Finally on lines 31 to 49 we set the default value of each field to the selected book’s information if isUpdating is true. Now lets run :

forge deploy

Go back to your Confluence page and refresh it, when you click the edit button you should see a modal with information of the selected book already filled in.

Update Modal

If you change any of the text and click submit you should see that the book is updated in the table.

Deleting Books

Now let’s see how we can delete a book, when the user clicks the delete button the book should be removed from the App Storage API and from the table. First open BooksTable.jsx and update the delete button like this:

From the code above we have added an onClick listener that calls the storage.delete method to delete the current book from the Storage API and on line 10 we update the setBooks state.

That’s it! if you click a delete button you should see that the book is deleted.

Learning Resources

Looking for more ways to develop your Forge skills Check out the official Forge Tutorials you can also take a look at some example apps built with forge.

Thanks for reading! Happy coding!