The XForms Model

5 The XForms Model

5.1 Introduction

Chapter 4 Datatypes described how XForms uses the XML Schema datatyping system, which can constrain the value space of datatypes that can be used in data collection. This chapter introduces a different set of properties, called model item properties, which define XForms-specific behaviors and metadata useful for data collection.

5.2 Model Item Properties

Model item properties fall into two basic categories:

Computed expressions are XPath expressions that provide a value to the XForms Processor. The value is recomputed at certain times, according to the XForms Processing Model (see 11 Processing Model).
All other properties are fixed, static values that the XForms Processor evaluates only once.

The following properties are available for all model items, and their syntax is explained throughout this chapter. For each property the following information is provided:

Description
Computed Expression (yes or no)
Legal Values
Default Value
Additional descriptive text

5.2.1 name

Description: provides a specific name for the model item.

Computed Expression: No

Legal Values: only values of type xsd:NCName

Default Value: none.

Authors can associate a human-readable name with a model item through the use of the name property. Each name should be unique within the scope of the XForms Model where it is declared.

5.2.2 type

Description: assigns a Schema datatype.

Computed Expression: No

Legal Values: any xsd:QName representing a Schema datatype.

Default Value: xsd:anyType

The concept of typed data is important to forms. The assignment of a particular datatype to a model item affects validation of the data it can accept, as well as affecting which form controls to which it can bind.

Note:

The XForms Model uses properties "name" and "type" as in XML Schema; the concrete syntax used to define XForm Models, and consequently the use of these properties will be made concrete in a forthcoming revision of this Working Draft.

5.2.3 readOnly

Description: describes whether the value is restricted from changing. The ability of form controls to have focus and appear in the navigation order is unaffected by this property.

Computed Expression: Yes

Legal Values: any expression is convertible to boolean.

Default Value: false.

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

In addition to restricting value changes, the readOnly property provides a hint to the XForms User Interface. Form controls bound to a model item with the readOnly property should indicate that entering or changing the value is not allowed. The hint provided has no effect on visibility, focus, or navigation order.

5.2.4 required

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

Computed Expression: Yes

Legal Values: any expression that is convertible to boolean

Default Value: false.

Often forms require certain values to be entered. This may be a static requirement, or may only be the case if some condition is satisfied. When evaluating to true, this property indicates that a non-empty instance data item is required before a submission of instance data can occur. Non-empty is defined as:

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

Except as noted below, the required 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 a unique indication that a form control is required, and may provide immediate feedback, including limiting navigation, for required form controls.

Issue (issue-default-default):

It might be useful to set the default for the required attribute for an entire XForms Model. What should the default default be? How could we assign a default for a single XForms Model? This could apply to other attributes as well, e.g. readOnly, etc...

The chapter 11 Processing Model contains details on how the XForms Processor enforces required values.

5.2.5 relevant

Description: indicates whether the model item is currently relevant to the rest of the XForms Model. XForms Processors would typically not render an associated form control, including children, when the value is false.

Computed Expression: Yes

Legal Values: any expression is convertible to boolean

Default Value: true.

Many forms have fields dependent 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.

When evaluating to true, this property indicates that the XForms Processor should render a form control, and conversely, when evaluating to false, indicates that the form control should not be rendered.

The relevant 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.

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

	`required="true"`	`required="false"`
`relevant="true"`	The form control (and any children) should be visible or available to the user. The XForms User Interface may indicate that a value is required.	The form control (and any children) should 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) should 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) should be hidden or unavailable to the user. Entering a value or obtaining focus should not be allowed.

5.2.6 calculate

Description: indicates that the instance data item associated with the model item is to be dynamically calculated.

Computed Expression: Yes

Legal Values: any expression is convertible to an XPath datatype compatible with the associated XML Schema datatype.

Default Value: none.

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

5.2.7 priority

Description: indicates the relative priority for calculations of the model item.

Computed Expression: No

Legal Values: any expression that is convertible to an integer in the range 0-32767.

Default Value: 0.

For model items that are calculated, this optional property specifies a calculation order. The XForms Processing Model uses this property to determine the calculation order for multiple calculations.

5.2.8 validate

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

Computed Expression: Yes

Legal Values: any expression that is convertible to boolean

Default Value: true.

