Model Item Properties

6 Model Item Properties

This chapter defines infoset contributions that can be bound to instance data nodes with element bind (see 3.3.4 The bind Element). The combination of these contributions to an instance data node is called a model item. Taken together, these contributions are called model item properties, and are defined in the following section. In contrast, the term Schema constraint refers only to XML Schema constraints from the facets of a given datatype.

6.1 Model Item Property Definitions

Model item properties can be distinguished along various axes.

Computed expressions vs. fixed properties:

Fixed properties are static values that the XForms Processor evaluates only once. Such properties consist of literals, and are not subject to XPath evaluation.
Computed expressions are XPath expressions that provide a value to the XForms Processor. Such values are recalculated at certain times as specified by the XForms Processing Model (see 4 Processing Model). These expressions encode dynamic properties, often constraints, such as the dependency among various data items. Computed expressions are not restricted to examining the value of the instance data node to which they apply. XPath expressions provide the means to traverse the instance data; more complex computations may be encoded as call-outs to external scripts.

Inheritance rules:

Some model item properties define inheritance rules, in which case the XForms Processor needs to keep track of two separate values: 1) the local value, which is applied from an attribute of element bind, and 2) the inherited value, which is determined by combining the evaluated local value with the evaluated values from ancestor nodes in the instance data.

Note:

The sample recalculation algorithm defined in D Recalculation Sequence Algorithm is defined to operate only on the local values of a model item property. It assumes that an implementation propagates the combined values to a node's descendants.

Assigning local values:

Local values are assigned by processing all bind elements in an XForms Model in document order. It is an error to attempt to set a model item property twice on the same node. The details of this process are given at 4.2.1 The xforms-model-construct Event.

The following sections list the model item properties available as part of all model items. For each, the following information is provided:

Description
Computed Expression (yes or no)
Legal Values
Default Value
Inheritance Rules

6.1.1 The type Property

Description: associates a Schema datatype.

Computed Expression: No.

Legal Values: Any xsd:QName representing a datatype definition in an XML Schema.

Default Value: xsd:string.

Inheritance Rules: does not inherit.

The effect of this model item property is the same as placing attribute xsi:type on the instance data. However, in contrast to xsi:type, type can be added to both elements and attributes.

Example: Attaching a XML Schema type constraint

<instance>
  <my:person-name>
    <my:first-name />
    <my:last-name xsi:type="my:nonEmptyString" />
  </my:person-name>
</instance>
<bind type="my:nonEmptyString" nodeset="/my:person-name/my:first-name" />

Here, we have illustrated two ways in which an XML Schema type can be associated with an element.

6.1.2 The readonly Property

Description: describes whether the value is restricted from changing.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath boolean with boolean().

Default Value: false(), unless a calculate property is specified, then true().

Inheritance Rules: If any ancestor node evaluates to true, this value is treated as true. Otherwise, the local value is used.

Note:

This is the equivalent of taking the logical OR of the evaluated readonly property on the local and every ancestor node.

When evaluating to true, this model item property indicates that the XForms Processor should not allow any changes to the bound instance data node.

In addition to restricting value changes, the readonly model item property provides a hint to the XForms user interface. Form controls bound to instance data with the readonly model item property should indicate that entering or changing the value is not allowed. This specification does not define any effect on visibility, focus, or navigation order.

Example: Attaching a readonly property

<instance>
  <my:person-name>
    <my:first-name>Roland</my:first-name>
    <my:last-name/>
  </my:person-name>
</instance>
<bind nodeset="/my:person-name/my:first-name" readonly="true()"/>

Here, we have associated a readonly property with an element.

6.1.3 The required Property

Description: describes whether a value is required before the instance data is submitted.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath boolean with boolean().

Default Value: false().

Inheritance Rules: does not inherit.

A form may require certain values, and this requirement may be dynamic. When evaluating to true, this model item property indicates that a non-empty instance data node is required before a submission of instance data can occur. Non-empty is defined as:

If the bound instance data node is an element, the element must not have the xsi:nil attribute set to true.
The value of the bound instance data node must be convertible to an XPath string with a length greater than zero.

Except as noted below, the required model item property does not provide a hint to the XForms user interface regarding visibility, focus, or navigation order. XForms authors are strongly encouraged to make sure that form controls that accept required data are visible. An XForms Processor may provide an indication that a form control is required, and may provide immediate feedback, including limiting navigation. Chapter 4 Processing Model contains details on how the XForms Processor enforces required values.

Example: Attaching a required property

<instance>
  <my:person-name>
    <my:first-name>Roland</my:first-name>
    <my:last-name />
  </my:person-name>
</instance>
<bind nodeset="/my:person-name/my:last-name" required="true()"/>

Here, we have associated a required property with element my:last-name to indicate that a value must be supplied.

Note:

XML Schema has a similarly named concept with use="required|optional|prohibited". This is different than the XForms Model item property, in two ways: 1) use applies only to attributes, while XForms required applies to any node. 2) use is concerned with whether the entire attribute must be specified (without regard to value), while required determines whether a value is required of the node before submission.

6.1.4 The relevant Property

Description: indicates whether the model item is currently relevant. Instance data nodes with this property evaluating to false are not serialized for submission.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath boolean with boolean().

Default Value: true().

Inheritance Rules: If any ancestor node evaluates to XPath false, this value is treated as false. Otherwise, the local value is used.

Note:

This is the equivalent of taking the logical AND of the evaluated relevant property on the local and every ancestor node.

Many forms have data entry sections that depend on other conditions. For example, a form might ask whether the respondent owns a car. It is only appropriate to ask for further information about their car if they have indicated that they own one.

