

Last date modified: March 10 2025
Helper methods to open different types of modals. These functions are available under the `convenienceApi.modalService` namespace.
Promise
Promise
Promise
Promise
Promise
Promise
Promise
Promise
Open a confirmation modal
Returns: Promise
- dialog promise with dialog result
Param | Type | Description | ||||
---|---|---|---|---|---|---|
model | Object
|
Data to be passed to modal
{
title: String,
message: String,
acceptText: String?, // defaults to 'Accept'
cancelText: String?, // defaults to 'Cancel'
cancelAction: Function?,
acceptAction: Function?,
focusEls: {
cancel: HTMLElement?,
accept: HTMLElement?
},
firstFocusableElementSelector: String?
} |
||||
openModalHandler | function
|
(Optional) callback to be executed after modal has opened
|
Param | Type | Description |
---|---|---|
model | Object
|
Data to be passed to modal |
openModalHandler | function
|
callback to be executed after modal has opened |
Example
var model = {
title: "Confirmation Modal Example",
acceptAction: function acceptAction() {
console.log("Accept button was clicked");
},
cancelAction: function cancelAction() {
console.log("Cancel button was clicked");
}
};
convenienceApi.modalService.confirm(model);
Promise
Open a progress modal
Returns: Promise
- dialog promise with dialog result
Param | Type | Description | ||||
---|---|---|---|---|---|---|
model | Object
|
Data to be passed to modal
{
title: String,
errorMessage: String?
message: String?, // A warning message
cancelText: String?, // Defaults to 'Cancel'.
value: Number,
state: String? // One of the following: "failed", "indeterminate", or null.
cancelAction: Function?,
focusEls: {
cancel: HTMLElement?
},
firstFocusableElementSelector: String?
}
|
||||
openModalHandler | function
|
(Optional) callback to be executed after modal has opened
|
Param | Type | Description |
---|---|---|
model | Object
|
Data to be passed to modal |
openModalHandler | function
|
callback to be executed after modal has opened |
Example
var model = {
title: "Progress Modal Example",
value: 0,
cancelAction: function cancelAction() {
console.log( "Cancel button was clicked" );
}
};
var fakeAfterModalOpeningHandler = function fakeAfterModalOpeningHandler() {
// This sets the progress value to 100 after 1 second.
setTimeout(function () {
model.value = 100;
}, 1000);
};
convenienceApi.modalService.openProgressModal(model, fakeAfterModalOpeningHandler);
Promise
Open a custom modal
Returns: Promise
- dialog promise with dialog result
Param | Type | Description | ||||
---|---|---|---|---|---|---|
model | Object
|
Data to be passed to modal
{
title: String,
isLoading: Boolean, // True if loading layout should be displayed.
errors: List<String>, // Errors list to be displayed in default error container.
warningMode: Boolean, // True if display errors in warning mode.
noHeader: Boolean, // True if title container should not be displayed.
noActions: Boolean, // True if actions container should not be displayed.
theme: String, // Refer to constants.MODAL_THEMES.
contentElement: HTMLElement, // HTML element to be displayed in custom modal content.
actions: List<Object> // { disabled: Boolean, click: Function, text: String }
cancelAction: Function?,
acceptAction: Function?,
focusEls: {
cancel: HTMLElement?,
accept: HTMLElement?
},
firstFocusableElementSelector: String?
}
* Notes about **contentElement**
* This DOM element is attached inside the modal content zone once the modal is opened.
* The element that contentElement references should not change after the modal is opened.
* If the content is loaded dynamically, it is recommended to pass an empty HTML container for contentElement and modify this container later when the content is ready to be loaded. |
||||
openModalHandler | function
|
(Optional) callback to be executed after modal has opened
close(message: String) - closes modal with the message passed for openCustomModal promise resolution as a result. Skips acceptAction call before close.
* close(message: String) - closes modal with the message passed for openCustomModal promise resolution as a result. Skips acceptAction call before close.
* cancel(message: String) - closes modal as cancelled with message passed for openCustomModal promise resolution as a result.
* accept(message: String) - closes modal with the message passed for openCustomModal promise resolution as a result.
* enableActions() - enables all modal actions.
* disableActions() - disables all modal actions.
* focusElement() - focuses element in custom modal content. |
Param | Type | Description |
---|---|---|
model | Object
|
Data to be passed to modal |
openModalHandler | function
|
callback to be executed after modal has opened |
Example
// Create custom modal content container.
var contentContainer = document.createElement("div");
// Create custom modal model. Initially, display it in loading state.
var model = {
isLoading: true,
theme: convenienceApi.constants.MODAL_THEMES.CONFIRMATION,
contentElement: contentContainer
};
convenienceApi.modalService.openCustomModal(model).then(function (closeResult) {
if (closeResult.wasCancelled) {
console.log("Custom modal was cancelled");
} else {
console.log("Custom modal was accepted");
}
console.log(closeResult);
});
// This section could be an async data load for custom modal content.
setTimeout(function () {
// Disable loading state.
model.isLoading = false;
// Populate DOM content.
contentContainer.innerText = "Loaded content";
// Define actions for the custom modal.
model.actions = [
{
text: "Ok" ,
click: function click() {
model.accept("Accept payload");
}
},
{
text: "Disabled action" ,
disabled: true
},
{
text: "Cancel" ,
click: function click() {
model.cancel("Cancel payload");
}
}
];
}, 1000);
Promise
Open a Relativity Delete modal
Returns: Promise
- dialog promise with dialog result
Param | Type | Description | ||||
---|---|---|---|---|---|---|
model | Object
|
Data to be passed to modal
{
objectTypeName: String,
actions: List<Object> // { position: "left"|"right", disabled: Boolean, click: Function, text: String }
dependencyListPromise: Promise<List<DependencyObject>>?,
cancelAction: Function?,
acceptAction: Function?,
focusEls: {
cancel: HTMLElement?,
accept: HTMLElement?
}
}
For more information about DependencyObject, refer to its entry in the [Delete Pipeline](https://platform.relativity.com/RelativityOne/Content/FormsAPI/Delete_Pipeline.htm) page. |
||||
openModalHandler | function
|
(Optional) callback to be executed after modal has opened
|
Param | Type | Description |
---|---|---|
model | Object
|
Data to be passed to modal |
openModalHandler | function
|
callback to be executed after modal has opened |
Example
var modalData = {
objectTypeName: "Object Type Name"
};
convenienceApi.modalService.openDeleteModal(modalData).then(function (action) {
if (!action.wasCancelled) {
console.log("Delete the thing here");
} else {
console.log("Cancelled, so don't delete the thing");
}
});
Promise
Open a Multi List Picker modal.
Returns: Promise
- Dialog promise with dialog result.
Param | Type | Description | ||||
---|---|---|---|---|---|---|
model | Object
|
Data to be passed to modal
{
// Used to format the full title of the modal, such as "Select Items - [label goes here]".
label: String,
// Optional. Text displayed in modal header. Defaults to "Select Items - {label}"
title: string
// A key by which the multi-list picker component stores settings of its inner Item Lists in session storage.
persistenceKey: String,
// A key by which the multi-list picker component stores widths of columns of its inner Item Lists in session storage.
columnsPersistenceKey: String,
// The name of the property used by a multi-list picker component to uniquely identify data items in the list.
rowKeyName: String,
// An array of values that are currently selected in the multi-list picker component. These values must correspond to values of property in data items denoted by "rowKeyName".
selectedValues: Array<Number>,
// An object used by the multi-list picker component to retrieve its data. For more information, see the following section.
itemListDataProvider: Object<ItemListDataProvider>,
// An object used by the multi-list picker component to retrieve and save settings of its inner Item Lists. For more information, see the following section.
itemListSettingPersistenceService: Object<ItemListSettingPersistenceService>,
// A workspace identifier mainly used for data retrieval.
workspaceId: Number,
// Artifact ID of the object type to be displayed in the picker.
objectTypeId: Number,
// Artifact ID of the workspace
workspaceId: Number,
// Optional. Used to customize the default "accept" and "cancel" buttons in the modal footer.
actions: Array<Action>
}
class Action
{
// Optional. CSS class applied to the button.
class: String,
// Optional. Text displayed on the button.
caption: String,
// Optional. If true, the button will not be rendered.
hide: Boolean
}
For more information about the itemListDataProvider and itemListSettingPersistenceService objects, see the [Additional Forms API objects](https://platform.relativity.com/RelativityOne/Content/Relativity_Forms/Additional_Forms_API_objects.htm) page. |
||||
openModalHandler | function
|
(Optional) callback to be executed after modal has opened
|
Param | Type | Description |
---|---|---|
model | Object
|
Data to be passed to modal. |
model.label | String
|
Title of modal |
model.persistenceKey | String
|
Key used to store settings of modal item list in local storage |
model.columnsPersistenceKey | String
|
Key used to store settings of modal item list columns in local storage |
model.rowKeyName | String
|
Name of property used by modal item lists to identify items |
model.itemListDataProvider | Object
|
Used to retrieve the data displayed in the item list. See itemListDataProvider |
model.workspaceId | Number
|
Artifact ID of the workspace |
model.objectTypeId | Number
|
Artifact ID of the object type to be displayed in the picker |
model.selectedValues | Array.<(String|Number)>
|
Values of the currently selected items in the picker. Corresponds to the key denoted by rowKeyName |
model.itemListSettingPersistenceService | Object
|
Optional. Used to customize how item list settings are stored. See itemListSettingPersistenceService |
model.title | String
|
Optional. Text displayed in modal header. Defaults to "Select Items - " |
model.actions | Array.<Object>
|
Optional. Used to customize the default "accept" and "cancel" buttons in the modal footer. |
model.actions[].class | String
|
Optional. CSS class applied to the button. |
model.actions[].caption | String
|
Optional. Text displayed on the button. |
model.actions[].hide | Boolean
|
Optional. If true, the button will not be rendered. |
openModalHandler | function
|
Optional. Callback to be executed after modal has been opened. |
Example
(function (eventNames, convenienceApi) {
var eventHandlers = {};
var selectedValues = [];
var dataProvider = convenienceApi.itemListDataProviderFactory.create(
"object",
{
workspaceId: convenienceApi.getCurrentFormState().workspaceId,
objectTypeId: 10,
textIdentifierColumnName: "Control Number",
viewArtifactId: 0 // Use default view for object
}
);
var openCustomPicker = () =>
convenienceApi.modalService.openMultiListPickerModal({
selectedValues: selectedValues,
persistenceKey: "CustomPickerForDocument",
columnsPersistenceKey: "CustomPickerForDocumentColumns",
itemListDataProvider: dataProvider,
rowKeyName: "ArtifactID",
objectTypeId: 10,
label: "Document",
workspaceId: convenienceApi.getCurrentFormState().workspaceId
}).then((result) => {
if (!result.wasCancelled) {
selectedValues = result.output;
}
});
eventHandlers[eventNames.CREATE_CONSOLE] = function() {
var button = document.createElement("button");
button.id = "custompicker";
button.textContent = "Open Custom Picker";
button.addEventListener("click", () => {
openCustomPicker();
});
return convenienceApi.console.containersPromise.then(function(containers) {
containers.rootElement.appendChild(button);
});
};
return eventHandlers;
})(eventNames, convenienceApi);
Promise
Open a Single List Picker modal.
Returns: Promise
- Dialog promise with dialog result.
Param | Type | Description | ||||
---|---|---|---|---|---|---|
model | Object
|
Data to be passed to modal
{
// Used to format the full title of the modal, such as "Select Items - [label goes here]".
label: String,
// Optional. Text displayed in modal header. Defaults to "Select Items - {label}"
title: string
// A key by which the multi-list picker component stores settings of its inner Item Lists in session storage.
persistenceKey: String,
// A key by which the multi-list picker component stores widths of columns of its inner Item Lists in session storage.
columnsPersistenceKey: String,
// The name of the property used by a multi-list picker component to uniquely identify data items in the list.
rowKeyName: String,
// An array of values that are currently selected in the multi-list picker component. These values must correspond to values of property in data items denoted by "rowKeyName".
selectedValues: Array<Number>,
// An object used by the multi-list picker component to retrieve its data. For more information, see the following section.
itemListDataProvider: Object<ItemListDataProvider>,
// An object used by the multi-list picker component to retrieve and save settings of its inner Item Lists. For more information, see the following section.
itemListSettingPersistenceService: Object<ItemListSettingPersistenceService>,
// A workspace identifier mainly used for data retrieval.
workspaceId: Number,
// Artifact ID of the object type to be displayed in the picker.
objectTypeId: Number,
// Artifact ID of the workspace
workspaceId: Number,
// Optional. Used to customize the default "accept" and "cancel" buttons in the modal footer.
actions: Array<Action>
}
class Action
{
// Optional. CSS class applied to the button.
class: String,
// Optional. Text displayed on the button.
caption: String,
// Optional. If true, the button will not be rendered.
hide: Boolean
}
For more information about the itemListDataProvider and itemListSettingPersistenceService objects, see the [Additional Forms API objects](https://platform.relativity.com/RelativityOne/Content/Relativity_Forms/Additional_Forms_API_objects.htm) page. |
||||
openModalHandler | function
|
(Optional) callback to be executed after modal has opened
|
Param | Type | Description |
---|---|---|
model | Object
|
Data to be passed to modal. |
model.label | String
|
Title of modal |
model.persistenceKey | String
|
Key used to store settings of modal item list in local storage |
model.columnsPersistenceKey | String
|
Key used to store settings of modal item list columns in local storage |
model.rowKeyName | String
|
Name of property used by modal item lists to identify items |
model.itemListDataProvider | Object
|
Used to retrieve the data displayed in the item list. See itemListDataProvider |
model.workspaceId | Number
|
Artifact ID of the workspace |
model.objectTypeId | Number
|
Artifact ID of the object type to be displayed in the picker |
model.selectedValue | String | Number |
Value of the currently selected item in the picker. Corresponds to the key denoted by rowKeyName |
model.itemListSettingPersistenceService | Object
|
Optional. Used to customize how item list settings are stored. See itemListSettingPersistenceService |
model.title | String
|
Optional. Text displayed in modal header. Defaults to "Select Items - " |
model.actions | Array.<Object>
|
Optional. Used to customize the default "accept" and "cancel" buttons in the modal footer. |
model.actions[].class | String
|
Optional. CSS class applied to the button. |
model.actions[].caption | String
|
Optional. Text displayed on the button. |
model.actions[].hide | Boolean
|
Optional. If true, the button will not be rendered. |
openModalHandler | function
|
Optional. Callback to be executed after modal has been opened. |
Example
(function (eventNames, convenienceApi) {
var eventHandlers = {};
var selectedValue;
var dataProvider = convenienceApi.itemListDataProviderFactory.create(
"object",
{
workspaceId: convenienceApi.getCurrentFormState().workspaceId,
objectTypeId: 10,
textIdentifierColumnName: "Control Number",
viewArtifactId: 0 // Use default view for object
}
);
var openCustomPicker = () =>
convenienceApi.modalService.openSingleListPickerModal({
selectedValue: selectedValue,
persistenceKey: "CustomPickerForDocument",
columnsPersistenceKey: "CustomPickerForDocumentColumns",
itemListDataProvider: dataProvider,
rowKeyName: "ArtifactID",
objectTypeId: 10,
label: "Document",
workspaceId: convenienceApi.getCurrentFormState().workspaceId
}).then((result) => {
if (!result.wasCancelled) {
selectedValue = result.output;
}
});
eventHandlers[eventNames.CREATE_CONSOLE] = function() {
var button = document.createElement("button");
button.id = "custompicker";
button.textContent = "Open Custom Picker";
button.addEventListener("click", () => {
openCustomPicker();
});
return convenienceApi.console.containersPromise.then(function(containers) {
containers.rootElement.appendChild(button);
});
};
return eventHandlers;
})(eventNames, convenienceApi);
Promise
Open a KeyboardShortcuts modal.
Returns: Promise
- Dialog promise with dialog result.
Param | Type | Description |
---|---|---|
model | Object
|
Data to be passed to modal. |
openModalHandler | function
|
Callback to be executed after modal has been opened. |
On this page
Why was this not helpful?
Check one that applies.
Thank you for your feedback.
Want to tell us more?
Great!
Additional Resources |
|||
DevHelp Community | GitHub | Release Notes | NuGet |