Skip to main content

Write fragment code

This page lists what your fragment code can use: the globals and the context each location passes. It also covers sizing, dark theme and errors. Gadgets and macros run the same way. Only their context differs.

Applies to: Script Master for Jira and Script Master for Confluence Β· Cloud

How the code runs​

Script Master puts the code from Frontend HTML + JavaScript into a frame in the location and runs it in the viewer's browser. Write it as a small HTML document: markup, styles in <style> or <link> tags, and JavaScript in <script> tags.

Use <script type="module"> so you can await the bridge calls at the top level.

Globals​

Every fragment, gadget and macro gets these globals. Use them directly, without an import or a window. prefix:

GlobalWhat it does
viewview.getContext() returns the context of the location. view.refresh() reloads the fragment
requestJiraCalls the Jira REST API as the viewer
requestConfluenceCalls the Confluence REST API as the viewer
showFlagShows a flag in Jira or Confluence
routerOpens or navigates to another page
eventsForge bridge events
ModalOpens a Forge modal
setHeightSets the frame's height. See Size the frame
themeThe viewer's theme. theme.colorMode is light or dark

All except setHeight and theme are the Forge bridge objects. See Forge bridge API for browser scripts.

The context of each location​

Call view.getContext() once at the start of the script. context isn't a global, so code that reads context.extension without this call fails.

const context = await view.getContext();
const workItemKey = context.extension.issue.key;

The fields you'll use most, by location:

LocationFields in context.extension
Work item panel, Work item actionissue.id, issue.key, issue.type, issue.typeId, project.id, project.key, project.type
Space page, Space settings page (Jira)project.id, project.key, project.type
Queue pageproject.id, project.key
Page action, Page byline itemcontent.id, content.type, space.id, space.key
Space page, Space settings page (Confluence)space.id, space.key

The Jira objects keep their API names. issue is the work item, and project is its space. context.accountId is the viewer's account ID. To see the whole context, log it and read it in the preview console.

Size the frame​

The frame fits its content and grows or shrinks when the content changes. Call setHeight only when you want a fixed height:

setHeight('300px'); // fixed height
setHeight('auto'); // fit the content again

Older examples call setHeight after every change. That still works, but you no longer need it.

Follow the dark theme​

Load Atlassian's design tokens for the viewer's theme, so your content matches Jira or Confluence:

const root = document.querySelector(':root');
root.setAttribute('data-color-mode', theme.colorMode);
root.setAttribute('data-theme', `${theme.colorMode}:${theme.colorMode}`);
root.insertAdjacentHTML('afterbegin',
`<link rel="stylesheet" href="https://forge.cdn.prod.atlassian-dev.net/atlaskit-tokens_${theme.colorMode}.css" />`);

The built-in snippets also load @atlaskit/css-reset to match Atlassian's fonts and spacing.

Errors​

Script Master catches errors the code doesn't handle and promise rejections nobody catches:

  • Viewers see that the fragment couldn't load, or a short warning when part of it rendered.
  • Jira and Confluence admins also see the error and the line.
  • Script Master records the failure on the fragment, and the Fragments list shows it.

A fragment that hasn't finished loading after 20 seconds counts as a failure too. See Failures.

To show your own message instead, catch the error in your code and write it into the page.

Keep viewers safe​

Text from Jira, Confluence or another site can contain markup. Put it into the page with textContent, not innerHTML, so a work item summary or page title can't add scripts to your fragment. When you must render HTML, clean it first. The Markdown notes gadget shows how.