Last updated Apr 3, 2024

view

The view object refers to the context in which a resource is loaded. For example, a modal.

close

The close method enables you to request the closure of the current view. For example, close a modal.

Function signature

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

Example

1
2
import { view } from "@forge/bridge";

view.close();

submit

The submit method enables you to request form submission on the Jira custom field edit, Jira custom field type edit, and Jira context configuration views.

The submit method throws an error if the submission fails.

Function signature

1
2
function submit(payload: mixed): Promise<void>;

Where the payload shape is defined by the requirements of the views.

Example

This example shows how to request form submission on a Jira custom field edit.

1
2
import { view } from "@forge/bridge";

const onSubmit = async () => {
  const fieldValue = "new-value";
  try {
    return await view.submit(fieldValue);
  } catch (e) {
    // Handle the error
  }
};

getContext

The getContext method enables you to retrieve contextual information for your custom UI app.

Function signature

1
2
function getContext(): Promise<Context>;

interface Context {
  accountId?: string;
  cloudId?: string;
  workspaceId?: string;
  extension: ExtensionData;
  license?: LicenseDetails;
  localId: string;
  locale: string;
  moduleKey: string;
  siteUrl: string;
  timezone: string;
}

interface ExtensionData {
  [k: string]: any;
}

interface LicenseDetails {
  active: boolean;
  billingPeriod: string;
  ccpEntitlementId: string;
  ccpEntitlementSlug: string;
  isEvaluation: boolean;
  subscriptionEndDate: string | null;
  supportEntitlementNumber: string | null;
  trialEndDate: string | null;
  type: string;
}

Returns

Context: An object containing contextual information about the current environment in which the app is running. The data available depends on the module in which your app is used.
- accountId: The Atlassian ID of the user that interacted with the app.
- cloudId: The ID identifying the cloud context of this app installation.
- workspaceId: The ID identifying the workspace context of this app installation.
- license: Contains information about the license of the app. Note: this field is only present for paid apps in the production environment. license is undefined for free apps, apps not listed on the Atlassian Marketplace, and apps in development and staging environments. See the LicenseDetails type for what information is available.
- localId: A unique ID for this instance of this app in the content.
- locale: The locale of the user that interacted with the app.
- moduleKey: The key for the module as defined in the manifest.yml file.
- siteUrl: The URL of the site of this app installation (e.g. https://example.atlassian.net).
- timezone: The timezone of the user that interacted with the app.

Example

1
2
import { view } from "@forge/bridge";

const context = await view.getContext();

There may be an extensionContext property in the context data. This extensionContext property is deprecated and will soon be removed. Use the extension property instead.
Not all of the values in the context data are guaranteed to be secure, unalterable, and valid to be used for authorization. See App context security for more information.

createHistory

The createHistory method enables your custom UI app to manipulate the current page URL for routing within full page apps.

When using this API, the path and location properties are always relative to your app's URL.

The createHistory method is only available in the jira:adminPage, jira:globalPage, jira:projectPage, jira:projectSettingsPage, confluence:globalPage, confluence:spacePage, confluence:spaceSettings, compass:adminPage, compass:componentPage, and compass:globalPage modules.

Learn how to add routing to a full page app with React Router.

Function signature

1
2
type LocationDescriptor = {
  pathname: string;
  search?: string;
  hash?: string;
  state?: any;
};
type UnlistenCallback = () => void;
type Action = "POP" | "PUSH" | "REPLACE";

function createHistory(): Promise<{
  action: Action;
  location: LocationDescriptor;
  push(path: string, state?: any): void;
  push(location: LocationDescriptor): void;
  replace(path: string, state?: any): void;
  replace(location: LocationDescriptor): void;
  go(n: number): void;
  goBack(): void;
  goForward(): void;
  listen(
    listener: (location: LocationDescriptor, action: Action) => void
  ): UnlistenCallback;
}>;

Example

1
2
import { view } from "@forge/bridge";

const history = await view.createHistory();

// e.g. URL begins as http://example.atlassian.net/example/apps/abc/123

history.push("/page-1");
// this updates the URL to http://example.atlassian.net/example/apps/abc/123/page-1

history.push("/page-2");
// this updates the URL to http://example.atlassian.net/example/apps/abc/123/page-2

history.go(-2);
// this updates the URL to http://example.atlassian.net/example/apps/abc/123

refresh

The refresh method enables you to fetch the data for the parent page again, without performing a full-page reload.

The refresh method is only available for certain Atlassian products. You will see the error this resource's view is not refreshable if the refresh method is not available.

At the moment, it can be used by the following modules:

Function signature

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

Example

1
2
import { view } from "@forge/bridge";

view.refresh();

theme

The theme object includes the method to enable theming. View the Design Tokens and Theming page for more details.

enable

The theme.enable method enables theming in the Forge app. This will fetch the current active theme from the host environment (e.g. Jira) and apply it in your app. It will also reactively apply theme changes that occur in the host environment so that your app and the host are always in sync.

Function signature

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

Example

1
2
import { view } from "@forge/bridge";

await view.theme.enable();