previous   next   contents

5 XForms Model


Contents

This chapter is normative.

5.1 Introduction

The XForms Model supports XML Schema built-in datatypes such as string and custom datatypes defined using XML Schema syntax.

This chapter goes into further detail on the XForms simple syntax. XForms simple syntax is designed for easy hand-authoring and is targeted at HTML authors. Simple syntax provides an easy to learn interface for HTML authors; it achieves its simplicity by providing a smaller range of functionality than that afforded by XML Schemas. Specifically, XForms simple syntax allows the author to:

In order to stay simple, simple syntax does not permit the definition of reusable datatypes. Instead, reusable datatypes can be defined in XML Schema and instantiated using XForms simple syntax as described here.

Later on, this chapter discusses ways to combine XForms simple syntax with XML Schema.

5.2 Model Item Properties

The following model item properties are similar in syntax to constraining datatype facets. Instead of constraining the value space of a datatype, however, they add properties such as readOnly or required to individual model items. The following properties are available for all datatypes, and their syntax is explained later in this document.

Many model item properties can be represented by the Dynamic Constraints Language, and may evaluate to values that can change at any time. XForms Processors that implement form controls need to dynamically update as the evaluated properties change.

5.2.1 Model Item Property: name

Description: provides a specific name for the declaring datatype.

Legal Values: only values of type xsd:NCNAME

Default Value: none.

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

When using simple syntax to define elements that appear in the instance data, the name property provides the corresponding element name, as shown in the atomic datatype example below.

5.2.2 Model Item Property: readOnly

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

Legal Values: any expression that evaluates to xform:boolean.

Default Value: false.

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 tab order.

