5.4. Validating multiple forms

XForms elements

The following XForms elements specify the text input field. Its form model may appear anywhere on the XDIME page, but must be placed before any XForms elements that refer to it.
```
<xforms:input ref="name" id="name">
  <xforms:label>Name</xforms:label>
</xforms:input>
```

Using forms validator widgets

widget:multiple-validator is the main element of the widget. It contains a list of the XForms fields which will be validated as a group.

<widget:multiple-validator id="myValidator" class="validable">
  <widget:field ref="name" message-area="formMessage1"/>
  <widget:field ref="pin" message-area="formMessage2"/>
  <widget:validate message-area="formMessage" src="service/validator"/>
</widget:multiple-validator>

The widget:field elements reference the XForms fields which should be validated as a group. The message-area attribute specifies container for the message that will be displayed if validation of the corresponding field fails. In our case, it is the following span element.
```
<span id="formMessage1" class="error" style="mcs-container: 'message1'"/>
```
The widget:validate element specifies the URL address of the service that should be used for validation. Its message-area attribute points to a container for the validation successful message.
```
<span id="formMessage" class="error" style="mcs-container: 'message'"/>
```
The validation rules are defined by the mcs-input-format property specified in the validator.mthm theme. See 2.8. Additional themes for more information.

The widget:button element allows the user to invoke the validation script

<widget:button id="formButton" action="validate-script#invoke">
  Validate</widget:button>

JavaScript support

The widget:script element contains the script to be executed. The validate() method validates the forms.

<widget:script id="validate-script">
  $W('myValidator').addSuccessCallback(function(){
    $W('formMsgSuccess').setContent("Validation succeeded.")});
  $W('myValidator').addFailureCallback(function(){
    $W('formMsgSuccess').setContent("")});
  $W('myValidator').validate()
</widget:script>

addSuccessCallback() and addFailureCallback() set the content of the formMsgSuccess area. The widget:display element presents the message.
```
<widget:display id="formMsgSuccess" style="mcs-container: 'msgSuccess'"/>
```

Widget response structure

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>

The response must contain the validation message, defined by response:message, bound to a field that failed validation via the ref attribute of the response:field element.

In case of successful validation, the service needs to 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>

Complete XDIME 2 code

Create a ajax-validator.xdime file

Modify the ajax-validator.xdime file by including the following code

<?xml version="1.0" encoding="UTF-8"?>
<html xmlns="http://www.w3.org/2002/06/xhtml2"
  xmlns:mcs="http://www.volantis.com/xmlns/2006/01/xdime/mcs"
  xmlns:template="http://www.volantis.com/xmlns/marlin-template"
  xmlns:widget="http://www.volantis.com/xmlns/2006/05/widget"
  xmlns:urid="http://www.volantis.com/xmlns/marlin-uri-driver"
  xmlns:xforms="http://www.w3.org/2002/xforms"
  xmlns:si="http://www.volantis.com/xmlns/2006/01/xdime2/si"
  xmlns:event="http://www.w3.org/2001/xml-events">
  <head>
    <title>AJAX Form Validator</title>
    <link rel="mcs:theme" href="/themes/main.mthm"/>
    <link rel="mcs:theme" href="/themes/validator.mthm"/>
    <link rel="mcs:layout" href="/layouts/main.mlyt"/>
    <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("")});
      $W('myValidator').validate()
    </widget:script>
  </head>
  <body id="body">
    <template:apply href="templates/demo-main.xdtpl">
      <template:binding name="title" value="AJAX Form Validator"/>
      <template:binding name="content">
        <template:complexValue> Please enter a name and PIN. <div
            style="mcs-layout: 'layouts/validator.mlyt';">
            <widget:display id="formMsgSuccess" style="mcs-container: 'msgSuccess'"/>
            <span id="formMessage" class="error" style="mcs-container: 'message'"/>
            <xforms:input ref="name" id="name" style="mcs-container: 'input1'">
              <xforms:label style="mcs-container: 'text1'">Name</xforms:label>
            </xforms:input>
            <span id="formMessage1" class="error" style="mcs-container: 'message1'"/>
            <xforms:input ref="pin" id="pin" style="mcs-container: 'input2'">
              <xforms:label style="mcs-container: 'text2'">PIN</xforms:label>
            </xforms:input>
            <span id="formMessage2" class="error" style="mcs-container: 'message2'"/>
            <widget:button id="formButton" action="validate-script#invoke"
              style="mcs-container: 'button'">Validate</widget:button>
          </div>
          <widget:multiple-validator id="myValidator" class="validable">
            <widget:field ref="name" message-area="formMessage1"/>
            <widget:field ref="pin" message-area="formMessage2"/>
            <widget:validate message-area="formMessage" src="service/validator"/>
          </widget:multiple-validator>
        </template:complexValue>
      </template:binding>
    </template:apply>
  </body>
</html>

Checklist

Name	Purpose
div	A section used to add extra structure to documents. Style sheets can be used to control the presentation.
response:field	Indicates an error on an XForms control for a Multiple Validator widget by a reference to it.
response:message	The message displayed when a particular type of error occurs. Used by the Multiple Forms Validator widget. If enclosed directly within the `response:validation` element, it describes an overall validation failure. If contained by the `response:field` element, it describes a field-specific validation failure.
response:validation	Returns the result of validation. It is used by Multiple Forms Validator widget.
si:instance	Container for data items used to supply initial values for forms controls, or to provide additional data to be submitted with the form.
si:item	Defines an item of instance data that is required if a form control needs to be initialized, or when data not associated with a form control needs to be provided during form submission.
span	Inline element used to set a style.
widget:button	A general purpose element, used by widgets which need a button-like control.
widget:display	An inline widget element used to display some text content. It may be associated with a widget property. In such cases, the displayed content represents the value of the selected property.
widget:field	A reference in a Multiple Forms Validator widget to a single XForm control that is validated as part of the group.
widget:multiple-validator	The main element for a Multiple Forms Validator widget.
widget:script	Contains a script that can be executed by the `invoke` action.
widget:validate	Enables form validation in both the Simple and Multiple Forms Validator widgets.
xforms:group	Combines a set of form controls into a user interface component. By applying theme properties on this element, you can control where form fragmentation occurs, and define or override at runtime the link texts specified on form fragment layouts.
xforms:input	A form control for text input.
xforms:instance	Optional element that contains instance data associated with the `model` element. It is used to supply initial values for forms controls, or to provide additional data to be submitted with the form.
xforms:label	Provides a descriptive label for forms controls.
xforms:model	Represents a form definition, used as a container for elements associated with its submission.
xforms:submission	Defines the information to submit, where it should be sent, and how to send it.
Core attributes	Attributes that are common to XDIME 2 elements.