Rate this page:
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.
To create the app, you'll learn how to:
InlineDialog
view when the user selects the app from the dropdown.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:
npm install -g @forge/cli@latest
on the command line.npm install @forge/ui@latest --save
on the command line.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:
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:
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 an app starting from the macro template.
Navigate to the directory where you want to create the app.
Create an app by running:
1 2forge create
Open the app directory to see the app files.
This app uses a confluence:contextMenu
module. All apps that use this module appear in the dropdown
in the context menu.
manifest.yml
file.macro
entry under modules
with the following confluence:contextMenu
.
1 2confluence: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 2modules: 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 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, you can see the new entry in the context 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 2You must have a <ContextMenu> at the root.
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.
In terminal, navigate to the app's top-level directory and start tunneling to view your local changes by running:
1 2forge tunnel
Open the src/index.jsx
file.
Replace the content of the file with:
1 2import 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> );
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.
In the code from this step:
App
component renders the InlineDialog
with selected text.
selectedText
is retrieved from useProductContext
.Text
UI kit component displays the selected text inside the InlineDialog
.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.
After confirming the app works locally, deploy the app so that it continues to work when you close the tunnel.
1 2forge deploy
Now you know how to build a simple Forge app using the confluence:contextMenu
module.
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: