Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 3 Tasks : Validating Data in a Form

Validating Data in a Form
TIBCO Forms supports runtime validation of data as the user fills up the forms. You can configure validations for the fields defined on the form. You can configure the validations to occur either when the user changes a field value, or when the user submits the form.
Validations help users to specify correct data, thereby enhancing the overall experience. On the server side, the submitted data are validated against the restrictions specified in the business object models used within the form.
You can write validation scripts for each control as well as each pane on a form. Validation scripts usually run when users update data or submit the form. The scripts need to be written to explicitly return a Boolean or an Array.
If the returned value for one or more validation scripts is false, the validation error messages are displayed on the form in a special pane called a Messages pane. Users can click the error message to navigate to the first instance of the error in the form.
The Messages pane displays the validation messages. You can specify a validation message either using a key reference from the External Resources of a *.properties file or as a Custom Message.
By default, the Messages pane opens at the bottom of the form when a validation fails. By manually adding a Messages pane to the form, you can configure the font and layout properties of the pane, and place it anywhere other than the default position.
Helping Users with Validation Messages
Good validation messages help users complete the forms faster and without any error in the specified data. This section summarizes how the users get to see the error messages for different types of controls and panes.
If you configure validation messages for each control, the user gets the validation message for the control after specifying data and moving on to the next control. If you configure the validation to occur on submitting the form, the validation message appears after the user clicks Submit to submit the form.
Clicking the message associated with an individual control sets the focus on that control. Record and Grid panes automatically navigate to the correct page in order to show the invalid control. If you configure validation for the entire pane, the focus of the screen shifts to the beginning of the pane in case of a failed validation.
Implementing Validations
You can add, edit, or remove validation scripts only when using the Solution Design capability. If the Solution Design capability is disabled, the Validations tab does not appear on the Properties view of a control. The following section describes the steps to perform such tasks.
For information about invoking validations programmatically, see validate in the API reference.
Adding a Validation
1.
The Properties view shows the properties for that control or pane. You can view the validation script for any control or pane by clicking the control or pane, and clicking the Validations tab in the Properties view of the control or the pane. See Chapter 7, Reference for a detailed description of each property available on the Validations tab.
Figure 89 The Validations Tab
2.
The Define Validation dialog opens.
Figure 90 The Define Validation Dialog
3.
4.
Select the Execute When option from:
a.
On Form Submit: Sets the validation script to run when the user submits the form. When more than one control is involved, such as when you want to ensure that at least one of the two or more fields are filled in, you can select On Form Submit.
b.
On Value Change: Sets the validation script to run when the user specifies a value in the field, and then exits that field. The validations of the syntax of specified values are best performed On Value Change.
5.
If you select Validate As List, then the validation runs just once for the entire list of items, and context.value contains an Array (for primitive values) or a list (for multi-valued pane validations). If you do not select Validate As List, then the validation runs once for each item in the multi-valued control or pane, with context.value set to a new item each time the validation is invoked.
6.
7.
Select the type of Message from:
External Reference: Picks the validation message from an external *.properties resource. You can define validation messages at the form level in an external resource file with validation_ as a prefix in the key, and share the file across forms or projects. Also, the default implicit validations can reference messages in the common resource bundle. External reference validation messages can use substitution variables to include runtime data values in an externalized static text string.
Custom: Allows you to specify custom text message or a message that contains substitution variables, for example: “Sorry, you cannot have more than {0} {1}”. You can dynamically determine the validation message at the runtime using substitution variables.
8.
If you select the Message type as External Reference, click the button to open the Resource Picker dialog. Select a validation message from all the available validation_* resource keys, and click OK.
The Resource Picker dialog displays a filtered list of only validation_* resource keys.
Figure 91 The Resource Picker Dialog
See Example 3: Validation Message Referenced from External Resource for details.
9.
If you select the Message type as Custom with substitution variables, ensure that the validation script expression evaluates to an array of strings.
The length of the array must be equal to the number of substitution variables in the message. See Example 2: Custom Validation Message with Substitution Variables for details.
10.
Confirm that the Enabled check box is selected, and click Finish to complete the process of defining a validation.
Editing a Validation
1.
Figure 89 displays the validations defined for a control or a pane.
2.
From the Validations tab of the Properties view, edit the Name, Execute When, Message Type, Message, and List fields.
3.
A cell editor button appears next to the script.
4.
The Edit Validation Script dialog opens.
Figure 92 The Edit Validation Script Dialog
 
