What is an XForms Model?
Briefly, an XForms model is a useful bucket into which you can put:
- References to, or actual WXS schemas.
- References to, or actual XML instances (that may or may not conform to a WXS schema).
- Model Item Properties (MIPs).
This is not an exhaustive list, but is plenty for our purposes. Our interests lie mostly in MIPs, which are themselves a bit of a bucketful. In our example MIPs play the same role as Schematron assertions. They are defined using the XForms bind expression. A bind consists of an XPath defined pattern from one of the instances referenced within the XForms model, associated with one or more assertion. The following MIPs are available:
- type: Assign a named WXS type to a node (including an attribute).
- readonly: Make a node read-only.
- required: Make a node required.
- relevant: Define a condition in which a node is relevant to its parent XML instance. If this condition is not met the node is not relevant, and will be pruned.
- calculate: Calculate a node value.
- constrain: Constrain a node value.
- p3ptype: Assign a p3ptype to a node.
To our fridge, MIPs are a convenient means of decorating the structures defined by the WXS schema with some extra assertions expressed in XPath 1.0. Crucially to our fridge, the XForms model defines how the application of MIPs to an XML instance must combine with the structural and data type validation provided by an underlying schema. In XForms the schema is a first class validation object, to which MIP defined assertions are subsidiary. For example, it is an error for MIPs to contradict a schema in any way, and an XML instance is validated against any associated schema before MIPs are applied.
However, it is legal to define MIPs that further constrain schema defined structures and values in an instance. In this context we want to constrain the value of a node defined in a schema to be a positive integer. First we need to define our model:
<xfm:model xmlns:xfm="http://www.w3.org/2002/xforms" schema="chilledML.xsd">
<xfm:instance src="my_fridge.xml" id="fridgeML"/>
</xfm:model>
Note the schema attribute on the <model/> element contains a space separated list of schema names. The <instance/> element refers to our external source XML document, and gives it an id so that we can refer to it within the model. An XForms processor must attempt to validate instances with any schemas listed within the schema attribute, ignoring any schemaLocation or noNamespaceSchemaLocation attribute within any instances.
Constraints
We need to constrain the allowed values of the <volume/> element. Unsurprisingly we express the assertion with the constraint MIP:
<xfm:model xmlns:xfm="http://www.w3.org/2002/xforms" schema="chilledML.xsd">
<xfm:instance src="my_fridge.xml" id="fridgeML"/>
<xfm:bind nodeset="instance('fridgeML')/contents/dairyProduce/milk[@type = 'full-fat']"
constraint="volume <= 1"/>
</xfm:model>
MIPs are expressed using the <bind/> element. The nodeset attribute value is an XPath 1.0 expression that defines the nodeset to be constrained. The constraint attribute defines the constraint itself, again in terms of XPath 1.0. We end up with an expression not a million miles away from the Schematron assertion we started with.
Note the use of the instance() function in the nodeset attribute. This is a bit like using document() in XSLT 1.0. It allows us to refer to an instance by the value of its id. Strictly speaking we don't need to use instance() here, XForms defines the first instance to be declared in a model to be the default. However making explicit the XML instance referred to, using instance() is safest. After all we might do the following:
Supposing our fridge stores configurable settings in an XML instance like this:
<fridge-settings>
<full-cream-milk>1</full-cream-milk>
</fridge-settings>
We can alter the XForms model to include our fridge settings, and use them directly to constrain the amount of creamy milk we store:
<xfm:model xmlns:xfm="http://www.w3.org/2002/xforms" schema="chilledML.xsd">
<xfm:instance src="my_fridge_settings.xml" id="fridgeSettings"/>
<xfm:instance src="my_fridge.xml" id="chilledML"/>
<xfm:bind nodeset="instance('chilledML')/contents/dairyProduce/milk[@type='full-fat']"
constraint="volume <= instance('fridgeSettings')/full-cream-milk"/>
</xfm:model>
Our fridge now constrains the value of the <milk/> element in our chilledML document to a value less than or equal to the value of the <full-cream-milk/> element in the fridge settings XML document. It would be just as easy to write MIPs that make optional elements or attributes mandatory, or to restrict the number of times an element repeats, for example.
Other MIPs
The relevance MIP is another useful tool in the box. We use it, not to state that a given node is invalid, but that it is simply not relevant to the instance if the MIP evaluates to false. The non-relevant node and its ancestors are treated as if they no longer exist, until the MIP evaluates to true again.
Let us suppose for a moment that we sometimes store salad stuff in our fridge. chilledML defines an optional structure to cater for such an eventuality:
<fridge>
<contents>
<saladStuff>
<lettuce>
<quantity>2</quantity>
</lettuce>
<tomato>
<weight uom="kg">0.25</weight>
</tomato>
</saladStuff>
</contents>
</fridge>
chilledML also has an optional structure to allow salad dressings. However, our configurable fridge allows us to say that we are only interested in salad dressing if we have some lettuce.
<xfm:bind nodeset="instance('chilledML')/contents/saladDressing"
relevant="instance('chilledML)/contents/saladStuff/lettuce"/>
We are not saying that there must be salad dressing if we have lettuce, simply that if we have lettuce, then salad dressing matters. If we don't have lettuce, then we don't need to worry about salad dressing. If we felt more strongly about our salad dressing, we might add a required MIP, so that not only would salad dressing be relevant should we have lettuce, but it becomes mandatory. Furthermore, we could use a calculate MIP to determine exactly how much salad dressing we require, given a certain quantity of lettuce.
<xfm:bind nodeset="instance('chilledML')/contents/saladDressing"
relevant="instance('chilledML)/contents/saladStuff/lettuce"/>
<xfm:bind nodeset="instance('chilledML')/contents/saladDressing/mayonnaise"
required="true()"/>
<xfm:bind nodeset="instance('chilledML')/contents/saladDressing/mayonnaise/volume"
calculate="30 * instance('chilledML')/contents/saladStuff/lettuce/quantity"/>
We have gone beyond the scope of validation with this last set of MIPs, as we now have a rule intended to modify an XML instance should the need arise. However, the second bind, which calculates the amount of mayonnaise we need could just as easily have been a constraint. Even so, the relevance MIP itself does more than validate. A node that is not relevant is treated as if it doesn't exist by an XForms processor. It is actually pruned from the tree at the point of saving an XML instance that has been used within an XForm.
Alert
Thus far we have a WXS schema that defines XML structures and their values, formally combined with a pattern based assertion. Usefully we have not had to alter our WXS schema to achieve this. Additionally, we know that any MIPs we define will not contradict the underlying WXS schema, so any instance validated by our XForms model will be valid against the WXS schema.
All this is good, but we still haven't replicated quite all of the Schematron assertion we began with. The assertion includes some text from which a useful validation report can be built, whilst our MIPs are so far mute. XForms actually defines four elements that we ought to be able to use to great effect in this context:
- label
- help
- hint
- alert
Each of these elements is designed to provide some kind of explanation to a human, and very usefully, their contents can be generated dynamically at runtime by using them in conjunction with the XForms <output/> element. Of these <alert/> is probably the most appropriate, as it is associated with validation errors. Ideally we would like to be able to do something like this:
<xfm:bind nodeset="instance('chilledML')/contents/dairyProduce/milk[@type = 'full-fat']"
constraint="volume <= instance('fridgeSettings')/full-cream-milk">
<xfm:alert>
<xfm:output value="concat('The amount of full-cream milk must not exceed',
instance('fridgeSettings')/full-cream-milk)"/>
</xfm:alert>
</xfm:bind>
However the use of alert as a child of bind is not permitted in XForms 1.0. To use alert, and to build a human-readable validation report we have to make use of the UI part of XForms. This is unfortunate not so much because we end up designing a human readable validation report with the XForms UI, but because the resources associated with validation are now split across the XForms model and the UI.
Ideally alerts would be defined inside the model, associated with a particular MIP. They could then manifest themselves as appropriate in some kind of report, XForms based or otherwise. An alert bound to a node in an XML instance is just not as useful as an alert bound to a MIP. XML nodes can potentially become invalid for several reasons, and an alert bound to such a node is presented no matter why the node is invalid. Thus it must be general purpose. On the other hand, an alert bound to a MIP could be authored to reflect the validity test in its parent MIP.
That said, it is possible to build a reasonable XForms UI based validation report. This can either be made read-only, or can take advantage of the fact that XForms is designed to allow user interaction. In the latter case a report not only tells a human what is wrong with an XML instance, but can allow the human to make corrections. If nothing else this makes an XForms based validation service very useful as a debugging tool for developers.
If we take our original constraint, we can build a simple validation report with the following markup:
<xfm:input bind="full-cream-milk">
<xfm:help>Enter a whole number between 0 and <xfm:output
value="instance('fridgeSettings')/full-cream-milk"/>
</xfm:help>
<xfm:hint>The quantity of full-cream milk currently in your fridge.</xfm:hint>
<xfm:alert>The quantity of full cream milk is not an allowed amount. <br/> There can be no
more than <xfm:output
value="concat(instance('fridgeSettings')/full-cream-milk, ' litre(s).')"/>
</xfm:alert>
<xfm:label>Quantity of Full Cream Milk</xfm:label>
</xfm:input>
This XForms markup can be embedded in XHTML, or any other suitable host language. If supported, CSS can be used to control the styling of the report. So, assuming an invalid instance, a simple report might look like this:
If I change the value of full-cream milk to a valid quantity, the form updates to display:
