Rate this page:
To consume the UI Modifications (UIM) API, your app needs to import the @forge/jira-bridge
package:
1 2import { uiModificationsApi } from '@forge/jira-bridge';
This API is strictly related to the Jira UI modifications module
1 2onInit(<initCallback>, <registerFieldsCallback>): void
initCallback
is where apps can query field data and request modifications. registerFieldsCallback
is used to specify which fields will be changed by initCallback
. The information returned by registerFieldsCallback
is used to display a loading indicator next to the relevant fields until initCallback
finishes.
Both callback functions are called every time:
project
or issueType
(from context) changesThe initCallback
function will receive one object as an argument. This object contains the following attributes:
api
- the API used to find and modify the GIC fieldsuiModifications
- an array of UIM entities registered for a given contextThe registerFieldsCallback
function will receive an object containing:
uiModifications
- an array of UIM entities registered for a given context1 2uiModificationsApi.onInit(({ api, uiModifications }) => { // You can find form fields using the FieldQueryingAPI here const summaryField = api.getFieldById('summary'); // You can manipulate the fields you found if (summaryField) { summaryField.setDescription('New summary description'); } }, ({ uiModifications }) => { // This function should return an array of the IDs of the fields // which are going to be changed in initCallback return ['summary']; })
All modifications requested synchronously using this API will be batched and applied at once.
If a Promise
is returned from the callback, all of the modifications will be postponed until the Promise
resolves.
This may be useful in a scenario when the app needs to perform an async operation before it requests a change.
UIM blocks any changes requested for fields within initCallback
for any field IDs not in the array returned from registerFieldsCallback
.
If the initCallback
doesn’t return a Promise
which resolves after all field modification requests are made, then field modifications requested asynchronously will be ignored.
1 2onChange(<changeCallback>, <registerFieldsCallback>): void
changeCallback
is where apps can query field data and request modifications. registerFieldsCallback
is used to specify which fields will be changed by changeCallback
. The information returned by registerFieldsCallback
is used to display a loading indicator next to the relevant fields until changeCallback
finishes.
Both callback functions are called every time:
blur
form field event is triggered by one of the GIC-supported text fields, which are summary
and description
change
form field event is triggered by any other GIC-supported fieldThe changeCallback
function will receive one object as an argument.
This object contains the following attributes:
api
- the API used to find and modify the GIC fieldschange
- an object with the current
attribute containing the object exposing the FieldAPI
of the field which triggered the change eventuiModifications
- an array of UIM entities registered for a given contextThe registerFieldsCallback
function will receive an object containing:
change
- an object with the current
attribute containing the object exposing the FieldAPI
of the field which triggered the change eventuiModifications
- an array of UIM entities registered for a given context1 2uiModificationsApi.onChange(({ api, change, uiModifications }) => { // You can find form fields using the FieldQueryingAPI here // You can also manipulate the fields you found or access the field // that triggered the change const { current } = change; if (current.getId() === 'summary') { // hint: You may want to read the content of uiModifications before // deciding what changes need to be applied here current.setDescription('New summary description'); } }, ({ change, uiModifications }) => { // This function should return an array of the IDs of the fields // which are going to be changed in changeCallback return ['summary']; })
All modifications requested synchronously using this API will be batched and applied at once.
If a Promise
is returned from the callback
, all of the modifications will be postponed until the Promise
resolves. This may be useful in a scenario when the app needs to perform an async operation before it requests a change.
UIM blocks any changes requested for fields within changeCallback
for any field IDs not in the array returned from registerFieldsCallback
.
If the changeCallback
doesn’t return a Promise
which resolves after all field modification requests are made, then field modifications requested asynchronously will be ignored.
1 2getFieldById(<fieldId>): FieldAPI | undefined
Accepts one argument: fieldId
(string) - the ID of the field which the app wants to work on.
Returns the FieldAPI object if the field exists on the GIC form.
Returns undefined
if the field doesn't exist on the GIC form.
1 2uiModificationsApi.onInit(({ api }) => { const { getFieldById } = api; const description = getFieldById('description') // You can perform operations on 'description' // field using the FieldAPI here }, () => ['description'])
The changes requested by setters in this API are not applied immediately.
They are batched and their application is postponed until the onInit
or onChange
callback execution ends.
This means that reading the values using getters will always provide the initial form field state, which is immutable.
1 2getId(): string
Returns the field's ID.
1 2setName(value: string): FieldAPI
Changes the field's name.
Example:
1 2field.setName('New name for the field');
1 2getName(): string
Returns the field's name.
1 2setDescription(value: string): FieldAPI
Changes the field's description.
Example:
1 2field.setDescription('This the description!');
1 2getDescription(): string
Returns the field’s description.
1 2setVisible(value: boolean): FieldAPI
Changes field visibility. The form payload will contain the field’s value, but the field won’t be visible in the UI if this is set to false
.
Example:
1 2field.setVisible(false);
1 2isVisible(): boolean
Returns true
if the field is currently visible. Returns false
otherwise.
1 2setValue(value: unknown): FieldAPI
Set a given field's value. See the specific field value contracts in the supported fields below to make sure the changes requested by this method will be applied.
1 2getValue(): unknown
Set a given field's value. See the specific field value contracts in the supported fields below to make sure the changes requested by this method will be applied.
1 2{ id: string, // '2' name: string, // 'High' iconUrl?: string, }
1 2string
1 2{ accountId: string, displayName: string, avatarUrls?: { '48x48': string, } }
1 2string[]
The description
field can be configured using either the rich-text "Wiki style renderer" (current default) or plain-text "Default style renderer". Each renderer requires a different value type, and apps will need to match the type they receive from getValue
in any calls to setValue
.
For more information on how to configure field renderers, please refer to https://support.atlassian.com/jira-cloud-administration/docs/configure-renderers/
1 2string // Plain-text editor | type ADF = { version: 1, type: 'doc', content: Node[] } // Rich-text editor (ADF format) // https://developer.atlassian.com/cloud/jira/platform/apis/document/structure/
Rate this page: