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;
  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.
  • extension: Provides information related to the Forge app extension point, such as the content ID of the page where the app is running, module type and so on.
  • 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();

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.

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.

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

• Jira issue action
• Jira issue activity
• Jira issue glance
• Jira issue context
• Jira issue panel

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();

changeWindowTitle

The changeWindowTitle method enables you to change the title of the current document in the following Jira modules: global page, admin page, project settings page, and project page.

Function signature

1
2
function changeWindowTitle(newTitle: string): Promise<void>;

Example

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

await view.changeWindowTitle('New title');