Defining cross-field validation in a form

Cross-field Validation is used to validate multiple fields in a form if their values are correlative.

For example, on most account registration forms, there are two password inputting fields. In order to avoid customers inputting wrong password accidentally, both fields must have the same value before the form can be submitted.

Defining xValidation in XUI editor

Cross-field validation process in client side and server side

Synchronizing the isMandatory values of form inputs between client and server

xValidationErrorHandler interface

Editing the properties of the XUI widgets

You can use xValidation section in Form widget to define cross-field validation easily. This page will provide the detailed process.

The cross-field validation from server side are enabled by default. Make sure these codes are in btt.xml:

In Condition, users can define how multiple correlative fields in a cross-field validation are valid or not valid, and the hint message will to be shown if values of correlative fields are not valid.

Note To directly provide codes for cross-validation on server side, see Performing cross-field validation.

To define a cross-field validation, do the following steps:

▪ In the Project Explorer View, open a XUI file and select the form which you want to define cross-field validation.

▪ In the xValidation tab of Properties view, click the Add icon

to add a new xValidation rule.

Headless xValidation has a small decoration beside it.

▪ In Basic tab of Details section, input the name and the hint message which will be shown when the values of correlative fields are not valid in Hint field. Hint message supports NLS, you can select NLS element by clicking Browse button. Choose to define either invalid condition or valid condition by clicking the "Invalid condition" checkbox.

▪ Select Condition tab of Details section to define condition of this validation. You can either choose Widget Function, Widget Property, Expression or Global Function to define the condition of this cross-field validation, and then click Apply Value to confirm.

Defining cross-field validation in a form

The validation can be executed from both client side and server side. This page will introduce the validation process and rules in both client-side and server-side.

In client-side, when any field in the form is changed (lost focus), the form will directly invoke the xValidation rules developers have defined and selectively pop up the hint message. Until all the cross-field validations are valid, submit buttons in the form will be disabled and no data can be submitted to the server.

When a cross-field validation rule is not valid, and there is no single-field validation failed, the hint message of the invalid cross-field validation rule will be shown. If a form has multiple cross-field validation rules, and more than one rules are not valid, only one hint message of invalid rule will be selected and shown on the form. The message of invalid rules is selected according to:

▪ If the last changed field is belonged to a cross-field validation rule, and all other fields in the rule have their values.

▪ If no rule can be found in 1, then choose the first invalid rule according to definition sequence.

If the client-side validation are accidently shut down or hacked by purpose, the form is submitted to the server. Then the server-side validation will be invoked.

Among all the xValidation rules you have defined, headless xValidation will be generated into a file under the definitions.operation folder.

In the server side, only the headless xValidation rules will be executed.

Headless xValidation has headless conditions, including:

Widget	headless property
TextBox	value
Combo	value
Radio	value
Checkbox	isChecked
SelectList	value
MultiSelect	value
CheckedMultiselect	value
EnhancedMultiselect	value
RichText	value
TextArea	value
Tree	value
HiddenField	value

▪ Global function: all functions available at the server side, as defined in their configuration, are headless

When a cross-field validation rule is not valid in the server side, an error message page will be shown.

Defining cross-field validation in a form

1 Enable the cross-field validation from server side are enabled by default. Make sure these codes are in btt.xml:

If ECA condition is the headless condition and it only contains action (include true/false actions) which modifies the “isMandatory” value of an input widget, the tooling displays a decoration icon in the ECA rule Label but not in the rest of ECA rules. The <mandatories> ID is same with the ECA rule ID.

An xml file that contains the ECA rules will be generated in definitions/operations/. Keep the feature on and then the server side will use the ECA rules in this file to update the isMandatory properties.

Defining cross-field validation in a form

You can implement the xValidationErrorHandler interface to handle the x-validation errors.

public interface xValidationErrorHandler {
public void handleError {Exception e, ChannelContext channelCtx, PresentationHandler prsentHandler) ;}
}

You can define xValidationErrorHandler in btt.xml > ChannelHandler > HTML.

If xValidationErrorHandler is not defined in btt.xml > ChannelHandler > HTML, the default handler will be used for server side x-Validation error. The default behavior is to render UDTT error page and print error in browser and in log file.