XForms Concepts
In this section, I will introduce you to the concepts that underlie XForms and allow data to be separated from its presentation.
XForms divides the underlying form data and its presentation into separate layers. For example, XForms has an xforms:input form control that accepts data. It is similar to an HTML/ XHTML input element. However, the presentation of the xforms:input form control is not fixed—its presentation is determined by the user interface of individual platforms. It can be presented on a desktop browser with an appearance similar or identical to that of the HTML input element. However, on a mobile browser, it might be presented in a simpler fashion—perhaps just a label, a colon, and a flashing cursor at the position for the entry of text. In addition, the xforms:input form control can, on an aural browser, be presented entirely verbally with no visual presentation at all.
In addition, the XForms processor automatically packs up the data collected from the user into an appropriate XML-based format for transmission. Assigning that task to the XForms processor can save the Web developer a lot of time writing custom code.
Data entered into an XForms form is bound to instance data. Later, we will look at how this is done. Data is entered by using a form control. Each form control is bound to part of the instance data. In an application, an xforms:selectOne form control can be presented in several ways on different platforms, but the control will be bound to the same part of the instance data in each case. For example, the user might want to indicate which age group he is in during an online survey. The xforms:selectOne form control could be presented on a desktop browser as a radio control or audibly in an aural browser. In both cases, the data entered will be bound to instance data of the same structure.
XForms Model
The XForms model and what the form does are defined in the xforms:model element. The XForms model contains information about where and how data collected from the user is to be submitted and also contains the default instance data for the form.
In an XForms application with a single XForms form, the XForms model can be represented simply by code such as the following:
<xforms:model> <xforms:submitInfo action="http://www.xmml.com/" id="submit" method="post"/> </xforms:model>
The xforms:submitInfo element has an action attribute defining the destination for data submitted. A method attribute defines the method used to submit the data to the destination defined in the action attribute.
In a more complex application, where more than one xforms:model element exists, the xforms:model element(s) other than the first must have an id attribute to allow them to be referenced unambiguously. Thus, a second xforms:model element in the application would be written using code such as the following:
<xforms:model id="SecondModel"> <xforms:submitInfo action="http://www.xmml.com/survey/" id="OnlineSurveySubmit" method="post"/> </xforms:model>
In addition to the xforms:submitInfo element, the xforms:model element contains the instance data for the XForms form and might optionally contain an xforms:schema element.
Caution
Be sure to avoid confusing the xforms:schema element, from the XForms Namespace, with the xsd:schema element from the W3C XML Schema Namespace.
Instance Data
The default instance data of an XForms form can be contained within the XForms Model, or it can be contained in an external file referenced from an xforms:instance element nested within the xforms:model element.
Listing 25.1 creates a very simple XForms form embedded in an XSL-FO document. At the time of writing, there is no implementation of the December 2001 XForms Working Draft. The XSL-FO code is fairly lengthy. Look for elements with an xforms namespace prefix to see how XForms elements can be used.
Caution
The namespace URI used in the following code was an internal one used by the X-Smiles development team during development of the December 2001 XForms Working Draft. Be sure to check the latest version of the XForms specification for the current namespace URI.
Listing 25.1. A Simple XForms Form Collecting Name Data (SimpleForm.fo)
Default instance data is referenced using the xforms:instance element nested within the xforms:model element. The Name.xml file that contains the default instance data is shown in Listing 25.2.
Listing 25.2. Simple Instance Data Used in Listing 25.1.
<?xml version='1.0'?> <Name> <FirstName>Fred</FirstName> <MiddleInitials>Q</MiddleInitials> <LastName>Samora</LastName> </Name> |
Figure 25.1 shows the appearance produced by the preceding code in the X-Smiles XML browser.
Figure 25.1. A simple XForms form embedded in an XSL-FO document and displayed at 150%. Binding
Notice how the data from Listing 25.2 is displayed as default values for the xforms:input form controls. Notice too that the content of an xforms:hint element is displayed as a ToolTip for the xforms:input form control that is moused. The cursor appears as an I-bar because it is mousing a form control that accepts text input.
To download the current version of the X-Smiles browser, visit http://www.xsmiles.org and follow the download links.
Note
If you are trying to access http://www.x-smiles.org from a corporate base and find that access is blocked, a system administrator might have erroneously blocked access believing that the URL is an “adult” site. The X-Smiles browser is unrelated to that site.
XForms has an xforms:bind element that might also be nested within the xforms:model element. The purpose of the xforms:bind element is to apply a constraint to a selected part of the instance data. Additionally, an id attribute within the part of the instance data allows a shorthand reference to that data.
In Listing 25.1, from which the following code is extracted, you can see a simple use of the xforms:bind element.
<xforms:model> <xforms:submitInfo id="submit1" method2="postxml" localfile="temp2.xml" target2="http://www.xmml.com/"/> <xforms:schema/> <xforms:instance href="Name.xml"/> <xforms:bind ref="Name/FirstName" type="xsd:string"/> </xforms:model>
The xsd:bind element has a ref attribute that indicates the part of the instance data which is subject to the constraint. The type attribute of the xforms:bind element indicates the type of constraint that is being placed on the referenced node-set. In the preceding example, the type attribute has a value which indicates that any data of type xsd:string is permitted. The type attribute could be used, for example, to constrain the entry to xsd:nonNegativeInteger values if the associated xforms:input form control is intended to accept the number of items to be purchased.
Note
If you are unfamiliar with the W3C XML Schema data types, refer to Chapter 5, “Defining XML Document Structures with XML Schemas,” for further information.
XForms Form Controls
XForms form controls use XML to describe the purpose or functionality of the XForms form controls. The attributes of a form control element allow the refinement of its appearance, including a class attribute that can be used in conjunction with Cascading Style Sheets to give selected form controls a coordinated look and feel. The form controls within an XForms form are bound to instance data.
A basic notion of the XForms form controls is that they describe a function, but do not indicate directly how the form control is to be presented. For example, the xforms:selectOne control is used to pick one or more items from a set. It is possible to use xforms:selectOne on a conventional desktop browser, on one of the many forms of mobile browsers, or to avoid a visual presentation altogether using Aural Cascading Style Sheets. In fact, all XForms form controls are suitable for styling using Aural CSS. The behavior of form controls is defined by XForms actions, which are described later in this chapter.
Note
If you are interested in Aural style sheets, further information is available at http://www.w3.org/TR/REC-CSS2/aural.html.
XForms form controls also have a number of common attributes that are described following the description of the individual form controls.
Note
In the XForms form controls descriptions that follow, all are described with a namespace prefix present; for example, xforms:input. This helps to distinguish the XForms form controls from similarly named HTML/XHTML constructs.
The Input Form Control
The XForms xforms:input form control is intended for the entry of brief free-form textual data. It might be used, for example, to ask for the entry of a name, some brief comments, or some other short message in an unstructured format.
For example, an input form control might be used to record special delivery instructions for an online order.
<xforms:input ref="order/shipTo/instructions" class="BlueForm"> <xforms:caption>Delivery instructions</xforms:caption> <xforms:hint>Describe briefly any special instructions to aid efficient delivery of your order</xforms:hint> </xforms:input>
Notice the ref attribute on the xforms:input element. The value of the ref attribute is an XPath location path that indicates with which part of the instance data the form control is associated.
Note
The value held in the instance data might not be identical to the form entered by the user. For example, a purchaser in Germany might enter a number using local conventions for thousands separator (period) and decimal separator (comma), but the data might be stored, for example, using English conventions.
The xforms:input form control can bind to any XML Schema simpleType data type, excluding xsd:base64Binary or xsd:hexBinary or types derived from them.
An xforms:input form control must enable the entry of a lexical value of the bound data type.
Depending on the type of data to which it is bound, it might take the appearance of a slider to allow numerical data, a calendar to allow date information, or a simple box into which text can be typed in the conventional way.
The input form control can have an inputMode attribute. The inputMode attribute provides a hint to the user agent about how text can best be entered—in contrast to binding to a W3C XML Schema simpleType, which is restricted by facets that provide a strict constraint on allowable text.
The textarea Form Control
The xforms:textarea form control is intended for the entry of multiline free-form data. It might be used, for example, to contain the body of an e-mail message or for some narrative text that is likely to be multiline in length.
We could use the textarea form control to accept delivery instructions in a way similar to that shown for the xforms:input form control.
<xforms:textarea ref="order/shipTo/instructions" class="BlueForm"> <xforms:caption>Delivery instructions</xforms:caption> <xforms:hint>Describe any special instructions to aid efficient delivery of your order. Please be sure to include sufficient information for the driver.</xforms:hint> </xforms:textarea>
The xforms:textarea form control can bind to data of type xsd:string or any type derived from it.
The Secret Form Control
The xforms:secret form control is the rather unusual name chosen to name the XForms form control that is intended for the input of sensitive information such as passwords. Any information entered into an xforms:secret form control is not echoed back to the browser, whether that is a conventional desktop browser or an aural browser.
The xforms:secret form control could be used to enter a login password using code such as this:
<xforms:secret ref="login/password"> <xforms:caption>Enter your password here</xforms:caption> <xforms:hint>Your password won't be visible as letters when you enter it - simply as a sequence of asterisks.</xforms:hint> </xforms:secret>
Notice the ref attribute on the xforms:secret element, which binds the data entered to a specific part of the form's instance data.
The Output Form Control
The xforms:output form control is intended for use to display read-only values. The user is not permitted to alter the value displayed.
The xforms:output form control might, for example, be used to display calculated sales tax (assuming that the Web page knew the appropriate rate for the user's locality) and the total price to be charged to a customer. Code might appear as follows, assuming that the XForms form is placed in an XHTML page:
<tr> <td>Sales tax is:</td> <td><xforms:output ref="Order/SalesTax"/> </tr> <tr> <td>Total cost is:</td> <td><xforms:output ref="Order/TotalCost"/></td> </tr>
The format in which a number, for example, is stored in the instance data might not be identical to the format used for display. That situation could occur when orders are being accepted from countries that use a decimal separator different from that in which W3C XML Schema numbers are stored. Thus in the instance data, the figure of 1,000.00 might be stored, but the figure displayed to a customer in Germany would be displayed as 1.000,00.
The Upload Form Control
The xforms:upload form control allows a user to upload a file from the local file system to that of the Web site, which provides the form control, or to upload input from devices such as pens or digital cameras.
To enable the upload of an image, you would use code such as the following:
<xforms:upload ref="Upload/Image" mediaType="image/*"> <xforms:caption>Upload an image to our server.</xforms:caption> <xforms:hint>Please be careful to select only an image file.</xforms:hint> </xforms:upload>
A graphical browser might render the xforms:upload form control as a drop-down menu that, when appropriate, includes an option to browse the local file system to select an appropriate file for upload to the server.
The xforms:upload form control can be bound only to the data types xsd:base64Binary or xsd:hexBinary or data types derived by restriction of those types.
In a system with a file system, the mediaType attribute of the xforms:upload element will determine the options offered to the user for upload. Thus if, for example, the mediaType attribute were used to specify audio files, audio files should be the offered option. For systems with pen hardware, a “scribble” option should be offered.
The Range Form Control
The xforms:range form control allows the display and input of a range of numerical values with prespecified steps.
The xforms:range form control could be used, for example, to constrain the number of items that a user could order for a special offer of a particular item.
<xforms:range ref="SpecialOffer/Widgets" start="0" end="5" stepSize="1"> <xforms:caption>Number of Widgets:</xforms:caption> <xforms:hint>For this special offer the maximum number you can order is 5.</xforms:hint> </xforms:range>
The preceding code would create a form control that could accept values from zero to five for the number of widgets to be ordered. The start attribute defines the minimum allowed number, and the end attribute defines the maximum allowed number.
The xforms:range form control can only be applied to scalar types. Thus, the permitted data types to which a range form control can be bound are xsd:float, xsd:decimal, xsd:double, xsd:duration, xsd:date, xsd:time, xsd:dateTime, xsd:gYearMonth, xsd:gYear, xsd:gDay, and xsd:gMonth or data types derived by restriction from the stated types.
The Button Form Control
The xforms:button form control, not surprisingly, provides graphical browsers a button for a user to click. In a typical implementation, the caption would be rendered on the face of the button. Using CSS, it is possible to use an image as the button.
An xforms:button form control cannot be bound to instance data and therefore has no ref, model or bind attribute, unlike many of the other XForms form controls. Buttons are used to generate events. The caption provides a label for the button, and a hint can also be provided.
<xforms:button> <xforms:caption>Click here!</xforms:caption> <xforms:hint>This will perform a stated action</xforms:hint> </xforms:button>
The Submit Form Control
The xforms:submit form control initiates submission of all or part of the XForms information. When the submit button, in a graphical browser, is clicked, an xforms:submit event is sent to an xforms:submitInfo element. The target xforms:submitInfo element is indicated by a submitInfo attribute on the xforms:submit element, or—in the absence of such an attribute—the first xforms:submitInfo element in document order is targeted.
The code to represent an xforms:submit form control is similar to the following:
<xforms:submit submitInfo="Order"> <xforms:caption>Click to submit your order</xforms:caption> <xforms:hint>This is the final step. Be sure all information shown is accurate before submitting it.</xforms:hint> </xforms:submit>
The selectOne Form Control
The xforms:selectOne form control allows a user to make a single choice from among a number of choices. The xforms:selectOne form control can bind to any type of simple content.
For example, if in an online pizza delivery service a number of mutually exclusive choices of toppings were offered, we could use code such as the following:
<xforms:selectOne ref="Order/Pizza/Topping"> <xforms:caption>Select one topping</xforms:caption> <xforms:item> <xforms:caption>Pepperoni</xforms:caption> <xforms:value>pepperoni</xforms:value> <xforms:hint>This selection selects pepperoni topping.</xforms:hint> </xforms:item> <xforms:item> <xforms:caption>Ham and Tomato</xforms:caption> <xforms:value>HamAndTom</xforms:value> <xforms:hint>This selection selects ham and tomato topping.</xforms:hint> </xforms:item> <xforms:item> <xforms:caption>Chicken and pineapple</xforms:caption> <xforms:value>ChickAndPin</xforms:value> <xforms:hint>This selection selects chicken and pineapple topping.</xforms:hint> </xforms:item> </xforms:selectOne>
The xforms:selectOne form control stores the chosen value in the part of the instance data defined by the value of the ref attribute on the xforms:selectOne element. In this case, the user would be able to select “pepperoni,” “ham and tomato topping,” or “chicken and pineapple.” These are defined within the xforms:item elements. After selecting one, the data instance element identified by the expression “Order/Pizza/Topping” would have a value of “pepperoni,” “HamAndTom,” or “ChickAndPin.”
The xforms:selectOne form control can have closed data entry of the type shown earlier—that is, all the possible choices are defined. Another option is for open data entry, with the acceptable data type being xsd:string. Free entry of text is handled similar to the xforms:input form control. The mode of entry is determined by the selection attribute, which might take values of “closed” or “open,” with the default being “closed.” In addition, a selectUI attribute allows selection of the user interface to be used for graphical browsers, with allowed values of “radio,” “menu,” or “listbox.”
Note
The December 2001 Working Draft allows a further “checkbox” option for a value of the selectUI attribute. Because that interface is contrary to the norms of HTML Web forms, it is possible that the option will be removed as the XForms specification is finalized.
The selectMany Form Control
The xforms:selectMany form control allows multiple choices to be made from a range of zero or more choices offered. A user can, however, choose only one choice if preferred.
If our fictional online pizza operation is a little more generous and allows two toppings, rather than only one, we could use the xforms:selectMany form control to express that in XForms code.
<xforms:selectMany selectUI="checkbox" ref="Order/Pizza/Toppings"> <xforms:caption>Choose Toppings</xforms:caption> <xforms:hint>You may choose up to two toppings.</xforms:hint> <xforms:item> <xforms:caption>Pepperoni</xforms:caption> <xforms:value>Pepperoni</xforms:value> <xforms:hint>This selection selects pepperoni topping.</xforms:hint> </xforms:item> <xforms:item> <xforms:caption>Ham and Tomato</xforms:caption> <xforms:value>HamAndTom</xforms:value> <xforms:hint>This selection selects ham and tomato topping.</xforms:hint> </xforms:item> <xforms:item> <xforms:caption>Chicken and pineapple</xforms:caption> <xforms:value>ChickAndPin</xforms:value> <xforms:hint>This selection selects chicken and pineapple topping.</xforms:hint> </xforms:item> </xforms:selectMany>
Values permitted for the selectUI attribute in the December 2001 Working Draft are “checkbox,” “menu,” “listbox,” and “radio.”
Caution
Although “radio” is a permitted value for the selectUI attribute, it makes no sense to use a radio button interface (which selects only one) in conjunction with a selectMany form control.
Common Attributes
Many form controls have a number of common attributes that are described here.
The xml:lang attribute is an optional attribute that defines a human language for the data to be entered into a form control on which the xml:lang attribute is present. The permitted content of the xml:lang attribute is of type xsd:language.
The class attribute associates a particular presentation style with the form control element on which it is present. The permitted content of the class attribute is a space separated list of CSS classes.
The navIndex attribute defines the position in tabbing order of the form control element on which the attribute is present. The allowed values of the navIndex attribute are of type xsd:nonNegativeInteger.
The accessKey attribute is an optional attribute that defines a shortcut to place focus on the form control. The value of the accessKey attribute must be of data type xsd:token.
Creating Choices at Runtime
The examples of the use of form controls that you have seen define the available choices statically—that is, the available choices are hard-coded within the form control itself. XForms also provides the opportunity to define the available selections at runtime using the xforms:itemset element.
We could use the xforms:itemset element to dynamically create a selection of pizza toppings similar to that we created earlier for the xforms:selectMany form control using code similar to the following. The code, could, of course, be augmented to provide choices of pizza size, different bases, and so on.
<xforms:model id="Pizza"> <xforms:instance> <my:pizza> <my:toppings/> </my:pizza> <!-- Other instance data could go here. --> </xforms:instance> </xforms:model> <xforms:model id="toppings"> <xforms:instance> <my:toppings> <my:topping type="pepperoni"> <my:description>Pepperoni</my:description> <my:hint>This selection selects pepperoni topping.</my:hint> </my:topping> <my:topping type="HamAndTom"> <my:description>Ham and Tomato</my:description> <my:hint>This selection selects ham and tomato topping.</my:hint> </my:topping> <my:topping type="ChickAndPin"> <my:description>Chicken And Pineapple</my:description> <my:hint>This selection selects chicken and pineapple topping.</my:hint> </my:topping> </my:toppings> </xforms:instance> </xforms:model> <!-- Other XForms markup could go here. --> <xforms:selectMany model="Pizza" ref="my:pizza/my:toppings"> <xforms:caption>Available Toppings</xforms:caption> <xforms:itemset model="toppings" nodeset="my:toppings/my:topping"> <xforms:caption ref="my:description"/> <xforms:hint ref="my:hint"/> <xforms:value ref="@type"/> </xforms:itemset> </xforms:selectMany> <!-- Other XForms markup could go here. -->
Notice that the code has two xforms:model elements. The xforms:model elements can be reliably distinguished in the code because each has an id attribute. The xforms:selectMany element binds to the Pizza model and my:toppings instance element of that model. Similarly, the xforms:itemset element binds to the toppings model and, more precisely, to the node-set that holds the available choices by means of its nodeset attribute. The XPath expressions in the ref attributes of the xforms:caption, xforms:hint, and xforms:value elements are interpreted relative to the context provided by the value of the ref attribute of the containing xforms:itemset element.
The example code illustrates “single node binding attributes” and “nodeset binding attributes.” The ref attribute of the xforms:selectMany element binds to a single node. The nodeset attribute on the xforms:itemset element is used to bind to a node-set. In this case, it binds to the nodeset produced by the XPath expression "my:toppings/my:topping," which yields all the my:topping elements that are children of the toppings element contained in the toppings model.
Common Child Elements for Form Controls
In the example code demonstrating the XForms form controls, you have already seen several of these child elements in use.
The xforms:caption element is a required child element for all form controls. The xforms:caption element provides a label for containing XForms form control. Typically, the xforms:caption element will contain the text that constitutes the caption. But, it can optionally take an xlink:href attribute to reference an external definition of the caption or one of the binding attributes to reference a caption definition in instance data.
Optionally, a form control can have xforms:help or xforms:hint child elements. Each of these elements provides information intended to be helpful to the user.
Optionally, a form control can have a nested xforms:alert element to express some warning or error message related to the form control. As with other common child elements, the message can be the text content of the xforms:alert element—referenced from within the same document using a ref attribute or referenced from an external document using an xlink:href attribute.
A further optional element permitted within form controls is the xforms:extension element. The xforms:extension element can be used to contain application-specific extension elements. One possible application is as a container for metadata as the following example adapted from the working draft indicates:
<xforms:input ref="dataset/user/email" id="email-input"> <xforms:caption>Enter your email address</xforms:caption> <xforms:extension> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> <rdf:Description about="#email-input"> <my:addressBook>personal</my:addressBook> </rdf:Description> </rdf:RDF> </xforms:extension> </xforms:input>
The chosen metadata format is the W3C's Resource Description Framework. In principle, any other appropriate XML application language could be used in conjunction with the xforms:extension element.
XForms Actions
XForms form controls do not intrinsically have behavior, but the XForms specification provides mechanisms for developers to define behaviors for XForms form controls by using XForms Actions. Event handling in XForms is defined in terms of the XML Events specification at the W3C. The current working draft for XML Events is located at http://www.w3.org/TR/xml-events.
XForms form controls can use attributes from the XML Events Namespace on XForms elements. Thus, assuming that the XML Events Namespace URI had been declared in another part of the code and that the namespace prefix ev had been declared with the XML Events Namespace URI, a reset button in XForms could be created using code similar to the following:
<xforms:button> <xforms:caption>Reset</xforms:caption> <xforms:resetInstance ev:event="xforms:activate"/> </xforms:button>
Caution
Because both the XForms and XML Events specifications are subject to change, details describing XForms actions might be particularly subject to change.
In the following parts of this section, we will look briefly at each of the XForms actions.
The dispatch Action
The xforms:dispatch action dispatches an XForms event to a target element. The target attribute of this element identifies the element that will receive the event. The xforms:dispatch element will additionally have a name attribute whose value contains the name of the event to be dispatched. Other attributes include an optional bubbles attribute, whose value indicates whether the event bubbles, and an optional cancellable attribute, whose value indicates, whether the event is cancellable. Bubbling and cancellation are defined in the Document Object Model Level 2 Events Specification.
The refresh Action
The xforms:refresh action causes the XForms form's display to be refreshed.
The recalculate Action
The xforms:recalculate action causes an XForms recalculate event to be dispatched and might be used when the number of items ordered is altered and the calculated cost, determined by the number of items ordered, needs to be recalculated.
The revalidate Action
The xforms:revalidate action causes an XForms revalidate event to be dispatched. This might be used when a user-entered value was invalid with respect to the applicable schema. After the user enters a new or amended value, there is a need for that new value to be validated against the schema.
The setFocus Action
The xforms:setFocus action sets the focus on a particular form control. This, of course, is useful to the user if the focus is set on the form control that logically is to be filled in first. Avoiding the need for a mouse click is a small, but significant, improvement in usability of a form.
For example, if we wanted the focus to be on an xforms:input form control for the entry of the user's first name, we could use code such as this for the form control:
<xforms:input id="firstName"/>
The xforms:setFocus action could be applied as follows:
<xforms:setFocus idref="firstName"/>
The loadURI Action
The xforms:loadURI action causes an XLink to be traversed. XForms supports only simple type XLinks. To open the linked resource in a new browser window (or an equivalent in non-graphical browsers), we could use code such as the following:
<xforms:loadURI xlink:href="http://www.xmml.com" xlink:show="new"/>
Equally, if there was a desire to load a resource into the current XForms form, code similar to the following could be used:
<xforms:loadURI xlink:href="http://www.xmml.com/someResource.xml" xlink:show="replace"/>
The setValue Action
The xforms:setValue action explicitly sets the value of a specified node in the instance data of a form. The setValue element has an optional value attribute whose value is an XPath expression. If there is no value attribute, the content of the xforms:setValue element is the value to be applied. If there is no value attribute nor any text content in the xforms:setValue element, the specified node is allocated the value of the empty string.
To set the value of the node with an id attribute value of “validOrNot” to a value of “invalid,” we could use the following code:
<xforms:setValue bind="validOrNot"> invalid </xforms:setValue>
The submitInstance Action
The xforms:submitInstance action can be used to explicitly submit instance data. The xforms:submitInstance element can optionally have a submitInfo attribute whose value is of type xsd:IDREF. This attribute associates the action with an xforms:submitInfo element.
The resetInstance Action
The xforms:resetInstance action explicitly resets instance data. The xforms:resetInstance element has a model attribute whose value defines the XForms model whose instance data is to be reset.
For example, if an XForms form contained two xforms:model elements with id attributes "first" and "second," the following code could be used to reset the instance data in the second xforms:model element:
<xforms:resetInstance model="second"/>
The setRepeatCursor Action
The xforms:setRepeatCursor action sets as current a particular item in a repeating sequence.
The insert Action
The xforms:insert action is used to insert nodes into the instance data.
Usually, xforms:insert is used to add a new item into a collection, such as a shopping cart. The collection, a part of the instance data, is identified through the use of nodeset binding attributes, which include the xforms:nodeset, xforms:model, and xforms:bind attributes. You learned how to use these attributes earlier when we discussed the xforms:itemset element. The value of the xforms:nodeset attribute is a binding expression that selects the collection to which we want to add. A binding expression is simply a limited XPath expression. The at attribute of the xforms:insert element is evaluated to determine an index into the node-set, which is used to select a specific node in the node-set. Finally, the position attribute defines whether the new node is to be inserted before or after the node defined in the at attribute. The xforms:insert action is used with code similar to the following:
<xforms:insert nodeset="/ShoppingCart/Items/item" at="item[last()]" position="after"/>
In this example, a new item would be inserted into the instance data following the last item element.
The delete Action
The xforms:delete action deletes nodes in the instance data. The xforms:delete element can have a nodeset attribute whose value defines the node-set from which a node will be deleted. Similar to the xforms:insert element, this element has an at attribute that determines which node within the node-set will be deleted.
Adding or deleting nodes dispatches events so that the user interface and other form elements can adjust to the changes appropriately. For example, an input that is bound to a deleted node will be removed from the user interface.
The toggle Action
The xforms:toggle action is used when a user interface is constructed conditionally. The xforms:toggle element can have a case attribute whose value is of type xsd:IDREF and references a case element that forms part of the logic used to create the interface presented to the user. The toggle action causes the state of the form to change by selecting a different case.
The script Action
The xforms:script action is used to invoke some scripting code. The xforms:script element must take a type attribute whose value identifies the mime type of the scripting code.
Thus, if we have some JavaScript code in an XForms form, we could use the xforms:script element as follows:
<xforms:script type="text/javascript"> <!-- The JavaScript code would go here. --> </xforms:script>
The message Action
The xforms:message action can be used to display a message to the user. The xforms:message element must have a level attribute that can take the values of “ephemeral,” “modeless,” or “modal.” The working draft does not clearly distinguish the precise roles of these values. But, the ephemeral level seems to correspond closely to the usage of the xforms:hint element, producing a brief message when, in a graphical browser, a form control is moused.
The xforms:message action can reference an external message by means of an optional xlink:href attribute on the xforms:message element.
The action Action
The xforms:action action can be used to bind XForms actions to form controls and group them in association with a common event handler.
XForms Functions
XForms processors support the full function library that is included with XPath 1.0. The XPath function library includes functions to handle XPath's four data types—node-set, number, string, and Boolean. You might want to refer to Chapter 11, “Locating Components in XML Documents with XPath,” to refresh your memory on the XPath function library.
Boolean Functions
XForms provides two Boolean functions—boolean-from-string() and if() function.
The boolean-from-string() function takes a single string argument. The function returns the Boolean value true when the argument is the string literal “true” and false if the argument is “false.” If, when using a comparison that isn't case sensitive, the string matches neither “true” nor “false,” an error occurs, causing processing to stop. You might find the boolean-from- string() function useful when referencing an xsd:boolean data type in an XPath expression. The need for the function arises from the use of both XPath 1.0 and W3C XML Schema data types within XForms.
The if() function takes three arguments—a Boolean and two string values. The first argument must evaluate to a Boolean value. If the first argument evaluates to true, the first of the two string arguments is returned: Otherwise, the second of the two string arguments is returned.
Thus, the if() function might resemble this:
if (5>4, "This is correct," "This is misleading")
Note that the arguments are separated by commas.
Number Functions
XForms provides five number functions—avg(), min(), max(), count-non-empty(), and cursor()—to augment the number functions provided by XPath.
The avg() function takes a single argument, which is a node-set. The function returns the arithmetic average of the values in each node in the node-set. The string value of each node is converted to a number. The numeric values are summed and divided by the number of nodes in the node-set.
The min() function takes a single argument, which is a node-set. The function returns the numeric value that is the lowest value found in the node-set after converting the string value of each node to a numeric value.
The max() function takes a single argument, which is a node-set. The function returns the numeric value that is the highest value found in the node-set after converting the string value of each node to a numeric value.
The count-non-empty()function takes a single argument, which is a node-set. The function returns a numeric value equal to the number of nodes in the argument node-set that have a string value of greater than zero.
The cursor() function takes a string, which is the value of an idref attribute of an xforms:repeat element (see later) and returns the position of the xforms:repeat cursor.
String Functions
XForms provides two string functions—property() and now().
The property() function takes a single string argument. The argument string can take the values of either “version” or “conformance-level.” The property() function returns a value corresponding to the property used in the string argument. For XForms version 1, the function
property(version)
returns the string “1.0.”
The now() function takes no argument and returns the current system date and time (including any available time zone information).