The relevant model item property provides hints to the XForms user interface regarding visibility, focus, and navigation order. In general, when true, associated form controls should be made visible. When false, associated form controls should be made unavailable, removed from the navigation order, and not allowed focus.

Example: Attaching a relevant property

<instance>
  <my:order>
    <my:item>
      <my:amount />
      <my:discount>100</my:discount>
    </my:item>
  </my:order>
</instance>
<bind nodeset="my:item/my:discount" readonly="true()"
      relevant="../my:amount &gt; 1000"/>

Here, we have associated a relevant property with element my:discount to indicate a discount is relevant when the order amount is greater than 1000.

The following table shows the user interface interaction between required and relevant.

	`required="true()"`	`required="false()"`
`relevant="true()"`	The form control (and any children) must be visible or available to the user. The XForms user interface may indicate that a value is required.	The form control (and any children) must be visible or available to the user. The XForms user interface may indicate that a value is optional.
`relevant="false()"`	The form control (and any children) must be hidden or unavailable to the user. Entering a value or obtaining focus should not be allowed. The XForms user interface may indicate that should the form control become relevant, a value would be required.	The form control (and any children) must be hidden or unavailable to the user. Entering a value or obtaining focus should not be allowed.

6.1.5 The calculate Property

Description: supplies an expression used to calculate the value of the associated instance data node.

Computed Expression: Yes.

Legal Values: Any XPath expression.

Default Value: none.

Inheritance Rules: does not inherit.

An XForms Model may include model items that are computed from other values. For example, the sum over line items for quantity times unit price, or the amount of tax to be paid on an order. Such computed value can be expressed as a computed expression using the values of other model items. Chapter 4 Processing Model contains details of when and how the calculation is performed.

Example: Attaching a calculate property

<instance>
  <my:order>
    <my:item>
      <my:amount />
      <my:discount />
    </my:item>
  </my:order>
</instance>
<bind nodeset="my:item/my:discount" calculate="../my:amount * 0.1"
      relevant="../my:amount &gt; 1000"/>

Here, we have associated a relevant property with element my:discount to indicate a discount of 10% is relevant when the order amount is greater than 1000.

6.1.6 The constraint Property

Description: specifies a predicate that needs to be satisfied for the associated instance data node to be considered valid.

Computed Expression: Yes.

Legal Values: Any expression that is convertible to XPath boolean with boolean().

Default Value: true().

Inheritance Rules: does not inherit.

When evaluating to XPath false, the associated model item is not valid; the converse is not necessarily true. Chapter 4 Processing Model contains details of when and how the constraint is calculated as well as when validation is performed.

Example: Attaching a constraint property

<instance>
  <my:range>
    <my:from />
    <my:to />
  </my:range>
</instance>
<bind nodeset="my:to" constraint=". &gt; ../my:from" />

Here, a constraint property associated with element my:to indicates that its value must be greater than that of element my:from.

Note:

Specifying minimum and maximum occurrences for nodes in the instance data can be achieved by using the count() function within a constraint property.

6.1.7 The p3ptype Property

Description: Attaches a P3P data element to an instance data node, indicating the specific kind of data collected there.

Computed Expression: No.

Legal Values: xsd:string.

Default Value: none

Inheritance Rules: does not inherit.

This model item property holds a description of the kind of data collected by the associated instance data node, based on the P3P datatype system [P3P 1.0]. This information may be used to enhance the form-fill experience, for example by supplying previously-known data.

Example: Attaching a type constraint using Binding

<instance>
  <my:person-name>
    <my:first-name />
    <my:last-name />
  </my:person-name>
</instance>
<bind type="my:nonEmptyString" nodeset="my:first-name"
      p3ptype="user.personname.given"/>

Here, we have attached both XML Schema and P3P type information to element first-name via element bind.

6.2 Schema Constraints

Chapter 5 Datatypes described how XForms uses the XML Schema datatype system to constrain the value space of data values collected by an XForms Model. Such datatype constraints can be provided via an XML Schema. Alternatively, this section lists various mechanisms for attaching type constraints to instance data. Attributes xsi:schemaLocation and xsi:noNamespaceSchemaLocation are ignored for purposes for locating a Schema.

6.2.1 Atomic Datatype

The XForms Processing Model applies XML Schema facets as part of the validation process. At the simplest level, it is necessary to associate a set of facets (through an XML Schema datatype) with a model item. This has the effect of restricting the allowable values of the associated instance data node to valid representations of the lexical space of the datatype.

The set of facets associated with a model item must be determined by the following list, as if it were processed in the given order. When multiple datatype restrictions apply to the same model item, the combination of all given restrictions must apply. Note that it is possible to produce a combination of restrictions that is impossible to satisfy; authors are encouraged to avoid this practice.

An XML Schema associated with the instance data.
An XML Schema xsi:type attribute in the instance data.
An XForms type constraint associated with the instance data node using XForms binding.
If no type constraint is provided, the instance data node defaults to type="xsd:string" (default to string rule).

The following declares a datatype based on xsd:string with an additional constraining facet.

Example: Type Constraint Using XML Schema

<xsd:simpleType name="nonEmptyString">
  <xsd:restriction base="xsd:string">
    <xsd:minLength value="1"/>
  </xsd:restriction>
</xsd:simpleType>

This new datatype would then be associated with one or more model items through one of the methods outlined here.

Example: Attaching A Type Constraint

<my:first-name xsi:type="my:nonEmptyString"/>

This defines element first-name to be of type my:nonEmptyString.

Example: Attaching Type Constraint Using XForms Binding

<instance>
  <my:first-name />
</instance>
<bind type="my:nonEmptyString" nodeset="/my:first-name"/>

Here, we have attached type information to element first-name via element bind. Thus the XForms author can extend external schemas without having the ability to change them.


Table of Contents	Prev	Next	Bottom