4.5. Validating a form

Form instance data

This time the form data model specifies two items: 'name' and 'PIN'.

Create a simplevalidator.xdime file

Enter the required xforms:model element in the head section of the page. The xforms:submission identifies the (imaginary) URI to be used when submitting the data.

<xforms:model>
  <xforms:instance>
    <si:instance>
      <si:item name="name"/>
      <si:item name="pin"/>
    </si:instance>
  </instance>
  <xforms:submission id="submit" action="http://example.com/response/pin.xdime"/>
</xforms:model>

Ensure that you refer to the validator.mthm in a link element. The validation rules are defined by the mcs-input-format property specified in the theme, and so are the message styles. See 2.8. Additional themes for more information.

Using forms validator widgets

Enter 'Simple Form Validator' as the title value in the template:binding element

In the content section of the page, add a help text and a div element with the layout style specification

<template:complexValue>Please enter a name and PIN
   <div style="mcs-layout: 'layouts/validator.mlyt';">
   ...
   </div>
</template:complexValue>

The widget:validate element must be enclosed by the xforms:input XForms element for which validation should occur. The message-area attribute specifies an element used to display a text message in case validation fails. In our example it points to the following span element.
```
<xforms:input ref="name" id="name">
  <xforms:label>Name</xforms:label>
  <widget:validate message-area="formMessage1">
  ...  
  </widget:validate>
</xforms:input>
<span id="formMessage1"/>
...
```
The contained widget:message elements hold messages to be displayed when form validation fails, either because the input field is empty, or because the entered value is incorrect. The type attribute settings for each message determine the outcome. Enter the following values for the messages.
```
<widget:message class="error" type="empty">The name cannot
  be empty!</widget:message>
<widget:message class="error" type="invalid">The name must be at least 4
   characters and start with an uppercase character!</widget:message> 
```

Complete XDIME 2 code

Finally, add the XML representing the PIN input. Your file, simplevalidator.xdime, should look like this.

<?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:xforms="http://www.w3.org/2002/xforms"
  xmlns:si="http://www.volantis.com/xmlns/2006/01/xdime2/si"
  xmlns:urid="http://www.volantis.com/xmlns/marlin-uri-driver">
  <head>
    <title>Simple 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="http://example.com/response/pin.xdime"/>
    </xforms:model>
  </head>
  <body>
    <template:apply href="templates/demo-main.xdtpl">
      <template:binding name="title" value="Simple Form Validator"/>
      <template:binding name="content">
        <template:complexValue>Please enter a name and PIN
        <div style="mcs-layout: 'layouts/validator.mlyt';">
          <xforms:input ref="name" id="name" style="mcs-container: 'input1'">
            <xforms:label style="mcs-container:'text1'">Name</xforms:label>
            <widget:validate message-area="formMessage1">
              <widget:message class="error" type="empty">
                The name cannot be empty!</widget:message>
              <widget:message class="error" 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" style="mcs-container: 'message1'"/>
          <xforms:input ref="pin" id="pin" style="mcs-container: 'input2'">
            <xforms:label style="mcs-container: 'text2'">PIN</xforms:label>
            <widget:validate message-area="formMessage2">
              <widget:message class="error" type="empty">PIN cannot
                be empty!</widget:message>
              <widget:message class="error" type="invalid">PIN must consist of 6
                digits!</widget:message>
            </widget:validate>
          </xforms:input>
          <span id="formMessage2" style="mcs-container: 'message2'"/>
        </div>
        </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.
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:message	Message displayed when particular type of validation error occurs. This element is used by the Simple Validator widget. It should not be specified for a Multiple Forms Validator widget because a server side process is responsible for displaying error messages.
widget:validate	Enables form validation in both the Simple and Multiple Forms Validator widgets.
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.