How to use explicit Validation Rules
From Wiki
Contents |
Introduction
Validation rules are used in WebRatio applications to verify that the input submitted by the user through a form is correct. WebRatio provides a built-in mechanism whereby you can validate the correctness of a single input field of Entry and Multi Entry units, by using a number of predefined validity predicates.
This article will show you how to use predefined validation rules.
Definition
A validation rule is a logical condition evaluated on the content input by the user in a field, selection field, multi selection field or entry unit. WebRatio provide two types of validation rules:
- Built-in validation rules, whereby you can validate the correctness of a single input field of an entry unit, by using a number of predefined validity predicates.
- Custom validation rules, whereby you can check the correctness of a single field using a predicate not natively provided by WebRatio, or specify and implement validation rules spanning multiple fields of an entry unit. To use custom validation rules you need to implement their business logic. WebRatio will use the code you develop to check the validity of the user input.
Validation occurs at the server-side after the user submits the form: if all fields satisfy the specified validation criteria, the user input is considered valid; otherwise the submitted form is redisplayed with error messages next to each incorrect input.
You can attach as many validation rules as you want to a field; they must all evaluate to TRUE, for the input to be accepted and the requested navigation to take place.
The same process is performed for the rules defined directly on Entry Units and on Multi Choice Index Units in order to validate the whole form.
Defining validation rules on fields
We are now ready to see validation rules in action. Suppose you want to add to your project a page to test how each validation rule works.
- Open your project and add a new Page.
- Add an Entry Unit to the page.
- Add a Field to the Entry Unit. Right click on the Entry unit and choose the Add Field command.
- Add a Validation Rule to the field. In the Outline, right click on the field and choose the Add Validation Rule command (Add Check Validation command if the field is a multi selection field).
The properties that permit to configure a Validation Rule are:
- Name: The user-defined validation rule name. It is good practice to choose meaningful names for validation rules.
- Predicate: The comparison operator used to build the validity predicate that the user input must satisfy. The built-in operators can be applied to a validation rule associated with a single field, selection field or multi selection field.
- Value: a user-defined constant to be used in the logical condition checked by the validation rule.
- Error Message: a user-defined text that is displayed to the user when validation fails. The special keywords '{0}' and '{1}' inserted in the error message text are replaced at runtime respectively by the name of the field and by the value property.
Rules Predicates and Values
The following table describes the configuration of the validation rule for each predicate. This predicate are provided for Fields and Selection Fields
| PREDICATE | DESCRIPTION | VALUE | IS VALUE REQUIRED? |
|---|---|---|---|
| Begins With | The value of the field must start with the defined value. | A | Yes |
| Boolean | The value of the field must be a valid boolean value in respect to the settings for the locale, the true and false values. The value field defines the valid values for the 'true' and the 'false'. | t|f: the first value is the valid 'true' value and the second one is the 'false' value. | No |
| Byte | The value of the field must be a valid byte. | No values to set. | No |
| Contains | The value of the field must contains the specified value or a set of values. For instance, if you want that the value contains 'A' and 'B', you have to specify it in the value property. | A for single value, A|B or A;B for multiple values. | Yes |
| Credit Card | The value of field must be a valid credit card number. | No values to set. | No |
| Custom Rule | The validation rule refers to a user-defined validation predicate and not a built-in validation predicate. This means that you have to specify, as Class Name property, the fully qualified name of a class. The class must be implemented by the user and it must contain the code to validate the form. | No values to set. | No |
| Date | The value of the field must be a valid date. The value must respect the settings for the locale. For instance, if the locale value wants the 'yyyy-MM-dd' format, the field value can be 2008-02-01. If you want that the inserted date has a specified pattern, you can define it in the value property. | yy-M-d: the date results in '08-2-1' | No |
| Decimal | The value of the field must be a valid decimal number. The format of the value must respect the settings for the locale. For instance, if the locale value wants the '.' for decimal separator, the number must have the format 0.19. If you want that the inserted number has a specified pattern, you can define it in the value property. | #.##: The value is truncated at the second decimal digit. | No |
| The value of the field must be a valid email address | No value to set. | No | |
| Ends With | The value of the field must end with the specified value. | A | Yes |
| Equal | The value must be equal to the specified value. | My value | Yes |
| Equal to Field | The value must be equal to the value of a second field. The value is the identifier of the field whose value is used to validate the current field. | fld1: the id property of the field. | Yes |
| Float | The value of the field must be a valid float number. The format of the value must respect the settings for the locale. For instance, if the locale value wants the '.' for decimal separator, the number must have the format 0.19. If you want that the inserted number has a specified pattern, you can define it in the value property. | #.##: The value is truncated at the second decimal digit. | No |
| Float Range | The value of the field must be a valid float number included in the specified minimum and maximum value. | 0|0.99: the first value corresponds to the minimum value and the second one to the maximum value. | Yes |
| Greater or Equal | The value of the field must be greater or at least equals to the specified value or to the value specified in another field (not selection field). | 100: for a comparison between values; fld1: for a comparison between fields. | Yes |
| Greater Than | The value of the field must be greater than the specified value or to the value specified in another field (not selection field). | 100: for a comparison between values; fld1: for a comparison between fields. | Yes |
| In | The value of the field must be equal to one of the specified values, or to the values provided by coupling. | 1|2|3|4 | No |
| Integer | The value of the field must be a valid integer number. The format of the value must respect the settings for the locale. For instance, if the locale value wants the '.' as thousand separator, the number must have the format 1.000. If you want that the inserted number has a specified pattern, you can define it in the value property. | 00: add to zero digits at the beginning of the number (e.g. 001) | No |
| Int Range | The value of the field must be a valid integer number included in the specified minimum and maximum value. | 0|100: the first value corresponds to the minimum value and the second one to the maximum value. | Yes |
| Less or Equal | The value of the field must be less or at least equals to the specified value or to the value specified in another field (not selection field). | 100: for a comparison between values; fld1: for a comparison between fields. | Yes |
| Less Than | The value of the field must be less than the specified value or to the value specified in another field (not selection field). | 100: for a comparison between values; fld1: for a comparison between fields. | Yes |
| Long | The value of the field must be a valid long number. | No value to set. | No |
| Match | The value of the field must match the specified regular expression. A regular expressions is a method for specifying in a compact way complex string searches. Explaining the full potentials of regular expressions is outside the limits of this article but you can have more information at this page | ^[0-9]{3}-[0-9]{7}$: the input is a sequence of three digits, followed by a trait, followed by seven more digits, like in a phone number. | Yes |
| Max Length | The number of character of the field value must be at most as the specified value. | 6 | Yes |
| Min Length | The number of character of the field value must be at least as the specified value. | 3 | Yes |
| Not Equal | The value of the field must not be equal to the specified value. | 0 | Yes |
| Not Contains | The value of the field must not contain the specified value or values.For instance, if you want that the value doesn't contain 'A' and 'B', you have to specify it in the value property. | A for single value, A|B for multiple values. | Yes |
| Not Equal to Field | The value must not be equal to the value of a second field. The value is the identifier of the field whose value is used to validate the current field. | fld1: the id property of the field. | Yes |
| Not In | The value of the field must not be equal to any of the specified values, or to the values provided by coupling. | 1|2|3|4 | No |
| Not Null | The value of the field must not be an empty string. It is considered as empty string also the whitespace. | No value to set. | No |
| Null | The value of the field must be an empty string. It is considered as empty string also the whitespace. | No value to set. | No |
| Short | The value of the field must be a valid short number. | No value to set. | No |
| Time | The value of the field must be a valid time. The value must respect the settings for the locale. For instance, if the locale value wants the 'hh:mm:ss' format, the field value can be 08:10:50. If you want that the inserted time has a specified pattern, define it in the value property. | hh:mm:ss: the time results in '08:10:50' | No |
| Timestamp | The value of the field must be a valid timestamp. The value must respect the settings for the locale. For instance, if the locale value wants the 'yyyy-MM-dd hh:mm:ss.SSS' format, the field value can be 2008-07-06 08:10:50.000. If you want that the inserted date has a specified pattern, define it in the value property. | yy-M-d hh:mm:ss.SSS: the timestamp results in '08-7-6 08:10:50.000' | No |
The predicate values provided for Multi Selection Fields are:
| PREDICATE | DESCRIPTION | VALUE | IS VALUE REQUIRED? |
|---|---|---|---|
| Min Checked | The number of instances checked must be at least as defined in the value property. | 2 | Yes |
| Max Checked | The number of instances checked must be at most as defined in the value property. | 6 | Yes |
| Match Checked | The number of checked instances must be equals to the defined value property. | 3 | Yes |
| Custom Rule | The validation rule refers to a user-defined validation predicate and not a built-in validation predicate. This means that you have to specify, as Class Name property, the fully qualified name of a class. The class must be implemented by the user and it must contain the code to validate the form. | 3 | Yes |
Defining Validation Rules on Entry Units
In order to add a validation rule to an Entry unit, right click on the unit and choose the Add Validation Rule command. The property panel for the Validation Rule on Entry Unit appears like in the image on the right. Note that the Value property is not in the panel because the validation refers to the whole form and not to a single field.
| PREDICATE | DESCRIPTION |
|---|---|
| Form Not Empty | All the fields of the form must not be empty when the form is submitted. At least one field must have a value. |
| Custom Rule | The validation rule refers to a user-defined validation predicate and not a built-in validation predicate. This means that you have to specify, as Class Name property, the fully qualified name of a class. The class must be implemented by the user and it must contain the code to validate the form. |
Defining Validation Rules on Multi Entry Units
In order to add a validation rule to a Multi Entry unit, right click on the unit and choose the Add Validation Rule command. The property panel for the Validation Rule on a Multi Entry Unit appears like in the image on the right. The value property is used not to validate the value of a single field, but to validate the whole form. In particular, it is used to control if the number of checked instances corresponds to the wanted number. N.B. The validation rule can be applied only if the unit is rendered with checkboxes that permit to choose which instances to commit.
| PREDICATE | DESCRIPTION | VALUE | IS VALUE REQUIRED? |
|---|---|---|---|
| Min Checked | The number of instances checked must be at least as defined in the value property. | 2 | Yes |
| Max Checked | The number of instances checked must be at most as defined in the value property. | 6 | Yes |
| Match Checked | The number of checked instances must be equals to the defined value property. | 3 | Yes |
| Custom Rule | The validation rule refers to a user-defined validation predicate and not a built-in validation predicate. This means that you have to specify, as Class Name property, the fully qualified name of a class. The class must be implemented by the user and it must contain the code to validate the form. | 3 | Yes |
Defining Validation Rules on Multi Choice Index Units
In order to add a validation rule to a Multi Choice Index unit, right click on the unit and choose the Add Check Validation command. The property panel for the Validation Rule on a Multi Choice Index unit appears like in the image on the right. The value property is used not to validate the value of a single field, but to validate the whole form. In particular, it is used to control if the number of checked elements corresponds to the wanted number.
| PREDICATE | DESCRIPTION | VALUE | IS VALUE REQUIRED? |
|---|---|---|---|
| Min Checked | The number of instances checked must be at least as defined in the value property. | 2 | Yes |
| Max Checked | The number of instances checked must be at most as defined in the value property. | 6 | Yes |
| Match Checked | The number of checked instances must be equals to the defined value property. | 3 | Yes |
| Custom Rule | The validation rule refers to a user-defined validation predicate and not a built-in validation predicate. This means that you have to specify, as Class Name property, the fully qualified name of a class. The class must be implemented by the user and it must contain the code to validate the form. | 3 | Yes |
Customizing error messages
You can change the default message issued by WebRatio in response to an invalid input, by exploiting the Error Message property of the Validation Rule. The special keyword {0} is replaced at runtime by the name or id of the field in the entry unit, instead the keyword {1} is replaced with the value you specify as value property. Note that you must write these keywords as illustrated.
It is also possible to localize the custom message in the Localization dialog. Right-click on the entry unit and insert the localized message for each language in the cell near the name of the Validation rule.
