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:
| Global | What it does |
|---|---|
view | view.getContext() returns the context of the location. view.refresh() reloads the fragment |
requestJira | Calls the Jira REST API as the viewer |
requestConfluence | Calls the Confluence REST API as the viewer |
showFlag | Shows a flag in Jira or Confluence |
router | Opens or navigates to another page |
events | Forge bridge events |
Modal | Opens a Forge modal |
setHeight | Sets the frame's height. See Size the frame |
theme | The 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:
| Location | Fields in context.extension |
|---|---|
| Work item panel, Work item action | issue.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 page | project.id, project.key |
| Page action, Page byline item | content.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.
Relatedβ
- Preview your code: run the code with real data while you type.
- Fragments AI prompt: an API reference to give an AI assistant that writes fragments for you.
- Forge bridge API for browser scripts: the bridge calls in detail.
- Create a fragment: fill in a fragment and turn it on.