Your first quest - part I

This tutorial will walk you through creating a simple Forge app for Confluence using UI Kit 2.

In part I you will use the Forge CLI to create a forge app based on one of the many available templates, you will then customise the app and add a new module. You will also learn how to build and deploy the app, and install it onto your confluence developer test site.

In part II you will customise your app further by accessing application context data via both the front and back end. You will also learn how to automatically deploy the app, and troubleshoot the app using console logging.

Before you begin

Before you start creating your app, ensure you've prepared by completing the steps outlined in Preparing for your first quest.

If you have time, you may also want to review Essential Knowlege which will explain where to find all the essential forge knowledge, and more importantly where to go to ask for help if you get stuck.

Create your app

Create an app based on the Confluence macro template.

1. Navigate to the directory where you want to create the app. A new subdirectory with the app's name will be created there.

2. Create your app by running:

   1
   2
   forge create
   

3. Enter a name for your app (up to 50 characters). For example my-first-quest.

4. Select the UI kit 2 (Preview) category.

5. Select Confluence as the product using the arrow keys and press the enter key.

6. Select the confluence-space-page template.

7. Change to the app subdirectory to see the app files:

   1
   2
   cd my-first-quest
   

About the confluence-space-page template

The app we'll create will create a Confluence Space Page, which will appear as a link in the space navigation menu.

The confluence-space-page template uses Node.js and has the following structure:

1
2
.
├── README.md
├── manifest.yml
├── package-lock.json
├── package.json
└── src
  └── frontend // front-end code goes in this folder
    └── index.jsx
  └── resolvers // back-end code goes in this folder
    └── index.js
  └── index.js // this exports the resolver functions to the top level directory 

Lets have a look at these files and directories a little more closely:

• src/frontend/index.jsx: contains the application the user interacts with directly
• manifest.yml: contains the description of your app, including the name and ID of the app, the app permissions, and the modules the app uses. To learn more about the manifest.yml file, see Forge manifest documentation.
• package.json: contains the app’s Node.js metadata. See the Node documentation for more information.
• package-lock.json: Records the version of the app’s dependencies.
• README.md: contains information about the app. We recommend updating this as you change the behavior of the app.
• src/resolvers/index.js: contains the applications backend functions, the functions are then defined in index.js and can be invoked from the frontend using the UI bridge method. For more information, see Custom UI Resolver docs.
• index.js: Where you write the src/resolvers/index.js function definitions. For more information, see Custom UI Resolver docs.

Explore the manifest.yml

This app displays content in place of a Confluence page within a Confluence space. The app appears as a link in the space navigation menu, and the title of each module is used as the title of the link, with the app rendering inside the content area of Confluence.

1. In the app’s top-level directory, open the manifest.yml file.
2. Find the title entry under the confluence:spacePage module.
3. Change the value of title to <your name>'s first quest. For example, Charlie's first quest.

Your manifest.yml file should look like the following, with your values for the title and app ID:

1
2
modules:
  confluence:spacePage:
    - key: my-first-quest-hello-world-space-page
      resource: main
      resolver:
        function: resolver
      render: native
      title: Charlie's first quest
      route: hello-world
  function:
    - key: resolver
      handler: index.handler
resources:
  - key: main
    path: src/frontend/index.jsx
app:
  id: '<your app id>'

Deploy and install your app

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

1. Install your app by running:

1
2
forge install

1. Select confluence using the arrow keys and press the enter key.
2. Enter the URL for your Atlassian development site. For example example.atlassian.net. You can view a list of your active sites at Atlassian administration

Once the install complete message appears, your app is installed and ready to use on the site spevccified. You can delete your app from the site by running the forge uninstall command.

About updating your app installation after changes

Once your app is installed, it will automatically pick up all minor app deployments so you don't need to run forge install every time you make a change. Minor deployments are changes that don't modify the app permissions in the manifest.yml file.
To deploy minor changes to your developer site, or bitbucket workspace run the forge deploy command. The Forge CLI will also detect if a change has been made to your app to modify the apps permissions, and will direct you to update your app installation using the forge install --upgrade command.

View your app

Now that your app is installed, it's time to see it in action in your Confluence site.

1. Open your confluence site (example.atlassian.com/wiki) and click on the Spaces menu to view a list of spaces.
2. Click on any space in the list to navigate to that space.
3. At the bottom of the Space navigation menu on the left, click on the link for your app under the APPS heading.
4. Your app will load in the content area on the right side.

Change how your app looks

In this section, you'll make some changes to the src/frontend/index.jsx to change the appearance of your app by using an additional UI Kit 2 component.

1. Navigate to the src/frontend directory.

2. Open the index.jsx file. The default content of the file is shown below:

   1
   2
   import React, { useEffect, useState } from 'react';
   import ForgeReconciler, { Text } from '@forge/react';
   import { invoke } from '@forge/bridge';
   
   const App = () => {
     const [data, setData] = useState(null);
   
     useEffect(() => {
       invoke('getText', { example: 'my-invoke-variable' }).then(setData);
     }, []);
   
     return (
       <>
         <Text>Hello world!</Text>
         <Text>{data ? data : 'Loading...'}</Text>
       </>
     );
   };
   
   ForgeReconciler.render(
     <React.StrictMode>
       <App />
     </React.StrictMode>
   );
   

3. Modify the import statement on line 3 of index.jsx to import the heading component,

   1
   2
   import ForgeReconciler, { Heading, Text } from '@forge/react';
   

4. Modify the App return statement to use the <Heading> tags instead of the <Text> tags on line 14, so that Hello world! displays as a medium sized heading,

   1
   2
   <Heading size="medium">Hello world!</Heading>
   

   To learn more about the Heading component, you can consult the Forge UI Kit 2 reference docs at https://developer.atlassian.com/platform/forge/ui-kit-2/heading/

5. Save the changes you made to index.jsx.

6. Navigate back to the app's top-level directory, and deploy your changes by running:

   1
   2
   forge deploy
   

7. Once the deployment is complete, refresh your app's space page in confluence to see the changes.

Next step

In the next part of this quest you will customise your app further by accessing application context data via both the front and back end. You will also learn how to automatically deploy your app, and troubleshoot it using console logging.

Continue to Part II