Table of Contents | Prev | Next | Bottom |
Quick Table of Contents |
---|
6 Model Item Properties 6.1 Model Item Property Definitions 6.1.1 The type Property 6.1.2 The readonly Property 6.1.3 The required Property 6.1.4 The relevant Property 6.1.5 The calculate Property 6.1.6 The constraint Property 6.1.7 The maxOccurs Property 6.1.8 The minOccurs Property 6.1.9 The p3ptype Property 6.2 Schema Constraints 6.2.1 Atomic Datatype |
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.
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.2 The xforms-model-initialize 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
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.
<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.
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.
<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.
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.
<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.
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.
<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 > 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. |
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.
<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 > 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.
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.
<instance> <my:range> <my:from /> <my:to /> </my:range> </instance> <bind nodeset="my:to" constraint=". > ../my:from" />
Here, we have associated a constraint
property with
element my:to
to indicate that its value must be
greater than that of element my:from
.
Description: for repeating structures, indicates the maximum number of allowed element nodes.
Computed Expression: Yes.
Legal Values: Any XPath expression. The result is evaluated as an XPath Number.
Default Value: INF
.
Inheritance Rules: does not inherit.
For model item elements that are repeated, this optional model
item property specifies a maximum number of allowed element nodes.
Negative results, Infinity, or NaN
have the effect of
not setting any limit.
<instance> <my:order> <my:item> <my:amount /> <my:discount /> <my:item> </my:order> </instance> <bind nodeset="my:item" minOccurs="1" maxOccurs="4" />
Here, the example associates both minOccurs
and
maxOccurs
properties with element my:item
to indicate that there must be a minimum of one and a maximum four
elements my:item
for the instance to be considered
valid.
Note:
XForms model item properties minOccurs
and
maxOccurs
are designed to be isomorphic to the
corresponding XML Schema facets minOccurs
and
maxOccurs
. The properties minOccurs
and
maxOccurs
are intended to specify the cardinality of a
set and therefore should not be applied to individual members of
the nodeset. Thus, <bind nodeset="/bookmarks/bookmark"
minOccurs="8"/>
is meaningful, but it is undefined to
apply this property to an individual member of the nodeset e.g.,
<bind nodeset="/bookmarks/bookmark[1]"
minOccurs="8"/>
Description: for repeating structures, indicates the minimum number of allowed element nodes.
Computed Expression: Yes.
Legal Values: Any XPath expression. The result is evaluated as an XPath Number.
Default Value: 0.
Inheritance Rules: does not inherit.
For model item elements that are repeated, this optional model
item property specifies a minimum number of allowed element nodes.
Negative results, Infinity, or NaN
have the effect of
not setting any limit.
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 from a server.
<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
.
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. XForms Basic processors have restricted
Schema processing requirements as defined in 12.1.2 XForms
Basic.
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 may be associated with a model item in one of the following ways (only the first that applies is used, and if multiple type constraints apply to the same node, the first definition in document order is used).
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.
<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.
<my:first-name xsi:type="my:nonEmptyString"/>
This defines element first-name
to be of type
my:nonEmptyString
.
<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 | Top |