You can use widgets to validate input in XForms elements. The Simple Forms Validator widget checks if the value in a single XForms field is valid. The Multiple Forms Validator checks that the values in multiple fields, taken together, meet some specified constraints.
You can use widgets to validate input in XForms elements. The Simple Forms Validator widget checks if the value in a single XForms field is valid. The Multiple Forms Validator checks that the values in multiple fields, taken together, meet some specified constraints.
Neither widget is visible until invalid input is detected. When validation fails, the widget presents a message or other visual cues to the user to indicate the nature of the failure.
Validation will be triggered when the user tries to move focus to another control, or by another widget, especially the Forms Wizard widget, which will trigger validation for each wizard step as well as the final completion step.
For simple validation, the widget:validate element is a child of the xforms:input element. For multiple validation, the widget:multiple-validator acts as a container for the widget:validate element and multiple widget:field elements. Either a global message, or control-specific messages are provided server-side.
Failed validation messages are displayed, either in a Popup widget instance identified by the message-popup attribute on the widget:validate element, or in a form element. If the message-area attribute is not specified with a related message-popup attribute, or if it is specified but does not refer to a content element within a popup, the popup will be displayed with its static content. If the message-area attribute is not specified for a form element and the mcs-validation-error-action style property contains 'message', the message text will be displayed in the browser message dialog.
The auto attribute determines whether or not validation is performed automatically after the user moves focus out of the input control. Possible values are 'yes' (default) and 'no'.
In a simple validator, the widget:message element contains the message to be displayed when a particular type of error occurs. The content of the element referred to in the message-area attribute will be replaced with the widget:message element content. When validation passes, the content will be cleared. Supported message type attribute values are 'invalid' (default) and 'empty'.
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget"
xmlns:xforms="http://www.w3.org/2002/xforms"
xmlns:si="http://www.volantis.com/xmlns/2006/01/xdime2/si">
<head>
<title>widget:validate</title>
<style type="text/css">
#name {
mcs-validation-error-action: message;
mcs-input-format: 'M:Xxxx*x';
}
#pin {
mcs-validation-error-action: message;
mcs-input-format: 'N:######';
}
</style>
<xforms:model>
<xforms:instance>
<si:instance>
<si:item name="name"/>
<si:item name="pin"/>
</si:instance>
</xforms:instance>
<xforms:submission id="submit" action="."/>
</xforms:model>
</head>
<body>
<p>
<xforms:input ref="name" id="name">
<xforms:label>Name</xforms:label>
<widget:validate message-area="formMessage1">
<widget:message type="empty">The name cannot be empty! </widget:message>
<widget:message type="invalid">The name must be at least 4 characters and start with an
uppercase character!</widget:message>
</widget:validate>
</xforms:input>
<span id="formMessage1"/>
</p>
<p>
<xforms:input ref="pin" id="pin">
<xforms:label>PIN</xforms:label>
<widget:validate message-area="formMessage2">
<widget:message type="empty">PIN cannot be empty!</widget:message>
<widget:message type="invalid">PIN must consist of 6 digits!</widget:message>
</widget:validate>
</xforms:input>
<span id="formMessage2"/>
</p>
</body>
</html>In a multiple validator, the widget:field elements contains references in the ref attribute to the XForm controls to be validated as a group. The src attribute is used to specify the URL of a page that handles multiple forms validation. No validation will occur if this attribute is not specified.
It is an error to specify a src attribute on widget:validate element in a the Simple Forms Validator.
<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget"
xmlns:xforms="http://www.w3.org/2002/xforms"
xmlns:si="http://www.volantis.com/xmlns/2006/01/xdime2/si">
<head>
<title>widget:multiple-validator</title>
<xforms:model>
<xforms:instance>
<si:instance>
<si:item name="name"/>
<si:item name="pin"/>
</si:instance>
</xforms:instance>
<xforms:submission id="submit" action="."/>
</xforms:model>
<widget:script id="validate-script">
$W('myValidator').addSuccessCallback(function(){
$W('formMsgSuccess').setContent("Validation succeeded.")});
$W('myValidator').addFailureCallback(function(){
$W('formMsgSuccess').setContent("Validation failed.")});
$W('myValidator').validate()
</widget:script>
</head>
<body>
<div>
<widget:display id="formMsgSuccess"/>
</div>
<div>
<xforms:input ref="name" id="name">
<xforms:label>Name</xforms:label>
</xforms:input>
<xforms:input ref="pin" id="pin">
<xforms:label>PIN</xforms:label>
</xforms:input>
<widget:button id="formButton" action="validate-script#invoke">Validate</widget:button>
<widget:multiple-validator id="myValidator">
<widget:field ref="name"/>
<widget:field ref="pin"/>
<widget:validate message-area="formMessage"
src="http://localhost:8080/mcs/projects/client-app/service/validator"/>
</widget:multiple-validator>
</div>
</body>
</html>The following is an example of the properly formated widget response. Please see Widget response structure for more information.
If validation fails, the validation service response should have the following form.
<?xml version="1.0" encoding="UTF-8"?>
<response:response xmlns="http://www.w3.org/2002/06/xhtml2"
xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
xmlns:response="http://www.volantis.com/xmlns/2006/05/widget/response">
<response:head>
<response:link rel="mcs:theme" href="/main.mthm"/>
</response:head>
<response:body>
<response:validation result="failed">
<response:message>Validation failed</response:message>
<response:field ref="pin">
<response:message>PIN must be exactly 6 digits long</response:message>
</response:field>
<response:field ref="name">
<response:message>Name must be at least 4 characters long</response:message>
</response:field>
</response:validation>
</response:body>
</response:response>In case of successful validation, the service must return the response in the following form.
<?xml version="1.0" encoding="UTF-8"?>
<response:response xmlns="http://www.w3.org/2002/06/xhtml2"
xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
xmlns:response="http://www.volantis.com/xmlns/2006/05/widget/response">
<response:head>
<response:link rel="mcs:theme" href="/main.mthm"/>
</response:head>
<response:body>
<response:validation result="passed"/>
</response:body>
</response:response>The mcs-validation-error-action style property controls actions that will occur after validation failure. Possible values are 'none', 'focus', and 'message'. If the value is 'message', the message text will be displayed in the browser message dialog.
If you have more than one validator on the same page, you should not set the mcs-validation-error-action property to 'focus' in conjunction with an auto attribute value of 'yes', as it may lead to an infinite loop of focus and blur events.
Use the 'focus' value with caution. If applied, it will prevent the user from moving focus until the input is correct.
To specify style changes that will be applied after validation has failed you should use the :mcs-invalid pseudo-class.
You cannot change the style of the xforms:label element as a response of validation failure, using :mcs-invalid.
If the device does not support JavaScript, -wap-input-format and -wap-input-required could be used to support internal wap input field validation.
Both widgets support JavaScript. See JavaScript support for details.