router

The router object enables you to navigate the host product to another page. router supports three methods:

1. navigate, which navigates to the page in the same tab.
2. open, which opens the page in a new tab or window, depending on the user’s browser configuration.
3. reload, which reloads the current page.

For navigate and open, there are two ways to declare the target page:

1. Pass a NavigationLocation (Preview), consisting of the target location and the corresponding properties.
2. Pass a URL directly.

Passing a NavigationLocation (Preview) object enables navigation with contextual and more human-readable data, rather than using a URL. For a list of supported target locations, see Target locations and properties.

navigate

The navigate method allows you to navigate to a page in the same tab.

Function signature

1
2
function navigate(url: string | location: NavigationLocation): Promise<void>;

The shape of NavigationLocation (Preview) will vary according to the target location. Required properties for each target location are defined in Target locations and properties.

If you’re using a URL to link to an external site, the user is prompted before opening the link in a new tab. If the user declines to proceed, the returned Promise is rejected. If you’re using relative URLs (starts with /), the user won’t be prompted.

Example

1
2
import { router, NavigationTarget } from '@forge/bridge';

// To navigate to the view page for a piece of content in Confluence:
router.navigate({target: 'contentView', contentId: '12345'});

// To navigate to the view page for version 2 of a piece of content in Confluence:
router.navigate({target: 'contentView', contentId: '12345', version: 2});

// To navigate to the edit page for a piece of content in Confluence:
router.navigate({target: 'contentEdit', contentId: '12345'});

// To navigate to the page of the given module key:
router.navigate({target: 'module', moduleKey: 'my-global-page'});

// To navigate to the issue view page of an issue in Jira:
router.navigate({target: 'issue', issueKey: 'TEST-1'});

// Alternatively, `NavigationTarget` can be imported and used for improved IDE autocompletion and documentation support:
router.navigate({target: NavigationTarget.Issue, issueKey: 'TEST-1'});

open

The open method allows you to open a page in a new tab or window, depending on the user’s browser configuration.

Function signature

1
2
function open(url: string | location: NavigationLocation): Promise<void>;

The shape of NavigationLocation (Preview) will vary according to the target location. Required properties for each target location are defined in Target locations and properties.

If you’re using a URL to link to an external site, the user is prompted before opening the link in a new tab. If the user declines to proceed, the returned Promise is rejected. If you’re using relative URLs (starts with /), the user won’t be prompted.

Example

1
2
import { router, NavigationTarget } from '@forge/bridge';

// Opens the view page for a piece of content in Confluence in a new tab or window:
router.open({target: 'contentView', contentId: '12345'});

// Opens the issue view page of an issue in Jira in a new tab or window:
router.open({target: 'issue', issueKey: 'TEST-1'});

// Alternatively, `NavigationTarget` can be imported and used for improved IDE autocompletion and documentation support:
router.open({target: NavigationTarget.Issue, issueKey: 'TEST-1'});

reload

The reload method allows you to reload the host window.

Function signature

1
2
function reload(): Promise<void>;

Example

1
2
import { router } from '@forge/bridge';

router.reload();

Target locations and properties

A NavigationLocation is a specific target within Confluence, Jira, or directory that can be navigated to using the navigate or open methods. It consists of a target location and its corresponding properties, which are outlined below.

Confluence

contentView

The view page for pages, blogs, and custom content.

Example

To navigate to /wiki/pages/viewpage.action?pageId=238945&pageVersion=2:

1
2
router.navigate({target: 'contentView', contentId: '238945', version: 2});

contentEdit

The edit page for pages, blogs, and custom content.

Example

To navigate to /wiki/spaces/${spaceKey}/pages/edit-v2/238945:

1
2
router.navigate({target: 'contentEdit', contentId: '238945'});

spaceView

The space view page.

Example

To navigate to /wiki/spaces/TEAM:

1
2
router.navigate({target: 'spaceView', spaceKey: 'TEAM'});

contentList

The list page for pages, blogs, and custom content in a space.

Example 1

To navigate to /wiki/spaces/TEAM/pages:

1
2
router.navigate({target: 'contentList', contentType: 'page', spaceKey: 'TEAM'});

Example 2

To navigate to /wiki/search?type=forge:${appId}:${environmentId}:my-custom-content-module:

1
2
router.navigate({target: 'contentList', contentType: 'customContent', moduleKey: 'my-custom-content-module'});

module

The page containing the supported module. Supported Confluence modules:

• Global page
• Global settings page
• Space page
• Space settings page

Example

To navigate to /wiki/apps/${appId}/${environmentId}/${route}:

1
2
router.navigate({target: 'module', moduleKey: 'my-global-page'});

Jira

dashboard

A dashboard in Jira.

Example

To navigate to /jira/dashboards/10000:

1
2
router.navigate({target: 'dashboard', dashboardId: '10000'});

issue

An issue in Jira.

Example

To navigate to /browse/FT-3:

1
2
router.navigate({target: 'issue', issueKey: 'FT-3'});

projectSettingsDetails

The details of a Jira project. Only accessible to administrators.

Example

To navigate to /jira/software/projects/FT/settings/details:

1
2
router.navigate({target: 'projectSettingsDetails', projectKey: 'FT'});

module

The page containing the supported module. Supported Jira modules:

• Admin page
• Global page
• Project page
• Personal settings page
• Project settings page

Example

To navigate to /jira/settings/apps/${appId}/${environmentId}:

1
2
router.navigate({target: 'module', moduleKey: 'my-admin-page'});

Directory

userProfile

The profile page for a specific user.

Example

To navigate to /people/12345:

1
2
router.navigate({target: 'userProfile', accountId: '12345'});