ShowTable of Contents
Introduction
This article will explain what validation is and why it is used on an XPage.
The reader will learn where on an XPage validation can be used, how to add simple validation to an XPage and how to build up some more advanced, customized validators.
Validation on An XPage
Validation is verification of any data which has been inputted by a user.Validation can be used on any control on an XPage, which accepts user input.
At a simple level, validation can be used to verify that:
- required data has been inputted.
- the correct data has been inputted.
Basic validation can be useful for checking for simple errors on a page. For example, that a user has filled out mandatary fields on a form such as their name, address, date of birth or that a password contains the correct number of characters.
However, a number of more advanced validators are available for use on an XPage. These can be used as a more advanced form of verifying the correct data has been entered. For example, that an email address is of the form
"johndoe@ibm.com". These are fully customizable, through use of JavaScript, Regular Expressions or Expression Language (EL) scripting and allow for custom validation on an XPage.
Simple Validation
Simple validation can be specified for the data input controls on which validation is commonly used. These include:
An Edit Box control.
A Multi-line Edit Box control.
A File Upload control.
A Date Time Picker control.
Simple validation can be applied through the
Properties -> Validation Tab in the Domino Designer Environment. Simple validation includes verifying the required data has
been inputted and verifying that the correct data has been inputted.
Specifying data as required
A control can be specified as a required field, using the
Properties -> Validation Tab in Domino Designer.
A user must input data into this control.
A user can create their own customizable error message. This message is localizable using the standard localization capability of XPages, so developers don't have to worry about specifying it when creating the XPage.
Specifying data which has a required input format
A control can be specified as having a required input format , using the
Properties -> Validation Tab in Domino Designer.
The required format is determined based on whether the input is in the form of a string, date/time, number or mask.
An xp converter is used to convert the data input before validation is specified for the control.
The validation dialog box displayed is dependent on this converter, as to which of the corresponding dialog boxes display. Each of these are shown below:
xpConvertString
xpConvertDateTime
xpConvertNumber
xpConvertMask
Advanced Validation Using All-Properties
More advanced, fully customizable validation can be specified for all data input controls.
This form of validation can be applied through the
Properties -> All Properties -> Data -> Validators in the Domino Designer Environment.
A number of customizable validators are available to the developer for use on an XPage, outlined below:
Validate Required
Validate that user input which is required, has been entered on an XPage.
Attributes which can be customised
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
Validate Length
Validate user input against a maximum and minimum character length.
The length or data entered is verified to ensure it is greater than or equal to the minimum character length allowed and/or less than or equal to the maximum character length allowed.
Attributes which can be customised
|
|
specified by a numeric value.
|
|
|
specified by a numeric value.
|
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
The Length validator uses the default xpConvertString converter.
Validate Date/Time Range
Validate user input against a maximum and minimum date/time value.
The date/time value is verified to ensure it is greater than or equal to the minimum date/time allowed and/or less than or equal to the maximum date/time allowed.
Attributes which can be customised
|
|
specified by yyyy/mm/dd hh:mm:ss.
|
|
|
specified by yyyy/mm/dd hh:mm:ss.
|
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
The xpConvertDateTime convertor must also be specified here such that user input is converted to date/time format. Otherwise the user input is treated as a 'string'.
See
the article on
Converters on an XPage for further information.
Validate Double Range
Validate user input against a maximum and minimum number of type double.
The numeric value is verified to ensure it is greater than or equal to the minimum numeric value allowed and/or less than or equal to the maximum numeric value allowed.
Attributes which can be customised
|
|
specified by a numeric value.
|
|
|
specified by a numeric value.
|
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
The xpConvertNumber convertor must also be specified here such that user input is converted to numeric format. Otherwise the user input is treated as a 'string'.
See
the article on
Converters on an XPage for further information.
Validate Long Range
Validate user input against a maximum and minimum number of type long.
The numeric value is verified to ensure it is greater than or equal to the minimum numeric value allowed and/or less than or equal to the maximum numeric value allowed.
Attributes which can be customised
|
|
specified by a numeric value.
|
|
|
specified by a numeric value.
|
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
The xpConvertNumber convertor must also be specified here such that user input is converted to numeric format. Otherwise the user input is treated as a 'string'.
See
the article on
Converters on an XPage for further information.
Validate Constraint
A Constraint validator validates user input using a Regular Expression that describes the form of the input box.
What are Regular Expressions?
Regular Expressions describe a set of strings based on some common characteristics or pattern.
A Regular Expression can be specified as Server-side, which uses the Java
(java.util.regex) API or Client-side, which uses the browser JavaScript Regular Expression Engine.
Client-side and Server-side Regular Expression syntax is similar, but there are differences that a user must be aware of.
See the following articles for syntax guidelines for both:
- The Sun Java Doc, Pattern Class for Java Regular Expression Syntax.
- The Mozilla Developer Center article, Regular Expressions for JavaScript Regular Expression Syntax.
One important point to note is since Java code uses a similar syntax to regular expressions, some unavoidable character clashing will occur when using the Server-side
java.util.regex API for Regular Expressions.Any backslash delimited metacharacters need to be escaped. For example:
The regular expression:
( \ ... ) @ ( \ ...) ( \ . \ ..... ) *
would have to be re-written as:
( \ \.....) @ (\ \ .....) (\ \ .\ \ ...... ) *
For more on Java Regular Expressions, see the Sitepoint article on
The Java Regex API
For a good tutorial on the
java.util.regex API regular expressions, see the Java Tutorial on
Regular Expressions.
For more on JavaScript Regular Expressions, see the w3chools doc on
JavaScript RegExp Object
For a good tutorial on JavaScript Regular Expressions, see this JavaScript tutorial on
Regular Expressions
Attributes which can be customised
|
|
is the regular expression which is specified to limit the type of characters that the user can input.
Examples:
[A-Za-z]* : Alphabet characters only.
[0-9]* : Digits only.
[A-Za-z]{2,4} : Alphabet characters, between 2 and 4 characters in length, only.
|
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
The Constraint validator uses the default xpConvertString converter.
Example of a Constraint Validator
The following code details the use of a constraint validator.
The constraint validator is specified using the
regex attribute and states that inputted data must be of the form: ^[A-Za-z0-9._%-]*@[A-Za-z0-9]*.[A-Za-z]{2,4}, which is the format of an email address.
<xp:inputText id="Textbox">
<xp:this.validators>
<xp:validateConstraint
message="Email address is incorrect.... must be of the form johndoe@ibm.com">
<xp:this.regex><![CDATA[^[A-Za-z0-9._%-]*@[A-Za-z0-9]*.[A-Za-z]{2,4}]]></xp:this.regex>
</xp:validateConstraint>
</xp:this.validators>
</xp:inputText>
Validate Expression
Validates user input against a regular expression.
Attributes which can be customised
|
|
customised script which is executed on the client.
|
|
|
is the Expression Language (EL) expression used to validate the user input. The user input is valid if it matches the expression. Otherwise, it is invalid.
|
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
For a good tutorial on Expression Language, see the Java j2EE tutorial on
Expression Language
Example of an Expression Validator
The following code details the use of an expression validator.
The example uses both a client-side and a server-side expression validator.
A Server-side expression validator is specified using the
expression attribute and its formula has the form :
A Client-side expression validator is specified using the
ClientScript attribute and its formula has the form:
This example has both server-side and client-side JavaScript expressions:
<xp:inputText id="Textbox">
<xp:this.validators>
<xp:validateExpression>
<xp:this.expression><![CDATA[#{javascript:value=="ABC"}]]></xp:this.expression>
<xp:this.message><![CDATA[Data entered must be 'ABC']]></xp:this.message>
<xp:this.clientScript><![CDATA[value=="ABC"]]></xp:this.clientScript>
</xp:validateExpression>
</xp:this.validators>
</xp:inputText>
Validate Modulus Self-Check
Validate user input to ensure it passes the IBM Modulus 10 or IBM Modulus 11 Self-Check Algorithm.
IBM Modulus 10 and Modulus 11 Self-Check Algorithm
These algorithms checks to ensure data entered in a data field passes the IBM Modulus 10 or Modulus 11 self-check algorithms, depending on which algorithm is specified.
The inputted data is split into 2 parts:
- A base number
- A check digit
For example, the following 8-digit number 89812231 is entered.
The number is spilt into two parts: a base number and a check digit:
8 9 8 1 2 2 3 1
base number check digit
The inputted number (base number + check digit) is validated using a mathematical algorithm which takes the base number, does some mathematical calculations on this number. The result must match the check digit, in order to verify the inputted number.
Sensitive numbers, such as credit card numbers, contain a self-check digit, which can be validated using this method.
For more about the IBM Modulus 10 and Modulus 11 Self-Check Algorithm, see the IBM iseries Information center doc on DDS Reference and search for "Modulus 10".
Attributes which can be customised
|
|
specifies which IBM Modulus Self Check Algorithm to use.
Entering 10 specifies the IBM Modulus 10 Self-check Algorithm is to be used.
Entering 11 specifies the IBM Modulus 11 Self-check Algorithm is to be used.
|
|
|
is optional. Specifies the validation error message to be displayed to the user. A custom validation error message can be entered here. Otherwise, the default error message is displayed.
|
The xpConvertNumber convertor must also be specified here such that user input is converted to numeric format. Otherwise the user input is treated as a 'string'.
See
the article on
Converters on an XPage for further information.
Custom Validator
Validates user input using a custom script, written using JavaScript, Expression Language (EL) or custom scripting tools.
A Custom Validator can be written using one or more of the xp: validators included in
All Properties.
The following example validates two input fields,
Password and
ConfirmPassword, such that the Password and ConfirmPassword values must match exactly.
The example uses a number of validators:
1. Two
xp:validaterequired validators which specifies field as required.
2. A
xp:validateexpression validator which specifies the server-side expression validator, verifying the value of
Password and
ConfirmPassword match
. A useful function for retrieving inputted values which are submitted to the server for validation, is the
getComponent("inputTextID").getSubmittedValue() function. The getComponent() function can be found in the JavaScript Editor under Global Functions.
3. A
xp:validateconstraint validator is used below to specify the form the password must have.
//"Enter Password" Input Field
<xp:inputText id="Password" value="#{sessionScope.Password}" required="true"
disableClientSideValidation="true"password="true">
<xp:this.validators>
<xp:validateRequired message="Can't be blank"></xp:validateRequired> <!-- (1) -->
<xp:validateExpression message="Passwords Must Match"> <!-- (2) -->
<xp:this.expression><![CDATA[#{javascript:
if (getComponent("Password").getSubmittedValue() != getComponent("ConfirmPassword").getSubmittedValue())
{
return false;
}
else
{
return true;
}
}]]></xp:this.expression>
</xp:validateExpression>
<xp:validateConstraint> <!-- (3) -->
<xp:this.message><![CDATA[Must be 7 to 20 characters [a-z][A-Z][0-9]]]></xp:this.message>
<xp:this.regex><![CDATA[[a-zA-Z0-9]{7,20}]]></xp:this.regex>
</xp:validateConstraint>
</xp:this.validators>
</xp:inputText>
<xp:td><xp:message id="message3" for="Password"></xp:message></xp:td>
//"Confirm Password" Input Field
<xp:inputText id="ConfirmPassword" password="true" required="true"
value="#{sessionScope.PasswordCheck}">
<xp:this.validators>
<xp:validateRequired message="Can't be blank"></xp:validateRequired> <!-- (1) -->
</xp:this.validators>
</xp:inputText>
//"Validate" Button
<xp:button value="Validate" id="validate"></xp:button>
More Advanced Custom Validation
More advanced custom validators can be specified using the xspClientDojo library.
The xp: validators, outlined above, reside within this library.
A user can however, create their own validator and reference this validator from within an XPage Source Code in the Domino Designer environment.
See the article on
Client Side JavaScript Libraries in XPages for how to define a new custom validator script within the xspClient Dojo Library and add this script to an XPage.
Displaying Validation errors on An XPage
If a user inputs invalid data into any of the controls which has validation associated with it, a validation error message must display to the user.
This validation error message displayed will either be the default validation error message or the user-defined validation error message as specified by the developer using the
message attribute.
How validation errors display on an XPage is dependent on whether validation is specified as Client-side or Server-side.
Client-side Validation Errors
Validation specified as Client-side will result in the displaying of validation errors within a pop-up dialog box on the page itself, as shown below:
Note
The displaying of this dialog box is as a result of a call been made to a function within the xspClientDojo.js library, in response to a client-side validation error.
A more advanced validation error message can be specified by replacing this function with some custom javascript, which displays an alternative client-side error message.
For example, a Dojo tooltip could be displayed instead.
See the corresponding article
Client Side JavaScript Libraries in XPages for more on the xspClientDojo library.
Server-side Validation Errors
Validation specified as Server-side, must ensure that any control, which has validation enabled, has an associated
Display Error control
or
the page itself must have a
Display Errors control, in order to display all validation errors associated with that page.
On a
Display Error Control, you can set a property to "show error messages for" the control on which validation is enabled by selecting the control from a list.
Any validation errors associated with that control will display when invalid data is inputted.
On a
Display Errors Control, any validation errors associated with all controls on the XPage will display when invalid data is inputted.
There does not need to be a direct association between a control and a
Display Errors control.
Any validation error messages will display on either error control, as shown below:
See the corresponding article on
Error Management in XPages for more on the validation error messages.
Validation, as a default, will occur Client-side, unless otherwise specified by the developer. Either method of validation, Client-side or Server-side, will result in the displaying of the associated error message(s) to the user, informing them of the input of invalid data. The user is allowed to re-submit data until all validators are satisfied and no further validation error messages are displayed to the user.