Framework overview
Building blocks
Design guidelines
Security for Connect apps
Modules
JavaScript API
Last updated Jan 27, 2025

Atlassian timeline for ending Connect support

Navigator

The Navigator API enables your add-on to change the page displayed using JavaScript.

Methods

getLocation (callback)

Returns the context of the current page within the host application.

This method will provide a context object to the passed in callback. This context object will contain information about the page currently open in the host application.

The object will contain a target, which can be used when calling the go method, and a context map containing in formation about the opened page.

Currently this method supports two contexts in Confluence only:

  • contentview: The host application is currently viewing a page, blog post or other content.

  • contentedit: the host application is currently editing a page, blog post or other content.

Parameters

NameTypeDescription
callback

function

function (location) {...}

Example

1
2
AP.navigator.getLocation(function (location) {
  console.log(location)
  // location will be:
  // {
  //   "target": "contentview",
  //   "context": {
  //     "contentId": 1234,
  //     "contentType": "page",
  //     "spaceKey": "DS"
  //   }
  // }
});

go (target, context)

Navigates the user from the current page to the specified page. This call navigates the host product, not the iframe content.

Requires a target location and the corresponding context. Navigating by passing a concrete url is currently unsupported.

Parameters

NameTypeDescription
targetNavigator~target~Jira || Navigator~target~Confluence

The type of page to navigate to.

contextNavigator~context

Specific information that identifies the page to navigate to.

Example

1
2
// To navigate to the view page for a piece of content in Confluence:
AP.navigator.go('contentview', {contentId: '12345'});

// To navigate to the view page for version 2 of a piece of content in Confluence:
AP.navigator.go('contentview', {contentId: '12345', versionOverride: 2});

// To navigate to the edit page for a piece of content in Confluence:
AP.navigator.go('contentedit', {contentId: '12345'});

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

// To navigate to any page in the current site:
AP.navigator.go('site', {
  relativeUrl: '/browse/TEST-1'
});

reload()

Triggers a reload of the parent page.

Throttle is applied to prevent infinite reloads

Example

1
2
AP.navigator.reload();

Types

Defines the available navigation targets for Confluence.

Properties

Name Type Description

contentview

String

The view page for pages, blogs and custom content. Takes a contentId to identify the content.

contentedit

String

The edit page for pages, blogs and custom content. Takes a contentId to identify the content.

spaceview

String

The space view page. Takes a spaceKey to identify the space.

spacetools

String

The space tools page. Takes a spaceKey to identify the space.

dashboard

String

The dashboard of Confluence.

userProfile

String

The profile page for a specific user. Takes a username or userAccountId to identify the user.

addonModule

String

The module page within a specific add-on. Takes an addonKey and a moduleKey to identify the correct module.

contentlist

String

The list/collector page for pages, blogs and custom content contained in a space. Takes a spaceKey and a contentType to identify the content type.

site

String

A specific location contained within a site. Takes a relativeUrl to identify the path.

Defines the available navigation targets for Jira.

Properties

Name Type Description

dashboard

String

A dashboard in Jira. Takes a dashboardId to identify the dashboard.

issue

String

An issue in Jira. Takes an issueKey to identify the issue.

addonModule

String

A module page within an add-on. Takes an addonKey and a moduleKey to identify the module.

userProfile

String

The profile page for a Jira User. Takes a userAccountId to identify the user.

projectAdminSummary

String

The admin details of a Jira project. Takes a projectKey to identify the project. Only accessible to administrators.

projectAdminTabPanel

String

The admin panel defined by a connect addon. Takes an addonKey, adminPageKey, projectKey, and projectId. Only accessible to administrators.

site

String

A location in the site. Takes either a relativeUrl or absoluteUrl to identify the path.

Defines the context information required for navigation targets.

Properties

Name Type Description

contentId

String

Identifies a piece of content. Required for the contentView target.

contentType

String

Identifies the type of content. Can be either page or blogpost. Required for the contentEdit target.

spaceKey

String

Identifies a space. Required for the spaceView and spaceTools targets.

username

String

Identifies a user. One of this or userAccountId required for the userProfile target.

userAccountId

String

Identifies a user. One of this or username required for the userProfile target.

addonKey

String

Identifies a connect add-on. Required for the addonModule and projectAdminTabPanel targets.

moduleKey

String

Identifies a connect add-on module. Required for the addonModule target.

dashboardId

String

Identifies a Jira dashboard. Required for the dashboard target in Jira.

projectKey

String

Identifies a Jira project. Required for the projectSummary, projectAdminSummary and projectAdminTabPanel targets.

issueKey

String

Identifies a Jira issue. Required for the issue target.

adminPageKey

String

Identifies a Jira Project Admin Tab Panels module key. Required for the projectAdminTabPanel target.

projectId

String

Identifies a Jira Project by its ID number. Required for the projectAdminTabPanel target.

customData

String

Contains parameters that will be added as query parameters to the product url with "ac." prepended. Used only in addonModule target. See Add-on specific context parameters for more info.

embeddedContentRender

String

Identifies the mode for rendering embedded content in Confluence, such as attachments embedded in a page. This only applies to the contentView target. Valid values are current (render the embedded content using the latest version) and version-at-save (render the embedded content using the version at the time the content was saved). This parameter is optional and defaults to current.

relativeUrl

String

Identifies a specific page within a site. Required for the site target and must begin with /.

absoluteUrl

String

Identifies a specific page within a site. Required for the site target and must be within the site's domain.


Rate this page: