5.4 Model Item Properties | Xforms Essentials

An individual property that can be applied to a node is called a model item property. Some of the properties are XPath expressions (called computed expressions in the specification), which the XForms Processor tracks and reevaluates as necessary:

readonly
required
relevant
calculate
constraint

The remaining properties are static, and don't get reevaluated:

type
p3ptype

Some of the model item properties have an effect on child nodes as well. The rules for this behavior can be summarized like this:

Setting a node to readonly sets all child nodes to readonly, unless specifically overridden.
Setting a node to non-relevant sets all child nodes to non-relevant, unless specifically overridden.

For all other model item properties, setting that property on a node has no effect on child nodes.

A common mistake is to write code like this:

required="true"

This almost certainly doesn't have the intended effect of making the node always required. Computed model item properties are XPath expressions, and under XPath rules, "true" is interpreted as a node-set matching all element nodes named true. Unless there is such an element, the expression will evaluate to an empty node-set, which is interpreted as an XPath boolean false! Always use the functions true( ) and false( ), which return the expected XPath boolean values.

required="true(  )"

type

Allowed values:a xs:QName representing an available XML Schema datatype.

Default value:xs:string

This property associates an XML Schema datatype with an instance data node.

The unusual thing about this property is that it's technically unnecessary. The right XML Schema incantations can accomplish the same result. In many cases, however, using this model item property is more convenient than using XML Schema features.

Attaching a datatype to an element node is the most straightforward scenario. XML Schema provides an instance-based syntax, using an xsi:type attribute that can be attached to any element. The main drawbacks of this technique are that it is highly intrusive to the instance data and that it works only with elements.

Normal XML Schema conventions can also be used to associate a datatype with a node, and this works with attributes, too. For example, the following XML Schema fragment associates a datatype of my:phoneNum to an attribute named pn:

<xs:attribute name="pn" type="my:phoneNum"/>

readonly

Allowed values:any XPath expression; the result is interpreted as a boolean.

Default value:false

This property signals whether a node is read-only, in which case form controls attached to the node won't allow the user to change data.

Form controls take a hint from the readonly property and are expected to distinctly render a read-only condition; for example, by dimming the form control.

required

Allowed values:any XPath expression; the result is interpreted as a boolean.

Default value:false

This property signals whether a value is required in this node for the form to be considered valid. A node satisfies the required condition when it is convertible into a string with one or more characters.

Form controls take a hint from the required property. Form controls are required to distinguish between valid and invalid states, and satisfying this property is a part of validity.

relevant

Allowed values:any XPath expression; the result is interpreted as a boolean.

Default value:true

This property signals whether a node is currently relevant to the form. Form controls bound to non-relevant nodes are either disabled or completely invisible. Non-relevant nodes are not even submitted with the rest of the data.

Form controls are directly affected by this property, and will be disabled or hidden depending on the implementation. One interaction to watch out for is when a non-relevant field is required. In that case, the required property won't hold, although if the node were to become relevant again, it would still be required.

calculate

Allowed values:any XPath expression; the result is interpreted as a string.

Default value:none

This property defines a calculation used to determine the value of the node.

It's important that interrelated calculations run in the proper order, and XForms takes care of this by analyzing the dependencies and correctly ordering the individual computations.

It's not wise to attach an editable form control to a calculated node, since the XForms specification gives recalculation engines the freedom to recalculate at nearly any given time. As part of the recalculation processing, any new information entered into the form control will get wiped out.

constraint

Allowed values:any XPath expression; the result is interpreted as a boolean.

Default value:true

This property imposes an additional XPath-based constraint on the validity of the attached node.

If the XPath expression with this property evaluates to false, the attached node is guaranteed to be invalid. If it evaluates to true, however, it's still possible (through XML Schema constraints) that the attached node might be invalid.

minOccurs and maxOccurs

Earlier drafts of the XForms Specification included model item properties for minOccurs and maxOccurs, designed to restrict the number of times a repeated node could occur. Difficulties arose in describing how these would actually work, since any given sequence of repeating nodes could have differing restrictions on each node.

Such restrictions can still be done with the calculate property, as shown in this example, which restricts the number of item children to more than zero and less than ten:

<xforms:bind nodeset="items" constraint="count(item) &gt; 0 and  count(item) &lt; 10"/>

p3ptype

Allowed values:any valid P3P datatype identifier.

Default value:none

This property associates a P3P datatype identifier with a node.

The Platform for Privacy Preferences (P3P) is a W3C specification that describes a machine-readable profile of what personally identifiable information is collected by a web site especially forms. The main use of this property is to give P3P-compliant browsers enough information, at a granular enough level, to offer users flexible choices in how much personal information they give out, and to whom. Another use of this property is as a key for autocomplete features. IE6 and Netscape 6 already both have the capability to remember things entered into forms, but matching the right data to the right part of the form has always been hit-or-miss. With the rich expressive capability of P3P datatypes, this problem is a thing of the past.