Validating coach data without exiting a coach

You can use the data change properties of a coach in a client-side human service to validate the coach data without exiting the coach.

About this task

By using the data change mechanism, you can validate the data entered into the coach while the user is still interacting with the coach. For example, you can do coach data validation to ensure that required fields contain data and before dates precede after dates.
Tip: You can leverage this same mechanism for more than validation. The validation mechanism can be used to update variables as the user enters values in the coach. For example, you can perform calculations and render the results in the coach. Or you can update a variable that controls the enablement state of a button in the coach.

For a typical coach validation, you can use a client-side JavaScript that you specify in the coach to be validated. To avoid perceived performance issues with the coach, it is a best practice to use a fast-executing script.

For information on how to perform coach data validation after exiting the coach, see Validating coach data after exiting a coach.

Procedure

To validate the coach data in your client-side human service without exiting the coach, complete the following steps:

  1. Open the client-side human service that contains the coach to be validated.
  2. Select the coach to be validated and click its Data Change tab.
  3. In the Script properties, add the JavaScript code that identifies the problematic data in the coach. Use the tw.system.coachValidation.addValidationError(String variableName, String errorMessage) JavaScript API to identify the coach view that has the problematic data and provide a message that helps the user to correct the problem. For example:
    if (tw.local.startDate.getTime() > tw.local.endDate.getTime())
    	tw.system.coachValidation.addValidationError("tw.local.startDate", "The start date must precede the end date. Set the start date before the end date, and try again.");
    Note:
    • If the data element that is being validated is not bound to a coach view, there is nowhere to display a validation error if one occurs.
    • If a coach view that is being validated contains rich text, the validation script must remove the formatting before validating the contents.
    • If you are validating a list and you want the error to refer to the entire list, the variableName parameter must include [] as a suffix. This matches coach view binding where [] indicates that the object is a list. For example, if a coach view is bound to tw.local.var3[], which is a list, you need code like the following example:
      tw.system.coachValidation.addValidationError("tw.local.var3[]", "Var3 has validation error");
  4. Click Save or Finish Editing.
  5. Test that the coach validation works correctly by clicking Run Run. At run time, when data is changed in one of the coach views, the following validation actions occur:
    • If the data is valid, the coach execution completes successfully.
    • If the data in the coach is not valid, a validation error occurs, and the control indicates the problem.
    • If the next change fixes the data, the data is validated again, and the error is removed.
    For an example, see Example: validating a coach in a client-side human service.