Modals

Warning

This code is for the pre-4.4.0 extension. If you are writing a Tecton SSR or CSR extension use this modal documentation.

“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 uses some special JavaScript to access Online’s modals, but you will invoke them in your extension routes using a special “modal” keyword argument.

Modals are displayed by using code from the Online application our extension runs inside of, so we need to use the special APIs defined below. This ensures the modals in the SDK look and feel exactly the same as the modals present in the rest of the application.

Modals are defined on the Q2Form object. A Q2Form returned with the optional “modal” keyword argument will display the configured modal over that form’s template.

There are two Python objects relating to modals- Modal and ModalAction. 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 three types of modal:

SuccessModal: Returns a success code to Online and displays a green checkmark to the user ErrorModal: Returns an error code to Online and displays a red error icon to the user WarningModal: Returns modal displaying an orange warning icon to the user

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

html = forms.Q2Form(
    "Modal Demo",
    modal=modals.ErrorModal('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 = forms.Q2Form(
    "Modal Demo",
    modal=modals.ErrorModal('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 show_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 Ember.js, the framework powering the Online application. 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 = forms.Q2Form(
    "Modal Demo",
    modal=modals.ErrorModal('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 function on the DOM 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 = forms.Q2Form(
    "Modal Demo",
    modal=modals.SuccessModal('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.