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 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"
  3. Fire Boundary Event on Modal Cancel Button - fires a boundary event when the modal's "Cancel" button is clicked and sets the "Action Executed" variable to "CANCEL"
  4. Fire Boundary Event on Modal Done Button - fires a boundary event when the modal's "Done" button is clicked and sets the "Action Executed" variable to "DONE"

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 or see the online copy of the documentation.

Validation

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

HHS

Performing Modal validations in Heritage Human Services is the same as for any other validation:

  • Set the "Fire Boundary Event on Done Modal Button" configuration option to true
  • Wire the modal boundary event as desired. The simplest is to simply set it to a Stay-On-Page event
  • Set the boundary event's "Fire Validation" Behavior to 'Before'

Script the validation as you normally would. If the validation script sets an error on a control in the modal's content box, then the message will be displayed and the modal will remain open rather than closing as normal.

The limitation with HHS validation and the modal is a common problem with validation on any HHS Coach: Any number of "Fire Validation: Before" events can only trigger a single validation script. Brazos UI buttons can use the Button Control ID to differentiate between triggering controls in scripting so if Modal validation needs to be separated from general page validation then a combination of identifiers may need to be used.

CSHS

Performing Modal validations in Client-Side Human Services also works similarly to other validation setups.

On Data Change

With the "Data Change" tab of a CSHS's Coach you can set soft validation for any control placed on the Modal. See IBM documentation for specific details. The limitation with this approach is that validation errors added in this manner will not prevent the Modal from closing. If you need to prevent the modal closing, use the next method.

On Coach Exit

This approach is similar to the HHS method:

  • Set the "Fire Boundary Event on Done Modal Button" configuration option to true
  • The modal boundary event can be wired to a script directly or to a service. See IBM documentation for further details and examples of these two approaches. In brief, either use:
    • A client-side validation script that also sets a flag for the presence of errors which then flows to a decision gateway for the stay-on-page path
    • Or a nested validation service that uses an error event for the stay-on-page path

If validation error messages are set against any controls in the Modal then they will display and the Modal will remain open rather than closing.

Deprecated

Previously, the 'Error Message on Return from "Done" Boundary Event' configuration option was used for Modal validation. 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. This was necessary prior to v4.5.0 of the toolkit:

[Improvement - US2075] [Modal]: Modal displays now stay open if the Done button triggers validation and there is a validation error

Example

Attached you will find an example that illustrates using boundary events along with coach validation in both Heritage and Client-Side Human Services with a Brazos UI Modal.

Note: The example has been updated to run on a minimum BPM version of 8.5.7 in order to illustrate CSHS validation.

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 "HHS Modal Validation Demo" Heritage Human Service
    • Click the Demo button to open the modal.
      • Enter and modify inputs to see how validation works with various methods of exiting the Modal. See the inline text for more details.
    • Click the "Validate Field Inside Modal" button to demonstrate validating modal contents from outside the context of the Modal events themselves. Note that you may need to reload the service to reset the variables to a state where validation fails.
  4. Run the "CSHS Modal Validation Demo" Client-Side Human Service
    • Choose between running the validation via direct scripts or a nested validation service. This can be changed on the running coach.
      • Errors from the nested service will also generate browser console log messages.
    • Click the Demo button to open the modal.
      • Enter and modify inputs to see how validation works with various methods of exiting the Modal. The CSHS example also includes validation via Data Change. See the inline text for more details.
    • Click the "Validate Field Inside Modal" button to demonstrate validating modal contents from outside the context of the Modal events themselves. Note that you may need to reload the service to reset the variables to a state where validation fails.
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.

  • Avatar
    Tom Bushart

    Article updated to reflect the latest behavior of the Modal in Brazos UI. Example application updated to show current validation methods of the Modal in both HHS and CSHS. Note: The example application has been updated to a base BPM version of 8.5.7 in order to properly illustrate validation within CSHS.

Powered by Zendesk