Modal Service

Helper methods to open different types of modals. These functions are available under the `convenienceApi.modalService` namespace.

Methods

confirm(model, openModalHandler)Promise
Open a confirmation modal
openProgressModal(model, openModalHandler)Promise
Open a progress modal
openCustomModal(model, openModalHandler)Promise
Open a custom modal
openDeleteModal(model, openModalHandler)Promise
Open a Relativity Delete modal
openMultiListPickerModal(model, openModalHandler)Promise
Open a Multi List Picker modal.
openSingleListPickerModal(model, openModalHandler)Promise
Open a Single List Picker modal.
openKeyboardShortcutModal(model, openModalHandler)Promise
Open a KeyboardShortcuts modal.

Properties Details

confirm(model, openModalHandler) ⇒ 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
ReturnDescription
OpenDialogResultAn object primarily interesting in that it contains the DialogController on its "controller" property. For more information, see Accessing The DialogController API on the Aurelia web site.
Param Type Description
model Object Data to be passed to modal
openModalHandler function callback to be executed after modal has opened

Example

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

openProgressModal(model, openModalHandler) ⇒ 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
ReturnDescription
OpenDialogResultAn object primarily interesting in that it contains the DialogController on its "controller" property. For more information, see Accessing The DialogController API on the Aurelia web site.
Param Type Description
model Object Data to be passed to modal
openModalHandler function callback to be executed after modal has opened

Example

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

openCustomModal(model, openModalHandler) ⇒ 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
ReturnDescription
OpenDialogResultAn object primarily interesting in that it contains the DialogController on its "controller" property. For more information, see Accessing The DialogController API on the Aurelia web site.
At the time the openModalHandler is called, the model object passed to openCustomModal function is enriched with functions for interacting with the modal when it's 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

Copy
// 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);

openDeleteModal(model, openModalHandler) ⇒ 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
ReturnDescription
OpenDialogResultAn object primarily interesting in that it contains the DialogController on its "controller" property. For more information, see Accessing The DialogController API on the Aurelia web site.
Param Type Description
model Object Data to be passed to modal
openModalHandler function callback to be executed after modal has opened

Example

Copy
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");
    }
});

openMultiListPickerModal(model, openModalHandler) ⇒ 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
ReturnDescription
OpenDialogResultAn object primarily interesting in that it contains the DialogController on its "controller" property. For more information, see Accessing The DialogController API on the Aurelia web site.
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

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

openSingleListPickerModal(model, openModalHandler) ⇒ 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
ReturnDescription
OpenDialogResultAn object primarily interesting in that it contains the DialogController on its "controller" property. For more information, see Accessing The DialogController API on the Aurelia web site.
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

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

openKeyboardShortcutModal(model, openModalHandler) ⇒ 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.