An XForms Model may include model items that need to be validated. When evaluating to true, indicates that the model item is considered valid. The chapter 11 Processing Model describes details such as immediate validation vs. onsubmit validation.

Computed expressions used here are not restricted to examining the instance data item they are invoked on. XPath, plus the extensions in this chapter, provide the means to traverse the instance data, as well as call-outs to external script, enabling potentially complex validations.

The XForms User Interface may indicate whether a form control is currently valid or invalid.

Issue (issue-cascade):

Will the validate property be evaluated on all the parent or child model items whenever a value changes? We need to make sure that inter-model item constraints will get evaluated.

5.3 Using Datatypes in the XForms Model

The following section is being rewritten with the guidance of the XML Schema Working Group. In its current state, it is an informative listing of the functionality that we are planning in XForms 1.0, with illustrative examples of similar functionality in XML Schema. A subsequent Working Draft will contain normative details on how the functionality is described in terms of XForms.

5.3.1 Atomic Datatype

At the simplest level, it is necessary to associate a datatype with a model item. This has the effect of restricting the allowable values of the associated instance data item to valid representations of the lexical space of the datatype, including enforcing of any constraining facets.

Example Schema Syntax: declaring a datatype based on an xsd:string plus additional constraining facet would be accomplished as follows:

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

5.3.2 Closed Enumeration

Often it is necessary to restrict the allowable values of the associated instance data item to a closed list of alternatives. Also under consideration is a method to obtain a list at runtime, for example, from an XPath node-set.

Example Schema Syntax: declaring a datatype allowing enumerated values of an xsd:string would be accomplished as follows:

<xsd:simpleType>
  <xsd:restriction base="xsd:string">
    <xsd:enumeration value="Mastercard"/>
    <xsd:enumeration value="Diner's Club"/>
    <xsd:enumeration value="American Express"/>
  </xsd:restriction>
</xsd:simpleType>

5.3.3 Open Enumeration

A special case of enumerated datatypes is the common form design pattern of a list, with an 'other, please specify' choice. This is referred to as an open enumeration.

Example Schema Syntax: declaring an open enumeration is possible through a combination of union and enumeration features, as follows:

<xsd:simpleType>
  <xsd:union memberTypes="xsd:string">
    <xsd:simpleType>
      <xsd:restriction base="xsd:string">
        <xsd:enumeration value="Mastercard"/>
        <xsd:enumeration value="Diner's Club"/>
        <xsd:enumeration value="American Express"/>
      </xsd:restriction>
    </xsd:simpleType>
  </xsd:union>
</xsd:simpleType>

5.3.4 Union

It may be desirable for data collection purpose to allow an instance data item to be a valid lexical value of one among several datatypes. Unions are defined in XML Schema.

Example Schema Syntax: declaring a datatype allowing either a creditCardType or bonusProgramType value would be as follows:

<xsd:simpleType>
  <xsd:union memberTypes="creditCardType bonusProgramType"/>
</xsd:simpleType>

5.3.5 Multiple Selection

Some form controls, such as selectMany, have the notion of supporting more than one simpleType value at any given time. This corresponds with Schema list datatypes.

Example Schema Syntax: declaring a list-derived datatype would be as follows:

<xsd:simpleType name="listOfMyIntType">
  <xsd:list itemType="xsd:int"/>
</xsd:simpleType>

5.3.6 Repeating Line Item

It is common for certain types of forms, such as order forms, to contain repeating structures, typically line items. If each individual structure were represented as a Schema complexType, a line item group would be analogous to the sequence construct.

Example Schema Syntax: a datatype allowing a sequence of child elements would be declared as follows:

<xsd:complexType>
  <xsd:sequence>
    <xsd:element name="child" type="xform:string" minOccurs="0" maxOccurs="unbounded"/>
  </xsd:sequence>
</xsd:complexType>

Chapter 8 XForms User Interface contains details on representing this with XForms User Interface form controls, as well as details for how this relates to the instance data in chapter 11 Processing Model.

5.3.7 Alternate Representation

In some forms, alternate representations might be necessary for underlying instance data structures.

Example Schema Syntax: a Schema choice element is roughly analogous to this, although XForms uses a more dynamic version. Examples of this are found in 8 XForms User Interface


Table of Contents	Prev	Next	Bottom