5.
Edit the code in the Script field, and click Finish.
The script editor provides content-assist editing. On typing the beginning of a legal value, such as “control.”, a pop-up window appears listing the available completion proposals. If you type CTRL+Space, a list displays containing all the top-level variables that are available in the given context.
Edit Validation Script Dialog
In this cell editor dialog, you can edit the script that determines whether the data submitted are valid, or you can modify the error message that appears when users submit invalid data. The final expression in the validation script must evaluate to true (if the data are valid), false (if the data are invalid), or an array of strings (if the data are invalid and the validation message contains substitution variables).
You can use the notation this in your script to refer to the control or pane during a given validation invocation. A validation script, for instance, might contain a statement such as the following:
this.getValue() == "New York";
You can also use the context object provided while executing the validation to retrieve the value of the given control or pane:
context.value == "New York";
You can refer to any control by using the “control.” notation, or to a pane using "pane." notation. To refer to the value of a control, use the latter notation in conjunction with the Control.getValue() method:
control.city_name.getValue() == "New York";
Example 1: Custom Validation Message
In this example, the text field has the name petNumber.
Figure 93 The General Tab
 
This means that the value submitted for this text field by a user can be referenced in the validation script by the expression control.petNumber.getvalue().
1.
In the Define Validation dialog, specify the value in the Script field.
Figure 94 Defining Custom Validation
2.
In the Custom text field, type the validation error message that you want the user to see on specifying incorrect data.
3.
Confirm that the Enabled check box is selected, and click Finish.
If the user submits a value other than the one specified in the validation script, the validation error message appears on the form.
Figure 95 Validation Script Example 1
 
Example 2: Custom Validation Message with Substitution Variables
To specify a validation message with substitution variables, you need to perform the following steps:
1.
In the Define Validation dialog, type the code as shown in the Script field in Figure 96.
Figure 96 Defining Custom Validation Using Substitution Variables
2.
In the Custom message field, specify the validation error message using substitution variables from an array.
3.
Confirm that the Enabled check box is selected, and click Finish.
If the user submits a value other than the one specified in the validation script, a validation error message using the substitution variables from the array appears on the form.
Figure 97 Validation Script Example 2
Example 3: Validation Message Referenced from External Resource
To specify a validation message from an external resource, you need to perform the following steps:
1.
Create <validations>.properties file under the Presentation Resources special folder in Project Explorer.
The name of the file does not matter as long as the extension is .properties. The file can contain any arbitrary custom display strings, not necessarily only validation messages.
2.
Define validation messages in the <validations>.properties file.
The validation message key must have "validation_" as a prefix. If a key does not start with "validation_", the system does not treat it as a validation message.
Figure 98 Sample Validation Messages
3.
Add the newly-created <validations>.properties file to the resources list of the form.
After adding the .properties file as a form external resource reference, the new validation messages are available in the Resource Picker.
4.
In the Define Validation dialog, provide the details of the external resource reference.
Figure 99 The Define Validation Dialog Using External Resources
5.
Click Finish.
If the user submits a value other than the one specified in the validation script, the validation error message from the external resource file appears on the form.
Figure 100 Validation Script Example 3
 
Enabling or Disabling a Validation
You can enable or disable a validation at the time of defining it, or after defining it. If disabled, the validation definition remains in the form model, but is not invoked at runtime. This may be useful during troubleshooting of a form.
When defining a validation, you can enable it or disable it by using the Enabled check box on the Define Validation dialog.
You can enable or disable a defined validation by using the Enabled check box in the Validations tab of the Properties view.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved