Example: validating a coach in a client-side human service

This example shows you how to use the data change properties of a coach in a client-side human service to validate the coach data without exiting the coach.

1. Create the client-side human service that contains the coach to be validated. See Building a client-side human service.
2. In the Variables tab of the human service, create two private variables, startDate and endDate, and set the type of each variable to Date.
   
3. In the client-side human service diagram, rename the coach to Prompt for Start and End Dates.
4. In the Coaches tab, from the Variables section of the palette, drop the startDate and endDate parameters onto the coach. Leave the default OK button unchanged.
5. In the coach, select the Start date parameter and ensure that it is bound to the startDate variable in the Behavior section of the General tab.
   
6. Repeat step 5 for the End date parameter to verify that it is correctly bound to the endDate variable, and then save the coach configuration.
7. In the diagram view for the coach, click its Data Change tab and, in the Script properties, enter the following JavaScript construct:

   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.");

   In the coachValidation object, the first string contains the full variable path to the elements whose data is to be validated. The second string is the message for the user, which specifies what is wrong with the data and tells the user how to fix the problem.
   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");

8. Optional: To prevent the user from proceeding to the next step when the data is not valid, complete the following steps:
   1. In the Variables tab for the human service, add another private variable named readyToSubmit, and set its type to Boolean.
   2. In the Script properties of the selected coach, append the following JavaScript code to the existing script:

      tw.local.readyToSubmit = tw.system.coachValidation.validationErrors.length==0;

   3. In the Coaches tab, configure the OK button to be read-only when not ready, as shown:
      
9. Click Save or Finish Editing.
10. Click Run to run the human service.
11. In the browser that displays the coach, test the validation by completing the following steps:
    1. Set the End date to a date that precedes the start date. Click OK. The browser highlights the Start date field and displays a warning icon. If you hover over the warning icon, you see a message that the start date must precede the end date.
       
    2. Set the End date to a date that succeeds the start date. Click OK. The human service completes successfully because both dates are valid.