XForms Basics, Part 2 - Welcome to Immigration (Page 2 of 6 )
I'll begin with a simple XForm, one that you're already familiar with from the previous segment of this tutorial:
<html xmlns=http://www.w3.org/1999/xhtml xmlns:xforms="http://www.w3.org/2002/xforms/cr">
<head>
<!-- form model -->
<xforms:model id="immigration">
<xforms:instance src="immigration.xml" />
<xforms:submission id="submit"
action="/tmp/immigrant.xml" method="put" />
</xforms:model>
<basefont face="Arial">
</head>
<body>
<!-- define interface controls -->
<table cellspacing="5" cellpadding="5"
border="0">
<tr>
<td colspan="2" align="center">
<font color="red" size="4">Welcome to
Immigration</font></td>
</tr>
<tr>
<td>
<xforms:input id="txtname"
model="immigration" ref="/immigrant/name">
<xforms:label>Name</xforms:label>
<xforms:hint>Enter your
name here</xforms:hint>
</xforms:input>
</td>
</tr>
<tr>
<td>
<xforms:input id="txtcitizenship"
model="immigration"
ref="/immigrant/citizenship">
<xforms:label>Citizenship</xforms:label>
<xforms:hint>Enter your country
of origin here</xforms:hint>
</xforms:input>
</td>
</tr>
<tr>
<td align="left">
<xforms:select1 model="immigration"
ref="/immigrant/purpose" appearance="full">
<xforms:label>Purpose of visit</xforms:label>
<xforms:hint>Please state
the purpose of your visit
</xforms:hint>
<xforms:item>
<xforms:label>Business</xforms:label>
<xforms:value>B</xforms:value>
</xforms:item>
<xforms:item>
<xforms:label>Pleasure</xforms:label>
<xforms:value>P</xforms:value>
</xforms:item>
<xforms:item>
<xforms:label>Other</xforms:label>
<xforms:value>O</xforms:value>
</xforms:item>
</xforms:select1>
</td>
</tr>
<tr>
<td align="left">
<xforms:select model="immigration"
ref="/immigrant/immunization"
appearance="full">
<xforms:label>Immunization</xforms:label>
<xforms:hint>Please select the
diseases that you have been
immunized against</xforms:hint>
<xforms:item>
<xforms:label>Smallpox</xforms:label>
<xforms:value>100</xforms:value>
</xforms:item>
<xforms:item>
<xforms:label>Malaria</xforms:label>
<xforms:value>113</xforms:value>
</xforms:item>
<xforms:item>
<xforms:label>Yellow fever</xforms:label>
<xforms:value>56</xforms:value>
</xforms:item>
<xforms:item>
<xforms:label>Typhoid</xforms:label>
<xforms:value>174</xforms:value>
</xforms:item>
</xforms:select>
</tr>
<tr>
<td align="left">
<xforms:textarea model="immigration"
ref="/immigrant/address">
<xforms:label>Address in home country
</xforms:label>
</xforms:textarea>
</td>
</tr>
</table>
<xforms:submit submission="submit">
<xforms:label>Save</xforms:label>
<xforms:hint>Save the information
entered above to a local file</xforms:hint>
</xforms:submit>
</body>
</html>
Looks familiar? It should, since this is the same form I used to demonstrate the various input controls earlier, with one important addition: the ability to actually do something with the data once it has been entered by the user.
The XForms specification defines an <xforms:submission> element, that specifies how form submission is to be handled. Typically, this element appears in the <head> of the document, within an <xforms:model> element, and contains information on the URL to which the form is to be submitted, the method of submission, and the format and structure of the submitted XML. Here's an example:
<xforms:submission id="submit"
action="/tmp/immigrant.xml" method="put" />
This is similar to the data that appears in the standard HTML <form> tag. Note the addition of an "id" element. This is used to link the <xforms:submission> element with the actual form submit button, and the method used (PUT, because in this first example, I'll be writing the form data to a local file, not a server storage engine).
The <xforms:submission> element is only part of the puzzle. The other half is the submit button itself, represented by the <xforms:submit> input control. (Remember this from last time's lesson?) Here's what it looks like:
<xforms:submit submission="submit">
<xforms:label>Save</xforms:label>
<xforms:hint>Save the information
entered above to a local file</xforms:hint>
</xforms:submit>
Pretty standard, as this - like other input controls - contains optional <xforms:label> and <xforms:hint> elements to give the user additional information on what it's supposed to do. The novel thing here, though, is the additional "submission" attribute, which associates this submit button with the <xforms:submission> element defined in the XForms model. Because of this link, the <xforms:submit> element will trigger the "action" specified in the <xforms:submission> element when invoked.
Now, let's give it a whirl to see it if works as advertised. Enter some data into the form and hit the "Save" button. Then, navigate to the location specified in the "action" attribute and open up the target file in a text editor. You should see the data you entered, formatted in XML as per your form model. Here's an example:
<!-- immigration.xml-->
<immigrant>
<name>Chewbacca</name>
<citizenship>Tatooine</citizenship>
<purpose>B</purpose>
<immunization>56 113 100</immunization>
<address>Planet Tatooine</address>
</immigrant>
Behind the scenes, here's what happens when the form is submitted:
- An "xforms-submit" event is triggered (more on events shortly).
- The instance data tree beginning at the root specified in the <xforms:submission> element is selected. If no root is specified (as in the example above), the entire instance data tree is selected.
- The selected instance data is validated as per validation rules that may be specified in the XForm. If an error occurs in validation, processing stops and an exception is generated.
- If the data passes all the validation tests, it is serialized and submitted using the information provided in the "method" and "action" attributes of the <xforms:submission> element.
Next: Data Overload >>
More XML Articles
More By Harish Kamath, (c) Melonfire
