showModal

tecton.actions.showModal(modalOptions: PlatformModalOptions): Promise<string>;

export interface PlatformModalOptions {
    title: string;
    message: string;
    modalType?: ModalType;
    button1?: ModalButton;
    button2?: ModalButton;
    button3?: ModalButton;
    close?: boolean;
    isBlocking?: boolean;
    customMarkup?: string;
    msgHasMarkup?: boolean;
    transInfo?: Array;
    infoList?: string[];
    addlInfo?: string;
    refocus?: ModalFocusTarget;
    refocusContainer?: ModalFocusTarget;
    testId?: string;
}

export interface ModalButton {
    text: string;
    actionName: string;
}

export type ModalFocusTarget = HTMLElement | string;

export type ModalType = 'success' | 'error' | 'info' | 'warning';

tecton.actions.showModal({
    title: 'Funds Transfer #456465',
    message: "Your funds transfer was successfully processed on 4/5/2019",
    modalType: "info",
    transInfo: [{
        label: 'From Account',
        value: 'Regular Checking x87234'
    }, {
        label: 'To Account',
        value: 'Regular Savings'
    }, {
        label: 'Amount',
        value: '$200.00'
    }, {
        label: 'Memo',
        value: 'Transfer to savings.'
    }]
});

tecton.actions.showModal({
    title: 'Leaving Application: External Link Clicked',
    message: `You are about about to be navigated to out of online banking. Do you want to proceed?`,
    close: false,
    button1: {
        text: 'Yes',
        actionName: 'LEAVE'
    },
    button2: {
        text: 'No',
        actionName: 'STAY'
    },
    refocus: 'main-content',
    refocusContainer: 'external-link-container'
}).then(function(actionName) {
    if (actionName === 'LEAVE') {
        tecton.actions.openURL('https://bit.ly/2KnkROu', { showInOverpanel: false, nativeBrowserIfInApp: false, requiresToken: false });
    }
});

Handling User Events

The showModal capability lets you know which option the user clicked by utilizing the value returned from the Promise. Using the below code as an example, if you provide an actionName of "confirm" to the button1 object and the user clicks that button, the modal will close, and the promise will resolve with a value of "confirm."

If, however, the user clicks the close button or icon in the modal, the modal will close and the promise will resolve with a default value of "close". This is so you can perform any necessary actions based on whatever action the user takes while the modal is displayed.

const actionName = await tecton.actions.showModal({
  title: "Leaving so soon?",
  message: "Click 'Okay' to be logged out.",
  button1: {
    text: "Okay",
    actionName: "confirm",
  },
});

switch (actionName) {
  case "confirm":
    tecton.actions.navigateTo("logout");
    break;
  case "close":
    tecton.actions.navigateTo("dashboard");
    break;
}

Restoring Focus

refocus can provide a fallback focus target for the platform to use if the original active element cannot be restored after the modal closes. refocusContainer can provide a container used to find sibling fallback targets matching the original focused element tag.

Both options accept an element id, selector, or HTMLElement in UUX. When calling showModal from an SDK extension, prefer passing a string id or selector because modal options are serialized across the platform message bus.

Using Custom Markup

When passing HTML to the showModal Capability via the customMarkup property, it is essential to note that this HTML passes through DOMPurify to ensure that no malicious content is making its way through. While this removes things like custom <style> or <script> tags, it will also remove references to Web Components that are not included in the following list:

• q2-avatar
• q2-badge
• q2-detail
• q2-icon
• q2-item
• q2-list
• q2-loading
• q2-message
• q2-currency
• q2-relative-time
• q2-tooltip

We do this because not every Web Component is intended to be used in the modal (e.g., form fields, data tables, steppers, etc.), so we enforce it at this layer.

In this example, showModal is configured to render with "warning" modal styling in place. As the modal pops up near the top-center of the platform's UI, the background behind the modal becomes dimmed. The modal title and message are prominently displayed at the top of the modal window, just beneath an alert icon.

In the content found below the title and message, the string values provided to several other configuration options can observed. In descending order they are: customMarkup, transInfo, addlInfo and infoList.

The visual impact of a style attribute included the in customMarkup parameter can be observed, transInfo labels are bolded, and infoList items are centered as an unordered list.

Upon clicking the close button at the bottom of the modal, a default actionName of "close" is dispatched to the promise's fulfillment handling block.

Captured on UUX version 4.6.0.10A.