Brazos UI Modal - Boundary Events and Validation

Follow

Overview

This article is to help explain how use boundary events and validation with the Brazos UI Modal coach view.

Boundary Events

The Brazos UI Modal control has 4 configuration options that allow you to fire boundary events. These can be found in the "Boundary Event" configuration options for the Modal:

  1. Fire Boundary Event on Modal Open - fires a boundary event when the modal control is opened and sets the "Action Executed" variable to "TRIGGER"
  2. Fire Boundary Event on Modal Done - fires a boundary event when the modal's "Done" button is clicked and sets the "Action Executed" variable to "DONE"
  3. Fire Boundary Event on Modal Cancel - fires a boundary event when the modal's "Cancel" button is clicked and sets the "Action Executed" variable to "CANCEL"
  4. Fire Boundary on Modal Closed - fires a boundary event when the modal is closed any other way (click on the background, press Escape, or click on the "X" button) and sets the "Action Executed" variable to "CLOSE"

There is only one actual boundary event on the coach for each modal, so if you are firing multiple boundary events for a single modal you must use the "Action Executed" variable to determine which action fired the boundary event. An example of using all the different boundary actions is shown in the Brazos UI Examples Process App.

Note that help text in the Modal control documents the configuration options - hover over the configuration options to display the associated help text. 

Validation

You can use the Modal Boundary Events to enable validation of data inside the modal.

If you want to trigger a validation error inside the Modal, you can use the 'Error Message on Return from "Done" Boundary Event' configuration option. If this configuration contains a value when the user clicks on the Modal's "Done" button , the value is displayed as an error message and the modal doesn't close. If the configuration is empty or null when the user clicks on the Modal's "Done" button, the Modal will be closed and no message will be displayed.

A common pattern is to associate the configuration option 'Error Message on Return from "Done" Boundary Event' to a variable that's controlled on the server side. This server side variable will control if the modal is closed and the error message that is displayed.

Field level validation using the out of the box coach validation framework does not allow you to keep the modal open and present an error on the field. You can do field level validation with the out of the box validation framework; however, the modal will not remain open after the validation fires. One option is to combine the two approaches and validate at the field level on submission of the coach as well using theError Message on Return from "Done" Boundary Event' while in the modal.

Example

Attached you will find an example that illustrates using Done and Cancel boundary events, 'Error Message on return from "Done" Boundary Event', and out of the box coach validation with a Brazos UI Modal.

To run this example:

  1. Download the example
  2. Import into your Process Center and open the example in the Process Designer
  3. Run the Demo Human Service
  4. Click the Demo button to open the modal
  5. In the Modal Text input box
  6. Leave the input box empty and click Done to see the error generated from the "Error Message on return from 'Done' Boundary Event" configuration.
  7. Enter text and click Done for no errors.
  8. Clicking Cancel will clear any text that was entered. This is controled by the "Fire Boundry Event on Modal Cancel" configuration option and the associted server script.
  9. Click the "Validate Field Inside Modal" button to generate the out of the box coach valication on the Modal Text input box inside the modal.
  10. To generate an error leave the Modal Text input box in the modal empty.
Have more questions? Submit a request

Comments

  • Avatar
    Jay Rosenberg

    Two points - although the documentation states:
    "Action Executed" variable to "TRIGGUER"
    for the open case, it actually sets it to the american spelling: "TRIGGER".

    The second is more an item of interest that developers should be aware of. When the modal opens there is a close dialog icon [x] in the upper right hand corner. When the dialog is closed using the [x], then no boundary event is fired and the 'Action Executed' variable remains set to 'TRIGGER', so if you have any code that is associated with the CANCEL button, it will not run if the user closes the dialog with the [x].

  • Avatar
    Sergei Malynovskyi

    Thank you, Jay.
    Re point one - based on my conversation with Brazos UI dev team they believe that the spelling is still "TRIGGUER". They didn't want to change it because it would break existing implementations.

    Re point two - thank you, noted. DEV team is aware.

  • Avatar
    David Bailie

    Note that in Brazos UI v4.1.0 - 2015-08-02 an additional boundary event was added on closing the Modal via a background click, using the [x] or pressing Esc. From the release notes:

    [Improvement - US1715] [Modal]: Added Boundary Event for Modal Close (on background click, "x" button click, or Esc key press)

  • Avatar
    Matthew Corbett

    Great article. Very helpful to include the .twx.

  • Avatar
    Jay Rosenberg

    Brazos version 2.0 (5.4.6 Enterprise Edition - 8.5.7.0) shows that the configuration option: Error Message on Return from "Done" Boundary Event

    is marked as Deprecated - and is in the Deprecated section.  Is there now a new recommended way to keep the Modal open if there are validation errors in the modal on Done?  Can the document be updated to include the new method as well?

    Thanks.

  • Avatar
    Tom Bushart

    Hi Jay,

    We'll work to bring the article up to date! In the meantime here's the summary of what you need to know:

    The Modal currently works within the existing validation framework, which is why the "Error Message on Return from "Done" Boundary Event" is no longer needed. Simply assign CoachValidation messages to controls in the modal as needed and it will remain open.

     

    Heritage Human Service
    For a HHS, the setup is as typical for validating a control. Configure the Modal to "Fire Boundary Event on Modal Done Button" and wire that event to where ever you need (script, service, or even just a stay-on-page). Change the boundary event to "Fire Validation: Before". From there, use a validation script as normal to set an error message on a control in the modal. As long as the validation fails and you add an error message to a control in the Modal it will not close on clicking the done button. Errors are displayed as typical for controls used in other containers.

    Client-Side Human Service
    Currently, the Modal's validation works in CSHS if you validate after coach exit. The "in coach" approach that leverages the Data Change script has some quirks that likely need to be addressed before I would recommend it with Modals (it works fine for other controls). The after-exit method is essentially the same as with HHS, it just doesn't have a built-in "Fire Validation: Before" option. But as long as the boundary event ends up returning a validation error to a control in the Modal it will not close when you click the Done button. See this IBM documentation on this CSHS validation style.

Powered by Zendesk