[Editor's Feedback Request 5.2.2.constant: Should it be possible to make the readOnly facet immutable? i.e. if an element in marked as read-only and immutable, then the XForms Processor could rely on the facet not changing and employ a different rendering. Do we need a "constant"? ]

5.2.3 Model Item Property: required

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

Legal Values: any expression that evaluates to xform:Boolean

Default Value: false.

Often forms require certain values to be entered. Within XForms, this may be a static requirement and defined in an XML Schema (e.g. xsd:minOccurs="1"). Alternatively a value may only be required if some condition is satisfied.

Except as noted below, the required property does not provide a hint to the XForms User Interface regarding visibility, focus, or tab 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.

Note: Suspend and resume operations are not restricted by the required property.

Note: As with the constraining facets, conflicting properties are resolved by choosing the most restrictive. For instance, if xform:required="false" was specified but xsd:minOccurs="1" was also defined by the Schema for the element, the element would still be required.

[Editor's Feedback Request 5.2.3.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..]

[Editor's Feedback Request 5.2.3.null: Null values; XML Schema nullable="true". We have not yet addressed the subject of null. It is of particular relevance for required items.]

5.2.4 Model Item Property: 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.

Legal Values: any expression that evaluates to xform: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 information about their car if they have indicated that they own one. In XForms, this occurs through the relevant property.

The relevant property provides hints to the XForms User Interface regarding visibility, focus, and tab order. In general, when true, associated form controls should be made visible. When false, associated form controls should be hidden, though an XForms Processor may only disable the form controls. In either case, the form controls should be removed from the tab order and not allowed focus.

The following table shows the 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.5 Model Item Property: calculate

Description: indicates that the value of the declaring datatype is to be dynamically calculated.

Legal Values: any expression that evaluates to a datatype compatible with the declaring 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 an Dynamic Constraint using the values of other model items.

5.2.6 Model Item Property: priority

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

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

Default Value: 0.

For model items that are calculated, this optional property specifies a calculation order.

5.2.7 Model Item Property: validate

Description: indicates that the value of the declaring datatype is to be dynamically validated.

Legal Values: any expression that evaluates to xform:Boolean

Default Value: true.

An XForms Model may include model items that need to be validated. The specified Dynamic Constraint is invoked every time the value of the declaring datatype changes. The expression must evaluate to true for the model item to be considered valid. Future versions of this specification will describe details such as immediate validation vs. onsubmit validation.

Dynamic Constraints used here are not restricted to examining the instance data item they are invoked on. The Dynamic Constraints Language provides the means to traverse the instance data, as well as call-outs to external script.

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

[Editor's Feedback Request 5.2.7.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

The basic datatypes defined by XForms can be used individually or aggregated to build appropriate structures for use in XForms applications. XForms provides a number of structures that are mapped to corresponding constructs in XML Schema.

XForms Processors that are Schema compliant can use arbitrarily complex Schema constructs in the XForms Model. The full Schema syntax can be found in [XSchema-1] and [XSchema-2].

5.3.1 Atomic Datatype

Description: inserts an atomic datatype into the XForms Model.

Simple Syntax: for each atomic datatype in the Datatypes chapter, the simple syntax specifies an element with a matching name in the XForms Namespace. Optional allowed attributes in the XForms Namespace are the XForms constraining facets and model item properties, except as noted below. The element content is empty, except as noted below:

XML Representation :  atomic datatypes 
<datatype-name
  id = xsd:ID
  datatype-facet-name  = value
  <!-- ... additional datatype facets ... -->
  model-item-property-name = value
  <!-- ... additional model item properties ... -->
  enum = ("open" | "closed") : "open"
  choices = dynamic-constraint

  <!-- exceptions noted below -->
>
  <!-- Content: described in this and the following section -->
</datatype-name>

Attribute Definitions:

id = xsd:ID
Optional unique identifier.
enum = ("open" | "closed") : "open"
Optional enumeration specifier, with details given below.
choices = dynamic-constraint
Optional dynamic constraint that produces an enumeration list dynamically.

Syntax Exceptions:

Editor's Note: <money> may not be considered an atomic datatype (see the Editor's Feedback Request in the Datatypes chapter), and thus may be considered a structure rather than a datatype.

A method is needed to include datatypes defined elsewhere (such as in Schema format) into the XForms Model. One syntax proposal is:

Example Simple Syntax:

<xform:string name="foo" minLength="1" />

Example Equivalent Schema Syntax:

<xsd:element name="foo">
  <xsd:complexType>
    <xsd:restriction base="xform:string">
      <xform:minLength value="1"/>
    </xsd:restriction>
  </xsd:complexType>
</xsd:element>

Second Example Simple Syntax:

<xform:binary name="foo">
  <xform:mediaType>image/jpg</xform:mediaType>
  <xform:mediaType>image/png</xform:mediaType>
</xform:binary>

Second Example Equivalent Schema Syntax:

<xsd:element name="foo">
  <xsd:complexType>
    <xsd:restriction base="xform:binary">
      <xsd:mediaType value="image/jpg"/>
      <xsd:mediaType value="image/png"/>
    </xsd:restriction>
  </xsd:complexType>
</xsd:element>

5.3.2 Enumerated Datatype

Description: inserts an atomic datatype, with a restricting enumeration, into the XForms Model. Enumerations are mentioned separately here only because of their special syntax.

Simple Syntax: an enumerated datatype is declared as an atomic datatype above, with the additional syntax as follows:

XML Representation :  <value> 
<value
  id = xsd:ID
>
  <!-- Content: #PCDATA -->
</value>

Attribute Definitions:

id = xsd:ID
Optional unique identifier.

Note that an open enumeration is useful for scenarios like the following, where a multiple choice question has an "other" option:

showing radio buttons, Visa, Master Card, Diner's Club, American Express, and 'other', where the user can freely enter a value

Editor's Note: functionality similar to open enumerations is available in XML Schema through the combination of union and enumeration features.

Simple Syntax:

<xform:string name="foo" enum="closed">
  <xform:value>Visa</xform:value>
  <xform:value>MasterCard</xform:value>
  <xform:value>Diner's Club</xform:value>
  <xform:value>American Express</xform:value>
</xform:string>

Equivalent Schema Syntax:

<xsd:element name="foo" enum="closed">
  <xsd:complexType>
    <xsd:restriction base="xform:string">
      <xsd:enumeration value="Mastercard"/>
      <xsd:enumeration value="Diner's Club"/>
      <xsd:enumeration value="American Express"/>
    </xsd:restriction>
  </xsd:complexType>
</xsd:element>

Simple Syntax with Dynamic Choices:

<xform:string name="foo" enum="closed" choices="getCreditCardList()"/>

5.3.3 Group

Description: allows aggregate hierarchical arrangement of ordered datatypes.

Simple Syntax: the simple syntax specifies the element <group>, with the possible attributes representing the model item properties.

XML Representation :  <group> 
<group
  id = xsd:ID
  name = xsd:NCNAME
>
  <!-- Content: (group | union | array | switch | atomic-datatypes)* -->
</group>

Attribute Definitions:

id = xsd:ID
Optional unique identifier.
name = xsd:NCNAME
Required name for the group.

Example Simple Syntax:

<xform:group name="person">
  <xform:string name="personName"/>
  <xform:string name="personTitle"/>
</xform:group>

Example Equivalent Schema Syntax:

<xsd:group name="person">
  <xsd:sequence>
    <xsd:element name="personName" type="xform:string"/>
    <xsd:element name="personTitle" type="xform:string"/>
  </xsd:sequence>
</xsd:group>

Note that here element person does not define a new datatype; when mapped to XML Schema syntax; i.e. person is an anonymous type that cannot be reused.

[Editor's Feedback Request 5.3.3.unordered-group: The Working Group is looking for feedback on whether the option for an unordered group is necessary in addition to the ordered group as described above.]

5.3.4 Union

Description: allows differing datatypes to be bound to a single model item.

Simple Syntax: the simple syntax specifies the element <union>, with the possible attributes representing the model item properties. Child datatypes do not require the name attribute.

[Editor's Feedback Request 5.3.4.names: Should the name attribute be required for each of the elements within a union?

XML Representation :  <union> 
<union
  id = xsd:ID
  name = xsd:NCNAME
>
  <!-- Content: (group | union | array | switch | atomic-datatypes)* -->
</union>

Attribute Definitions:

id = xsd:ID
Optional unique identifier.
Name = xsd:NCNAME
Required name for the union.

Example Simple Syntax:

<xform:union name="weekday">
  <xform:string enum="closed">
    <xform:value>Monday</xform:value>
    <xform:value>Tuesday</xform:value>
    <xform:value>Wednesday</xform:value>
    <xform:value>Thursday</xform:value>
    <xform:value>Friday</xform:value>
    <xform:value>Saturday</xform:value>
    <xform:value>Sunday</xform:value>
  </xform:string>
  <xform:number min="1" max="7" scale="0"/>
</xform:union>

Example Equivalent Schema Syntax:

<xsd:element name="weekday">
  <xsd:simpleType>
    <xsd:union>
      <xsd:simpleType>
        <xsd:restriction base="xform:string">
          <xsd:enumeration value="Monday"/>
          <xsd:enumeration value="Tuesday"/>
          <xsd:enumeration value="Wednesday"/>
          <xsd:enumeration value="Thursday"/>
          <xsd:enumeration value="Friday"/>
          <xsd:enumeration value="Saturday"/>
          <xsd:enumeration value="Sunday"/>
        </xsd:restriction>
      </xsd:simpleType>
      <xsd:simpleType>
        <xsd:restriction base="xform:decimal">
          <xsd:maxInclusive value="7"/>
          <xsd:minInclusive value="1"/>
          <xsd:scale value="0"/>
        </xsd:restriction>
      </xsd:simpleType>
    </xsd:union>
  </xsd:simpleType>
</xsd:element>

5.3.5 Array

Description: allows homogeneous collections (i.e., all members of an array are the same structure).

Simple Syntax: the simple syntax specifies the element <array>, with the possible attributes representing the model item properties.

XML Representation :  <array> 
<array
  id = xsd:ID
  name = xsd:NCNAME
  minOccurs = xform:number : 1
  maxOccurs = (xform:number | "unbounded") : 1
>
  <!-- Content: (group | union | array | switch | atomic-datatypes)* -->
</array>

Attribute Definitions:

id = xsd:ID
Optional unique identifier.
Name = xsd:NCNAME
Optional name for the array. Note: The author has the ability to specify whether a containing element for the repeating elements is produced. If a name is specified for the array then a containing element will be created where the containing element name will be derived from the name of the array. If no name is provided for the array then no containing element will be created.
minOccurs = xform:number
Optional restriction for the minimum number of elements in the array.
maxOccurs = xform:number | "unbounded"
Optional restriction for the maximum number of elements in the array, or "unbounded" for no restriction.

Example Simple Syntax:

<xform:array name="children" minOccurs="0" maxOccurs="unbounded">
  <xform:string name="child" />
</xform:array>

Example Equivalent Schema Syntax:

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

Second Example Simple Syntax:

<xform:array minOccurs="0" maxOccurs="unbounded">
  <xform:string name="child" />
</xform:array>

Second Example Equivalent Schema Syntax:

 <xsd:element name="child" type="xform:string"  minOccurs="0" maxOccurs="unbounded"/>
 
<!-- note this syntax is only valid inside a group -->

5.3.6 Switch

Description: allows alternative structures to be defined within simple syntax and for a Dynamic Constraint to determine which should be created in the instance data.

Simple Syntax: the simple syntax specifies the element <switch>, with the possible attributes representing the model item properties. The content model consists of <case> elements, which in turn contain datatype declarations. The <case> elements have two attributes: name from the model item properties, and condition, which consists of a script to validate.

XML Representation :  <switch> 
<switch
  id = xsd:ID
  name = xsd:NCNAME
>
  <!-- Content: (case)* -->
</switch>

Attribute Definitions:

id = xsd:ID
Optional unique identifier.
Name = xsd:NCNAME
Required name for the switch.
XML Representation :  <case> 
<case
  id = xsd:ID
  name = xsd:NCNAME
  condition = dynamic-constraint
>
  <!-- Content: (group | union | array | switch | atomic-datatypes)* -->
</case>

Attribute Definitions:

id = xsd:ID
Optional unique identifier.
Name = xsd:NCNAME
Required name for a specific case
condition = dynamic-constraint
Optional dynamic constraint; the condition used to select this case statement. A maximum of one case may be without a condition, this will be considered the default case.

Example Simple Syntax:

<xform:switch name="address">
  <xform:case name="us" condition="property(locale) is 'US'" >
    <xform:string name="street"/>
    <xform:string name="city"/>
    <xform:string name="state"/>
    <xform:string name="zip"/>
  </xform:case>
  <xform:case name="uk" condition="property(locale) is 'UK'" >
    <xform:string name="street"/>
    <xform:string name="town"/>
    <xform:string name="county"/>
    <xform:string name="postcode"/>
  </xform:case>
  <xform:case name="default">
    <xform:string name="street"/>
    <xform:string name="town"/>
    <xform:string name="county"/>
    <xform:string name="postcode"/>
  </xform:case>
</xform:switch>

Example Equivalent Schema Syntax:

<xsd:choice>
  <xsd:element name="address">
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="street"   type="xform:string"/>
        <xsd:element name="city"     type="xform:string"/>
        <xsd:element name="state"    type="xform:string"/>
        <xsd:element name="zip"      type="xform:string"/>
      </xsd:sequence>
      <xsd:attribute name="xform:caseName" type="xsd:string"
              use="fixed" value="us"/>
      <xsd:attribute name="xform:caseCondition" type="xform:xfmExpr" 
              use="fixed" value=" property(locale) is 'US'"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="address" >
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="street"   type="xform:string"/>
        <xsd:element name="town"     type="xform:string"/>
        <xsd:element name="county"   type="xform:string"/>
        <xsd:element name="postcode" type="xform:string"/>
      </xsd:sequence>
      <xsd:attribute name="xform:caseName" type="xsd:string" 
              use="fixed" value="UK"/>
      <xsd:attribute name="xform:caseCondition" type="xform:xfmExpr"
              use="fixed" value=" property::locale is 'UK'"/>
    </xsd:complexType>
  </xsd:element>
  <xsd:element name="address" >
    <xsd:complexType>
      <xsd:sequence>
        <xsd:element name="street"   type="xform:string"/>
        <xsd:element name="town"     type="xform:string"/>
        <xsd:element name="county"   type="xform:string"/>
        <xsd:element name="postcode" type="xform:string"/>
      </xsd:sequence>
      <xsd:attribute name="xform:caseName" type="xsd:string"
              use="fixed" value="default"/>
    </xsd:complexType>
  </xsd:element>
</xsd:choice>

Note that this capability is an extension of the XML Schema choice.

Editor's Note: This impacts instance data, XForms User Interface, the XForms Model, and the binding between them. An XForms Model can exploit the switch construct to define a number of variants and to determine at runtime which single variant should be created in the instance.

5.4 Combining XForms and XML Schema

XML Schema allows annotations as foreign namespaced attributes. Adding elements is more problematic. Future versions of this specification will specify in greater detail how XForms datatypes, properties, and structures can be used within XML Schema.

5.4.1 Annotating an External Schema

XForms authors may wish to reuse datatypes and structures already defined in an external XML Schema. For use in an XForms application, such schemas may need to be annotated using XForms dynamic properties for expressing run-time constraints.

Future versions of this specification will describe how to add XForms annotations to an external Schema by reference without modifying the original Schema.

One syntax proposal is:

previous   next   contents