Modals

See the video below for a visual introduction to modals in uux:

“Modal” is our term for the standard overlay dialog present in most Online workflows. These are used for confirmation, error handling, or any time a user decision is required to continue. The Caliper SDK includes some convenience wrappers around the Tecton Modal APIs. This ensures the modals in your extension match the modals in the rest of Online Banking. There are a few specific examples below but the rest of the Tecton Modal APIs are available on the TectonModal class.

Modals are passed in as an argument to the get_tecton_form function. When a modal is passed to get_tecton_form a modal will be rendered immediately on top of your template.

There are three Python objects relating to modals- TectonModal, ModalAction, and TransRow. Access them by importing from q2_sdk.ui import modals.

Modal

Modal defines the message, header, and type of modal as well as takes optional custom actions.

There are four types of modals that are set using ModalType:

• InfoModal: Displays a modal with a “i” in a circle colored with the FI’s primary color

• SuccessModal: Displays a modal with a green check mark in a circle

• ErrorModal: Displays a modal with a red exclamation mark in a triangle

• WarningModal: Displays a modal with a yellow exclamation mark in a circle

Here is a code snippet that will display a basic error modal that can be dismissed by pressing the default ‘Close’ button:

html = self.get_tecton_form(
    "Modal Demo",
    modal=modals.TectonModal(modals.ModalType.ERROR, 'Error', 'There was an error. Sorry!')
)

At its most basic, a modal takes a title and a message. But modals are often used to present multiple options, or to navigate a user to a different route in the application. To configure this behavior, we use ModalActions.

ModalAction

When configured and passed to a Modal, a ModalAction will appear as a button on that modal. There are three common uses for ModalActions:

I want to route a user elsewhere in Online

If an extension fails to load, a common catchall is an error modal apologizing for the error that redirects the user back to the landing page. Here’s how we would define a modal to do that:

html = self.get_tecton_form(
    "Modal Demo",
    modal=modals.TectonModal(modals.ModalType.ERROR, 'Error'
        "There was an error. Sorry! Please go back to the Online application's landing page.",
        show_close=False,
        modal_actions=[modals.ModalAction('Close', external_route='landingPage')]
    )
)

return html

The default Close button merely removes the modal, so we hide it with close=False. We replace it with a custom button that sends the user back to the landing page via external_route.

These names refer to the route names in UUX. These route names can be looked up in the Q2_NavigationNode table. Here are some common destination routes:

Landing Page: ‘landingPage’ Activity Center: ‘activityCenter’ Settings: ‘settings’ Funds Transfer: ‘transfer’

I want to route a user to a different route within my extension

If your extension is defining multiple internal routes, you can use ModalAction to redirect them within the extension via internal_route:

html = self.get_tecton_form(
    "Modal Demo",
    modal=modals.TectonModal(modals.ModalType.ERROR,'Error',
        'There was an error. Sorry! Please go back to the default extension route.',
        show_close=False,
        modal_actions=[modals.ModalAction('Close', internal_route='default')]
    )
)

return html

I want to do something else entirely

Your modal can be configured to execute custom JavaScript when a button is clicked via the custom_action_hook keyword argument.

This keyword will look for a JavaScript global function with the name passed in as custom_action_hook and call that function when the button is pressed. This function can be defined in a custom template, or passed to the form via the custom_javascript keyword argument. Here’s a simple example:

html = self.get_tecton_form(
    "Modal Demo",
    modal=modals.TectonModal(modals.ModalType.SUCCESS, 'Demo',
        'This modal demonstrates custom actions. Click below to show a browser alert.',
        modal_actions=[modals.ModalAction('Show an Alert', custom_action_hook='showAlert')]
    ),
    custom_javascript="""function showAlert() {alert('Here I am!')}"""
)

return html

The Form will add your JavaScript snippet to the DOM so that your button can invoke it when pressed.