Last updated Sep 30, 2021

Use highlighted text in a Confluence Forge app

This tutorial describes how to make a Forge app that uses highlighted text from a Confluence page. You might use this technique in a dictionary app, a custom glossary, or any app that requires users to highlight text on a page.

Confluence context menu

To create the app, you'll learn how to:

  • Use the confluence:contextMenu module to add an item to the context menu dropdown, which appears when users highlight text on a published page.
  • Send the highlighted text to a InlineDialog view when the user selects the app from the dropdown.

Before you begin

This tutorial assumes you're already familiar with the basics of Forge development. If this is your first time using Forge, see Getting started first.

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.
  • The latest version of the UI kit. To update your version, navigate to the app's top-level directory, and run npm install @forge/ui@latest --save on the command line.

Set up a cloud developer site

An Atlassian cloud developer site lets you install and test your app on Confluence and Jira products set up for you. If you don't have one yet, set it up now:

  1. Go to http://go.atlassian.com/cloud-dev and create a site using the email address associated with your Atlassian account.
  2. Once your site is ready, log in and complete the setup wizard.

You can install your app to multiple Atlassian sites. However, app data won't be shared between separate Atlassian sites, products, or Forge environments.

The limits on the numbers of users you can create are as follows:

  • Confluence: 5 users
  • Jira Service Management: 1 agent
  • Jira Software and Jira Work Management: 5 users

The Atlassian Marketplace doesn't currently support cross-product apps. If your app supports multiple products, you can publish two separate listings on the Marketplace, but your app won't be able to make API calls across different products and instances/installations.

Create your app

Create an app starting from the macro template.

  1. Navigate to the directory where you want to create the app.

  2. Create an app by running:

    1
    2
    forge create
    
    1. Enter a name for the app. For example, show-selected-text.
    2. Select the UI Kit category from the list.
    3. Select the Confluence product from the list.
    4. Select the confluence-macro template from the list.
  3. Open the app directory to see the app files.

Update the manifest

This app uses a confluence:contextMenu module. All apps that use this module appear in the dropdown in the context menu.

  1. In the app's top-level directory, open the manifest.yml file.
  2. Replace the macro entry under modules with the following confluence:contextMenu.
    1
    2
    confluence:contextMenu:
     - key: show-selected-text
       function: main
       title: Show selected text
       description: Simple app that shows selected text
    

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

1
2
modules:
  confluence:contextMenu:
    - key: show-selected-text
      function: main
      title: Show selected text
      description: Simple app that shows selected text
  function:
    - key: main
      handler: index.run
app:
  id: '<your-app-id>'

See Manifest to learn more about the manifest file.

Build, deploy, and install

Build, deploy, and install the app to see it in your Confluence site.

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

    1
    2
    forge deploy
    
  2. Install your app by running:

    1
    2
    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. 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

With the app installed, you can see the new entry in the context menu.

  1. Navigate to a page on your Confluence Cloud site.
  2. Select any text on the page. The context menu should appear.
  3. Open the dropdown menu.

You'll see the Show selected text item.

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 <ContextMenu> at the root.

Implement the front end

Add UI elements that render when the app is called (when the user clicks on the menu item). You'll use the useProductContext UI kit hook to get information about the selected text.

  1. In terminal, navigate to the app's top-level directory and start tunneling to view your local changes by running:

    1
    2
    forge tunnel
    
  2. Open the src/index.jsx file.

  3. Replace the content of the file with:

    1
    2
    import ForgeUI, { render, ContextMenu, InlineDialog, Text, Strong, useProductContext } from '@forge/ui';
    
    const App = () => {
      const { extensionContext: { selectedText } } = useProductContext();
    
      return (
        <InlineDialog>
          <Text><Strong>Selected text</Strong></Text>
          <Text>{selectedText}</Text>
        </InlineDialog>
      );
    };
    
    export const run = render(
      <ContextMenu><App/></ContextMenu>
    );
    
  4. Open a Confluence page and select some text. When the context menu appears, click the dropdown button and select Show selected text.

    An inline dialog displays the text you selected.

    Inline Dialog with selected text

    In the code from this step:

    • The import statement lists the components and hooks that are used in the app. See UI kit components and UI kit hooks for more information.
    • The App component renders the InlineDialog with selected text.
      • The const selectedText is retrieved from useProductContext.
      • The Text UI kit component displays the selected text inside the InlineDialog.
    • The export of the run constant renders the App component, wrapped with ContextMenu.

The context menu module should follow these conventions:

  • The ContextMenu UI kit component should be the top-level component for the render function.

  • The next component after ContextMenu in the tree should be the InlineDialog UI kit component.

Close the tunnel and deploy the app

After confirming the app works locally, deploy the app so that it continues to work when you close the tunnel.

  1. Close your tunnel by pressing Ctrl+C.
  2. Deploy your app by running:
    1
    2
    forge deploy
    

Now you know how to build a simple Forge app using the confluence:contextMenu module.

Next steps

Take a look at a full Dictionary example app that uses a similar technique, or review other documentation for more on how Forge works:

Rate this page: