XForms 1.2 Data Layer -- Review Version

1 About the XForms Data Layer Specification

1.1 Background

Managing data, independent from an associated user interface, is an important part of Web applications. Web applications and electronic commerce solutions have sparked the demand for richer interactions with data including asynchronous communication with external services, declarative binding to UI controls, and associated access functions for manipulating data. The XForms Data Layer is the response to this demand, and provides a new platform-independent markup language for storing, binding to, and manipulating XML data in a variety of host languages.

XForms itself is the broader specification including not only a data layer but abstract UI controls and submission features, which collectively provide the successor to HTML forms, and benefit from the lessons learned from HTML forms. Further background information on XForms can be found at http://www.w3.org/MarkUp/Forms.

1.2 Reading the Specification

Editorial note: Need to finish intro text for data layer
To be done: finish adapting this text to the specifics of the data layer!

This specification has been written with various types of readers in mind—in particular XForms authors and XForms implementors. We hope the specification will provide authors with the tools they need to write efficient, attractive and accessible documents without overexposing them to the XForms implementation details. Implementors, however, should find all they need to build conforming XForms Processors. The specification begins with a general presentation of XForms before specifying the technical details of the various XForms components.

The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.

This document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119].

1.3 How the Specification is Organized

The specification is organized into the following chapters:

Chapter 1: An introduction to XForms. The introduction outlines the design principles and includes a brief tutorial on XForms.
Chapters 2 and up: XForms Data Layer reference manual. The bulk of the reference manual consists of the specification of the XForms Data Island, Binding Attributes, Processing Model, and XPath Functions modules.
Appendixes: Appendixes contain references, examples, and other useful information.

1.4 Documentation Conventions

Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:

xforms: The XForms namespace, e.g. http://www.w3.org/2002/xforms (see ???)
html: An XHTML namespace, e.g. http://www.w3.org/1999/xhtml (see [XHTML 1.0])
xs: The XML Schema namespace http://www.w3.org/2001/XMLSchema (see [XML Schema part 1])
xsd: The XML Schema namespace http://www.w3.org/2001/XMLSchema (see [XML Schema part 2])
xsi: The XML Schema for instances namespace http://www.w3.org/2001/XMLSchema-instance (see [XML Schema part 1])
ev: The XML Events namespace http://www.w3.org/2001/xml-events (see [XML Events])
my: Any user defined namespace

This is only a convention; any namespace prefix may be used in practice.

The following typographical conventions are used to present technical material in this document.

Official terms are defined in the following manner: [Definition: You can find most terms in chapter 8 Glossary Of Terms]. Links to terms may be specially highlighted where necessary.

The XML representations of various elements within XForms are presented using the syntax for Abstract Modules in XHTML Modularization [XHTML Modularization].

Examples are set off typographically:

Example item

Example Item

References to external documents appear as follows: [Sample Reference] with links to the references section of this document.

Sample Reference: Reference - linked to from above.

The following typesetting convention is used for additional commentary:

Note:

A gentle explanation to readers.

Editorial note: Editorial Note Name
Editorial commentary, not intended for final publication.

Issue (sample-implementation-issue):

Issue-Name

A specific issue for which input from implementors is requested, for example as part of the Candidate Recommendation phase.

Resolution:

None recorded.

2 Introduction to the XForms Data Layer

XForms has been designed on the basis of several years' experience with HTML forms. HTML forms have formed the backbone of the e-commerce revolution, and having shown their worth, have also indicated numerous ways they could be improved.

The primary difference when comparing XForms with HTML forms, apart from XForms being in XML, is the separation of the data being collected from the markup of the controls collecting the individual values. By doing this, it not only makes XForms more tractable by making it clear what is being submitted where, it also eases reuse of forms, since the underlying essential part of a Form is no longer irretrievably bound to the page it is used in.

A second major difference is that XForms, while designed to be integrated into XHTML, is no longer restricted only to be a part of that language, but may be integrated into any suitable markup language.

XForms has striven to improve authoring, reuse, internationalization, accessibility, usability, and device independence. Here is a summary of the primary benefits of using XForms:

Editorial note: Need to finish adapting concepts text for data layer
To be done: finish adapting this text to the specifics of the data layer!

2.1 Providing XML Instance Data

The XForms Processor can directly submit the data collected as XML. In the example, the submitted data would look like this:

Submitted Data

<ecommerce>
  <method>cc</method>
  <number>1235467789012345</number>
  <expiry>2001-08</expiry>
</ecommerce>

XForms processing keeps track of the state of the partially filled form through this instance data. Initial values for the instance data may be provided or left empty as in the example. Element instance essentially holds a skeleton XML document that gets updated as the user fills out the form. It gives the author full control on the structure of the submitted XML data, including namespace information. When the form is submitted, the instance data is serialized as an XML document. Here is an alternative version of the earlier example:

Model

<xforms:model>
  <xforms:instance>
    <payment method="cc" xmlns="http://commerce.example.com/payment">
      <number/>
      <expiry/>
    </payment>
  </xforms:instance>
  <xforms:submission action="http://example.com/submit" method="post" includenamespaceprefixes="#default"/>
</xforms:model>

In this case the submitted data would look like this:

Submitted Data

<payment method="cc" xmlns="http://commerce.example.com/payment">
  <number>1235467789012345</number>
  <expiry>2001-08</expiry>
</payment>

This design has features worth calling out:

There is complete flexibility in the structure of the XML instance data, including the use of attributes. Notice that XML namespaces are used, and that a wrapper element of the author's choosing contains the instance data.
Empty elements number and expiry serve as place-holders in the XML structure, and will be filled in with form data provided by the user.
An initial value ("cc") for the form control is provided through the instance data, in this case an attribute method. In the submitted XML, this initial value will be replaced by the user input, if the user changes the form control displaying that data.

To connect this instance data with form controls, the ref attributes on the form controls need to be changed to point to the proper part of the instance data, using binding expressions:

Binding Form Controls to Instance Nodes with ref

... xmlns:my="http://commerce.example.com/payment"
  ...
  <xforms:select1 ref="@method">...</xforms:select1>
  ...
  <xforms:input ref="my:number">...</xforms:input>
  ...
  <xforms:input ref="/my:payment/my:expiry">...</xforms:input>

Binding expressions are based on XPath [XPath 1.0], including the use of the @ character to refer to attributes, as seen here. Note that for illustrative purposes, the first two expressions make use of the XPath context node, which defaults to the top-level element (here my:payment). The third expression shows an absolute path.

3 Data Island Module

The XML Data Island Module defines the support for XML data instances in web applications. The elements and attributes included in this module are:

Element	Attributes	Minimal Content Model
instance	Common, src (xsd:anyURI), resource (xsd:anyURI)	(ANY)

3.1 The instance Element

The instance element contains or references XML data.

Editorial note: Support for non-XML Instance data
It is the hope/intent of the WG to support non-XML Instance data. As such, event names and method descriptions are kept as independent of XML Instance content as possible.

3.1.1 Instance element attributes

Common Attributes: Common

Special Attributes:

src: Optional link to externally defined initial instance data. If the link traversal fails, it is treated as an exception (???).
resource: Optional link to externally defined initial instance data. If the link is traversed and the traversal fails, it is treated as an exception (???).

3.1.2 Instance element processing

If the src attribute is given, then it takes precedence over inline content and the resource attribute, and the XML data for the instance is obtained from the link. If the src attribute is omitted, then the data for the instance is obtained from inline content if it is given or the resource attribute otherwise. If both the resource attribute and inline content are provided, the inline content takes precedence.

If the initial instance data is given by a link (from src or resource), then the instance data is formed by creating an XPath data model of the linked resource. If the link cannot be traversed, then load processing halts after dispatching a data-link-error event with a resource-uri of the link that failed.

If the initial instance data is given by inline content, then instance data is obtained by first creating a detached copy of the inline content (including namespaces inherited from the enveloping ancestors), then creating an XPath data model over the detached copy. The detached copy must consist of content that would be well-formed XML if it existed in a separate document. Note that this restricts the element content of instance to a single child element.

If creation of the XPath data model for the instance data fails due to an XML error, then instance load processing halts after dispatching a data-link-error event with a resource-uri indicating either the URI for an external instance, a fragment identifier URI reference (including the leading # mark) for an identified internal instance, or empty string for an unidentified internal instance. This error could happen, for example, if the content had no top-level element or more than one top-level element, neither of which is permitted by the grammar of XML.

Note:

All data relevant to the XPath data model must be preserved during processing and as input to submission serialization, including processing instructions, comment nodes and all whitespace.

Note:

XForms authors who need additional control over the serialization of namespace nodes can use the includenamespaceprefixes attribute on the submission element.

3.2 XML Data Island Events overview

The following events are defined by the XML Data Island Module:

Event name	Cancelable?	Bubbles?	Target element
data-instance-load	Yes	Yes	`instance`
data-instance-ready	No	Yes	`instance`
data-link-error	No	Yes	`instance`

3.2.1 The data-instance-load Event

Dispatched as an indication of: initiation of instance initialization including loading of any remote instance data indicated by src or resource attributes.

Target: instance element.

Bubbles: Yes

Cancelable: Yes

Context Info:

Property	Type	Value
resource-uri	string	The URI associated with the remote resource, if any (xsd:anyURI)

Default Action: The associated instance processor performs any steps required to access remote resources and construct or reinitialize the XPath data model for this instance.

3.2.2 The data-instance-ready Event

Dispatched as an indication of: completion of instance initialization including loading of any remote instance data indicated by src or resource attributes.

Target: instance element.

Bubbles: Yes

Cancelable: No

Context Info:

Property	Type	Value
resource-uri	string	The URI associated with the remote resource, if any (xsd:anyURI)

Default Action: None, notification only.

3.2.3 The data-link-error Event

Dispatched as an indication of: a failure to traverse or process the result of a link in a situation critical to form processing, such as schema or instance initialization.

Target: instance element performing the link

Bubbles: Yes

Cancelable: No

Context Info:

Property	Type	Value
resource-uri	string	The URI associated with the failed link (xsd:anyURI)

Default Action: None, notification only. Note that XForms processors including this module will interpret this as a Fatal error which halts processing.

3.3 DOM Interface for Access to XML Instance Data

Each instance element defines a structure called instance data that conforms to the XPath Data Model [XPath 1.0]. Processors that implement DOM representations of instance storage must provide DOM access to this instance data via the interface defined below.

Note:

Instance data always has a single root element, and thus corresponds to a DOM Document.

The IDL for this interface follows:

#include "dom.idl"
			
			pragma prefix "w3c.org"
			
			module data-instance-data {
			  interface DataInstanceElement : dom::Element {
				dom::Document getInstanceDocument();
				void setInstanceDocument( dom::Document doc )
				void load();
			  };
			};

3.3.1 The getInstanceDocument() Method

The document element of the associated instance is returned.

3.3.2 The setInstanceDocument() Method

The document element of the associated instance is set to the "doc" argument content.

3.3.3 The load() Method

This method signals the processor to access any specified external resources and initialize the instance document, or to refresh instance data from inline markup. This method takes no parameters and raises no exceptions.

4 Binding Attributes Module

The binding attributes module provides a collection of attributes that can be used to associate an object such as an XML element with XML data nodes using XPath expressions.

4.1 Introduction

This document describes the Binding Attribute Module, which includes a collection of attribute groups, XPath functions, and behavioral semantics useful for binding objects, such as [XML 1.0] elements, to XML data nodes and evaluating other XPath expressions based on evaluations contexts set by those bindings.

This document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119].

4.2 Bindings

This section describes an extensible method of associating an object, such as an XML element, with an XML data node. A binding expression is an [XPath 1.0] expression that locates the XML data node to associate with an object. Section 4.3 Evaluation Context specifies how the evaluation context of the binding expression is determined. A binding attribute of an object is an attribute that contains a binding expression.

A binding object is an object, such as an XML element, that may contain a binding attribute. A bound object is a binding object that does contain a binding attribute.

This section defines attribute groups for two classes of bindings, the single node binding and the node set binding.

4.2.1 Single-Node Binding Attribute Group

This section defines the Single-Node Binding Attribute Group. This section defines one attribute for the single-node binding attribute group. Modules of the consuming profile may add other attributes or semantics to this attribute group.

ref: A binding expression interpreted as [XPath 1.0] and evaluated with an evaluation context defined in Section 4.3 Evaluation Context. The result is interpreted as an XPath nodeset, and the first node rule is applied to obtain at most one directly referenced XML data node.

The single-node binding associates the directly referenced XML data node with the bound object. The duration of the binding is specified in the definition of the bound object. For example, the binding may be ephemeral, lasting only as long as a behavioral operation, or the binding may persist as long as the bound object exists.

4.2.2 Node-Set Binding Attribute Group

This section defines the Node-Set Binding Attribute Group. This section defines one attribute for the node-set binding attribute group. Modules of the consuming profile may add other attributes or semantics to this attribute group.

nodeset: A binding expression interpreted as [XPath 1.0] and evaluated with an evaluation context defined in Section 4.3 Evaluation Context. The result is interpreted as an XPath nodeset that directly references zero or more XML data nodes.

The node-set binding associates the directly referenced XML data nodes with the bound object. The duration of the binding is specified in the definition of the bound object. For example, the bound object may simply use the directly referenced nodes in a behavioral operation, or the bound object may generate a multiplicity of related objects and implicitly bind each related object with one of the XML data nodes located by the node-set binding.

4.3 Evaluation Context

An object, such as an XML element, may have attributes containing XPath expressions that must be evaluated. According to [XPath 1.0], every XPath expression requires an evaluation context consisting of a node, position, size, variable bindings, function library, and namespace context. This section describes an extensible method for determining an in-scope evaluation context for an object, which may be used as the evaluation context for XPath expressions associated with the object.

The method of defining the in-scope evaluation context is based on the use of binding attributes. The following terms are used to describe the effects of bindings among objects that are related by a logical tree structure. An outermost object is an object that is not a logical descendant of an object that expresses a binding. A inner object is an object that is a logical descendant of an object that expresses a binding. A outer object is a bound object that is a logical ancestor of an inner object.

The first component of the in-scope evaluation context is the in-scope evaluation context node. The initial in-scope evaluation context node of an outermost object is defined by the consuming profile. The initial in-scope evaluation context node of an inner object is defined by the nearest ancestor outer object. If the outer object expresses a single-node binding that directly references an XML data node, then the directly referenced XML data node is the initial in-scope evaluation context node of the inner object. If the outer object expresses a node-set binding, and if the outer object associates each XML data node located by the node-set binding expression with a related object containing a copy of the content of the outer object, then the XML data node associated with the related object is the initial in-scope evaluation context node of the inner object.

To allow greater control over the in-scope evaluation context node, any object may override the initial in-scope evaluation context node using the context attribute, which is defined to be part of the Single-Node Binding Attribute Group and the Node-Set Binding Attribute Group.

context: An optional attribute containing an XPath expression evaluated using the initial in-scope evaluation context. The result of the expression is interpreted as a nodeset, the first node rule is applied, and the result overrides the in-scope evaluation context node of the object that bears this attribute.

If an object has no in-scope evaluation context node, then behaviors related to XPath expressions associated with the object are suppressed. An object may have no in-scope evaluation context node for many reasons, including the possibility that the consuming profile defines no default node for an outermost object, because the context attribute resolves to an empty nodeset, or because the object is an inner object and an outer object ancestor has no in-scope evaluation context node.

The in-scope evaluation context position and size are based on the nodeset used to obtain the in-scope evaluation context node. For the initial in-scope evaluation context, this is the nodeset that contains the initial in-scope evaluation context node. If the context attribute is specified and results in a node, then the position and size are both 1 because the first node rule is applied to the context. If the nearest ancestor outer object of an inner object expresses a node-set binding, then the initial in-scope evaluation context position of the inner object is based on the position in the nodeset of the XML data node associated with the related object ancestor of the inner object, and the initial in-scope evaluation context size of the inner object is based on the size of the nodeset obtained by the node-set binding of the outer object.

This module defines no XPath variables for the in-scope evaluation context. The consuming profile may add variables to the initial in-scope evaluation context. Any such variables are also added to the in-scope evaluation context.

The function library available to the initial in-scope evaluation context and the in-scope evaluation context is defined in 4.4 XPath Function Library.

Any namespace declarations in scope for the attribute bearing the XPath expression are applied to the in-scope evaluation context of the expression.

This section has described how the in-scope evaluation context of an object is determined, not whether the in-scope evaluation context will be used to evaluate an XPath expression associated with the object. The initial in-scope evaluation context is used to evaluate the context attribute of an object, if one is specified. The in-scope evaluation context is used to evaluate a binding expression of an object, if one is specified. By default, the in-scope evaluation context of an object is used to evaluate any other attributes of an object unless the attribute definition specifies otherwise. For example, it is possible to evaluate an attribute of an object using an evaluation context that is based on the object's binding expression.

4.4 XPath Function Library

The function library for XPath expressions includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans. This section provides an addtional function that is required to implement by this module. Other modules of the consuming profile may add more functions to the function library.

4.4.1 Node-set Functions

4.4.1.1 The context() Function

node-set context()

This function returns the in-scope evaluation context node of the nearest ancestor object of the attribute containing the XPath expression that invokes this function. The nearest ancestor object may be related to an object that expresses a node-set binding as described in Section 4.3 Evaluation Context.

Example:

<setvalue ref="x" value="context()/y"/>

In this example, the element setvalue has a binding attribute ref whose result is used as the evaluation context node node of the value attribute. The context() function returns the in-scope in-scope evaluation context node for the setvalue element.

4.5 References, Dependencies, and Dynamic Dependencies

An XPath expression references a node of XML data if the node is selected during the evaluation of the expression. A node is selected by matching an XPath NodeTest or by being returned by a function call. For examples, a node can match a name test, a wildcard test, a node type test, or it can be returned by or used as a parameter to a function, or it can appear in a filter expression (where all of the prior examples recursively apply). Once selected, a node is considered to be referenced even if a filter expression subsequently excludes the node from further participation in the expression evaluation. The reference list of an XPath expression is the set of XML nodes that it references.

Example of References and Non-References

Given the following XML data:

   <data xmlns="">
      <a attr="X">
         <b attr="Y">
            <c/>
         </b>
         <d/>
      </a>         
      <a attr="Z">
         <b>
            <c/>
         </b>
         <d/>
      </a>         
   </data>

and the following XPath expression:

a[@attr='X']/b[@attr='X']/c

Both nodes named a are referenced since both are matched by a NameTest. The attr attribute in each element a is referenced during the evaluation of the filter expression. The filter expression rejects the second element a, but that element is still considered to have been referenced because it was selected for further processing during the expression evaluation.

The element named b in the first element a is referenced, but element b in the second a is not referenced because the expression evaluation did not proceed beyond the filter expression that rejected the second a element.

While performing the NameTest for element b, observe that an XPath expression evaluator may visit all the children of the first element a in order to perform the NodeTest. However, a node is not referenced if it is only visited but fails the NodeTest. In this case, the NodeTest is a NameTest for b, which the element d fails. Therefore, d is not referenced.

The filter expression test on b rejects the only element b that has been selected so far because the attribute value of attr does not match the equality test. Still, b and its attribute attr have been referenced by this expression.

Element c is not considered to be referenced by this expression given this data. Although a NameTest for c appears in the expression, the evaluation of the expression did not proceed to perform the NameTest due to the rejection of b by the filter expression.

Finally, note that an XPath expression can reference many nodes even if its final result is an empty nodeset.

Note:

Defining a reference in terms of matching a NodeTest was a deliberate design decision that creates more references than necessary in order to make various XPath-based systems more responsive to certain types of changes. When a leaf node is filtered from an expression by a predicate, the leaf node is still considered to be referenced so that if the condition changes such that the leaf node would be included in the result value of the expression, then it can be easily detected that the expression needs re-evaluation without evaluating other XPath expressions.

However, once a node is rejected from an expression, further location steps are not evaluated relative to the rejected node, so references for that location step are only created based on its execution relative to accepted nodes.

Editorial note
Part of the above note about the effect of rejected nodes on computational dependencies must be added to the calculate module.

Editorial note
Comments about referencing a repeat index with the index() function must be added to the repeat module.

If an XPath expression references an XML data node, then the expression result is dependent on the node. A dependency list for an XML data node is the list of XPath expressions of a given category that are dependent upon the node.

Editorial note
A comment about the relationship between dependency lists and order of recalculation must be added to the calculate module.

The references of an XPath expression may be altered by insertion of XML data nodes since the new nodes may be referenced by the XPath expression if it is re-evaluated. Similarly, the references of an XPath expression may be altered by deletion of XML data nodes that are being referenced by the XPath expression. An XPath expression is dynamically dependent on an XML data node if its reference list is altered by inserting, deleting or changing the value of the node. An XML data node is a dynamic dependency for an XPath expression if the expression is dynamically dependent on the node. If an XPath expression contains a dynamic dependency and dependency lists are being maintained for XPath expressions, then changing the dynamic dependency implies a change to the dependency lists of XML data nodes referenced by the XPath expression.

Editorial note
Comments about the relationship between dynamic dependencies, recalculate and rebuild must be added to at least one of the calculate module and the bind module.

5 Data Accessors Module

The XForms Data Accessors Module defines the support for data instances in XForms applications by extending the "Data Instance" module with the following elements and attributes:

Element	Attributes	Events	Minimal Content Model
instance	Common, src (xsd:anyURI), resource (xsd:anyURI)	xforms-insert, xforms-delete	(ANY)
setvalue	Common, Events, Action Common, Single Node Binding, value (string XPath Expression)	xforms-binding-exception	PCDATA
insert	Common, Events, Action Common, Node Set Binding, context (node XPath Expresson), at (number XPath Expression), position ("before"\|"after"), origin (nodeset XPath Expresson)	xforms-binding-exception	EMPTY
delete	Common, Events, Action Common, Node Set Binding, context (node XPath Expresson), at (number XPath Expression)	xforms-binding-exception	EMPTY

5.1 The instance Element

The instance element is defined in the Data Instance module and is imported for use here in the XForms Instance Data Module. This specification adds the xforms-insert and xforms-delete events which target the instance element as described below.

5.2 The setvalue Element

The setvalue element is an Action as defined in the XForms Actions module and is added by the definition that follows to the set of Actions supported by that module.

This action explicitly sets the value of the specified instance data node. This action has no effect if the Single Node Binding does not select an instance data node or if a readonly instance data node is selected. An xforms-binding-exception occurs if the Single Node Binding indicates a node whose content is not simpleContent (i.e., a node that has element children).

5.2.1 Setvalue attributes

Common Attributes: Common, Events, Action Common, Single Node Binding

Special Attributes:

value: Optional XPath expression to evaluate, with the result stored in the selected instance data node. The evaluation context for this XPath expression is the result from the Single Node Binding. To obtain the value, the result of the expression is processed as if by call to the XPath string function. An empty string is used if the XPath evaluation fails.

5.2.2 Setvalue processing

The element content of setvalue specifies the literal value to set; this is an alternative to specifying a computed value via attribute value. If neither a value attribute nor text content are present, the effect is to set the value of the selected node to the empty string (""). If both are present, the value attribute is used. The following examples contrast these approaches:

setvalue with Expression

<setvalue bind="put-here" value="a/b/c"/>

This causes the string value at a/b/c in the instance data to be placed on the single node selected by the bind element with id="put-here".

setvalue with Literal

<setvalue bind="put-here">literal string</setvalue>

This causes the value "literal string" to be placed on the single node selected by the bind element with id="put-here".

Note:

See Section 4.4.1.1 The context() Function for an example in which the context() function is used to provide the same initial evaluation context node to both the ref and value attributes.

All strings are inserted into the instance data as follows:

Element nodes: If element child nodes are present, then an xforms-binding-exception occurs. Otherwise, regardless of how many child nodes the element has, the result is that the string becomes the new content of the element. In accord with the data model of [XPath 1.0], the element will have either a single non-empty text node child, or no children string was empty.
Attribute nodes: The string-value of the attribute is replaced with a string corresponding to the new value.
Text nodes: The text node is replaced with a new one corresponding to the new value, or the text node is eliminated if the new value is the empty string.
Namespace, processing instruction, and comment nodes: behavior is undefined (implementation-dependent).
the XPath root node: an xforms-binding-exception occurs.

Note:

This action affects deferred updates by setting the deferred update flags for recalculate, revalidate and refresh.

5.3 The `insert` Element

The insert element is an Action as defined in the XForms Actions module and is added by the definition that follows to the set of Actions supported by that module.

The insert action is used to create one or more nodes of instance data by cloning one or more existing instance nodes. Attributes of the insert action specify the node or nodes to be cloned and the location within instance data where the clones will appear. The clones are deep copies of the original nodes except the contents of nodes of type xsd:ID are modified to remain as unique values in the instance data after the clones are inserted.

5.3.1 Insert attributes

Common Attributes: Common, Events, Action Common, Node Set Binding (optional)

Special Attributes:

context: Optional attribute containing an XPath expression evaluated using the in-scope evaluation context. If the model attribute is present, then it is processed as described in ??? before evaluating this attribute. The Node Set Binding is required unless this attribute is present. The result of the XPath expression is used to override the in-scope evaluation context. If the result is an empty nodeset or not a nodeset, then the insert action is terminated with no effect. Otherwise, the first node of the nodeset is used as the new in-scope evaluation context node, and the context position and size are set to 1. By adjusting the in-scope evaluation context, this attribute affects the evaluation of subsequent attributes that may appear on insert, including if, while, nodeset and origin.
origin: Optional attribute containing an XPath expression evaluated using the in-scope evaluation context , which may have been amended by the context attribute. The origin node-set is the set of one or more nodes to be cloned by the insert action. If this attribute is present and resolves to a non-empty nodeset, then the result overrides the default setting of the origin node-set as described below in the processing of the insert action.
at: Optional attribute containing an XPath expression evaluated using the in-scope evaluation context. This attribute is ignored if the Node Set Binding is not specified or specifies an empty node-set. The insert location node is a node within the Node Set Binding node-set that is used to help determine where in the instance to insert each node cloned by the insert. If this attribute is present, then its result is used to override the default setting of the insert location node as described below in the processing of the insert action.
position: Optional selector that indicates where to put the cloned node or nodes relative to the insert location node. Valid values are before and after, and the latter is the default. This attribute is ignored if the Node Set Binding node-set is not specified or empty. If the node at the insert location node within the Node Set Binding node-set is the document element of an instance, then this attribute is ignored.

5.3.2 The xforms-insert Event

Dispatched in response to: Successful insertion of one or more nodes by an XForms insert action.

Target: instance

Bubbles: Yes

Cancelable: No

Context Info:

Property	Type	Value
inserted-nodes	node-set	The instance data node or nodes inserted.
origin-nodes	node-set	The instance data nodes referenced by the `insert` action's `origin` attribute if present, or the empty nodeset if not present.
insert-location-node	node-set	The `insert location node` as defined by the `insert` action.
position	string	The insert position, `before` or `after`.

Default Action: None; notification event only.

5.3.3 Insert action processing

Processing for the insert action is as follows:

The insert context is determined. If the context attribute is not given, the insert context is the in-scope evaluation context. Otherwise, the XPath expression provided by the context attribute is evaluated using the in-scope evaluation context, and the first node rule is applied to obtain the insert context. The insert action is terminated with no effect if the insert context is the empty node-set.
The Node Set Binding node-set is determined. If a bind attribute is present, it directly determines the Node Set Binding node-set. If a nodeset attribute is present, it is evaluated within the insert context to determine the Node Set Binding node-set. If the Node Set Binding attributes are not present, then the Node Set Binding node-set is the empty node-set. The insert action is terminated with no effect if any of the following conditions is true:
1. The context attribute is not given and the Node Set Binding node-set is the empty node-set.
2. The context attribute is given, the insert context does not evaluate to an element node and the Node Set Binding node-set is the empty node-set.
The origin node-set is determined. If the origin attribute is not given and the Node Set Binding node-set is empty, then the origin node-set is the empty node-set. Otherwise, if the origin attribute is not given, then the origin node-set consists of the last node of the Node Set Binding node-set. If the origin attribute is given, the origin node-set is the result of the evaluation of the origin attribute in the insert context. The insert action is terminated with no effect if the origin node-set is the empty node-set.
The insert location node is determined. If the Node Set Binding node-set is not specified or empty, the insert location node is the insert context node. Otherwise, if the at attribute is not given, then the insert location node is the last node of the Node Set Binding node-set. Otherwise, an insert location node is determined from the at attribute as follows:
1. The evaluation context node is the first node in document order from the Node Set Binding node-set, the context size is the size of the Node Set Binding node-set, and the context position is 1.
2. The return value is processed according to the rules of the XPath function round(). For example, the literal 1.5 becomes 2, and the literal 'string' becomes NaN.
3. If the result is in the range 1 to the Node Set Binding node-set size, then the insert location is equal to the result. If the result is non-positive, then the insert location is 1. Otherwise, the result is NaN or exceeds the Node Set Binding node-set size, so the insert location is the Node Set Binding node-set size.
4. The insert location node is the node in the Node Set Binding node-set at the position given by the insert location.
The insert action is terminated with no effect if the insertion will create nodes whose parent is readonly. This occurs if the insert location node is readonly and the Node Set Binding node-set is not specified or empty, or otherwise if the parent of the insert location node is readonly.
Each node in the origin node-set is cloned in the order it appears in the origin node-set.
The target location of each of the cloned nodes is determined as follows:
1. If the Node Set Binding node-set is not specified or empty, then the insert location node provided by the context attribute is intended to be the parent of the cloned node. The target location is dependent on the types of the cloned node and the insert location node as follows:
  - If the insert location node is not an element node or root node, then it cannot be the parent of the cloned node, so the target location is undefined.
  - If the insert location node is the root node of an instance (which is the parent of the root element), and the cloned node is an element, then the target location is the root element of the instance.
  - If the insert location node is the root node of an instance (which is the parent of the root element), and the cloned node is not an element, then the target location is before the first child of the insert location node.
  - If the insert location node is an element, and the cloned node is an attribute, then the target location is the attribute list of the insert location node.
  - If the insert location node is an element, and the cloned node is not an attribute, then the target location is before the first child of the insert location node, or the child list of the insert location node if it is empty.
2. Otherwise, the Node Set Binding node-set is specified and non-empty, so the insert location node provided by the Node Set Binding and optional at attribute is intended to be the sibling of the cloned node. If the insert location node is an attribute or root node, then the target location is undefined. If the insert location node is not an attribute or root node, then the target location is immediately before or after the insert location node, based on the position attribute setting or its default.
The cloned node or nodes are inserted in the order they were cloned into their target locations depending on their node type. If the target location was the root element of an instance, then the cloned node replaces the instance root element. If the cloned node is a duplicate of another attribute in its parent element, then the duplicate attribute is first removed. If a cloned node cannot be placed at the target location due to a node type conflict or because the target location is undefined, then the insertion for that particular cloned node is ignored.
Note:
A node type conflict is a mismatch between the XPath node type and the target location. For example, an attribute cannot be inserted as a sibling before or after an element.
Editorial note: Need to move to Model module
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
The insert action is successfully completed by dispatching the xforms-insert event with appropriate context information.
Note:
If used with the XForms UI module, a repeat updates its index in response to this event if its repeat collection changes size as a result of the insertion. See Section ??? for details.

Note:

If used with the XForms Model module, this action affects deferred updates by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.

5.3.4 Insert action examples

Using insert to update a data instance in a standalone XForms Data Instance (insert used without an XForms UI)

When the xxx event is fired on yyy, the insert action executes, adding zzz to the referenced node in the data instance

code to go here...

Inserting into an XForms repeat, whether or not it is empty

When the repeat is empty, the at index is zero so a new item is prepended to the child elements of purchaseOrder. When the repeat is non-empty, the new item is added after the node currently indexed by repeat R.

...
<xforms:instance>
   <purchaseOrder xmlns="">
        <subtotal/>
        <tax/>
        <total/>
   </purchaseOrder>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
       ...
       <item>
           <product/>
           <quantity/>
           <unitcost/>
           <price/>
       </item>
       ...
    </prototypes>
</xforms:instance>
...
<repeat nodeset="/purchaseOrder/item" id="R">
   ...
</repeat>
...
<xforms:trigger>
  <xforms:label>Add to purchase order</xforms:label>
  <xforms:action ev:event="DOMActivate>
    <xforms:insert context="/purchaseOrder" nodeset="item" at="index('R')" origin="instance('prototypes')/item"/>
    <xforms:setfocus control="R"/>
  </xforms:action>
</xforms:trigger>

Insert and Read-Only Content

Editorial note: Rework example to not require XForms model or binds...
We should have this example stand alone for this module, or else duplicate it and show versions both with and without the XForms model and binds...

<model xmlns:my="http://example.org">
  <instance>
    <my:data>
      <my:name>
        <my:first-name>John</my:first-name>
        <my:last-name>Doe</my:last-name>
      </my:name>
      <my:address>
        <my:street>123 Main St.</my:street>
        <my:city>Smallville</my:city>
      </my:address>
    </my:data>
  </instance>

  <bind nodeset="/my:data/my:name/" readonly="true()"/>
  <bind nodeset="/my:data/my:address/my:street" readonly="true()"/>

  <action ev:event="xforms-model-construct-done">
      <insert id="I1" nodeset="my:name/*" ... />
      <insert id="I2" nodeset="my:address/my:street" at="1" >
  </action>
</model>

Insert I1 fails because it attempts to insert into the content of a readonly node (my:name). Insert I2 succeeds even though the insert location is a readonly node because the new node is placed as a sibling into the content of the parent, which is not readonly.

Editorial note: Need to move to UI module
See 5.4 The delete Element for an example that uses `insert` and `delete` to make a `repeat` that always shows at least one repeat item. See Appendix B Insert and Delete Action Patterns for Data Mutations for numerous further usage patterns for `insert` and `delete`.

5.4 The `delete` Element

The delete element is an Action as defined in the XForms Actions module and is added by the definition that follows to the set of Actions supported by that module.

This action deletes one or more nodes from instance data.

5.4.1 Delete action attributes

Common Attributes: Common, Events, Action Common, Node Set Binding

Special Attributes:

context: Optional attribute containing an XPath expression evaluated using the in-scope evaluation context. If the model attribute is present, then it is processed as described in ??? before evaluating this attribute. The Node Set Binding is required unless this attribute is present. The result of the XPath expression is used to override the in-scope evaluation context. If the result is an empty nodeset or not a nodeset, then the delete action is terminated with no effect. Otherwise, the first node of the nodeset is used as the new in-scope evaluation context node, and the context position and size are set to 1. By adjusting the in-scope evaluation context, this attribute affects the evaluation of subsequent attributes that may appear on delete, including if, while, and nodeset.
at: Optional attribute containing an XPath expression evaluated using the Node Set Binding node-set to determine the delete location. If the Node Set Binding node-set is empty, then this attribute is ignored.

5.4.2 The xforms-delete Event

Dispatched in response to: Successful deletion of one or more nodes by an XForms delete action.

Target: instance

Bubbles: Yes

Cancelable: No

Context Info:

Property	Type	Value
deleted-nodes	node-set	The instance data node or nodes deleted. Note that these nodes are no longer referenced by their parents.
delete-location	number	The `delete location` as defined by the `delete` action, or NaN if there is no delete location.

Default Action: None; notification event only.

5.4.3 Delete action processing

Processing for the delete action is as follows:

The delete context is determined. It is set to the in-scope evaluation context, possibly overridden by the context attribute if that attribute is present. The delete action is terminated with no effect if the delete context is the empty node-set.
The Node Set Binding node-set is determined. If a bind attribute is present, it directly determines the Node Set Binding node-set. If a nodeset attribute is present, it is evaluated within the delete context to determine the Node Set Binding node-set. The delete action is terminated with no effect if the Node Set Binding is expressed and the Node Set Binding node-set is the empty node-set. Otherwise, the Node Set Binding is not expressed, so the Node Set Binding node-set is set equal to the delete context node with a position and size of 1.
The delete location is determined. If the at attribute is not specified, there is no delete location. Otherwise, the delete location is determined by evaluating the XPath expression specified by the at attribute as follows:
1. The evaluation context node is the first node in document order from the Node Set Binding node-set, the context size is the size of the Node Set Binding node-set, and the context position is 1.
2. The return value is processed according to the rules of the XPath function round(). For example, the literal 1.5 becomes 2, and the literal 'string' becomes NaN.
3. If the result is in the range 1 to the Node Set Binding node-set size, then the delete location is equal to the result. If the result is non-positive, then the delete location is 1. Otherwise, if the result is NaN or exceeds the Node Set Binding node-set size, the delete location is the Node Set Binding node-set size.
If there is no delete location, each node in the Node Set Binding node-set is deleted, except if the node is a readonly node or the root document element of an instance then that particular node is not deleted. Otherwise, if there is a delete location, the node at the delete location in the Node Set Binding node-set is deleted, except if the node is the root document element of an instance or has a readonly parent node, then that node is not deleted. The delete action is terminated with no effect if no node is deleted.
Editorial note: Need to move to Model module
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
The delete action is successfully completed by dispatching the xforms-delete event with appropriate context information.

Note:

If used with the XForms Model module, this action affects deferred updates by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.

5.4.4 Delete action examples

Editorial note: Need to rework to not require Model or UI modules
These examples should be reworked, or extended, to not require the Model or UI modules.

Using delete and insert to Maintain a Non-empty repeat repeat

In this example, the trigger is not in the repeat. When it is activated, the indexed item in the repeat is first deleted. Next, if that was the last item, then a new prototypical item is inserted so that the repeat does not become empty. The focus is then sent back to the repeat from the trigger.

...
<xforms:trigger>
  <xforms:label>Delete from purchase order</xforms:label>
  <xforms:action ev:event="DOMActivate">
    <xforms:delete context="/purchaseOrder" nodeset="item" at="index('R')"/>
    <xforms:insert context="/purchaseOrder" if="not(item)"
                   nodeset="item" origin="instance('prototypes')/item"/>
    <xforms:setfocus control="R"/>
  </xforms:action>
</xforms:trigger>

Note:

The form author could have written nodeset="/purchaseOrder/item" in the delete action, but the context attribute was added for consistency with the insert action.

Delete and Read-Only Content

<model xmlns:my="http://example.org">
  <instance>
    <my:data>
      <my:name>
        <my:first-name>John</my:first-name>
        <my:last-name>Doe</my:last-name>
      </my:name>
      <my:address>
        <my:street>123 Main St.</my:street>
        <my:city>Smallville</my:city>
      </my:address>
    </my:data>
  </instance>

  <bind nodeset="/my:data/my:name/" readonly="true()"/>
  <bind nodeset="/my:data/my:address/my:street" readonly="true()"/>

  <action ev:event="xforms-model-construct-done">
      <delete id="D1" nodeset="my:name/*" ... />
      <delete id="D2" nodeset="my:address/my:street" at="1" >
      <delete id="D3" nodeset="my:address" at="1" >
  </action>
</model>

Delete D1 fails because it attempts to delete from the content of a readonly node (my:name). Delete D2 succeeds even though the node to delete is readonly because the node is not being changed, but rather removed from the content of the parent, which is not readonly. Delete D3 succeeds even though it contains a readonly node because a node can be deleted if its parent is not readonly, and node deletion includes deletion of its attributes and content, regardless of whether or not the attributes or content nodes are readonly.

See Appendix B Insert and Delete Action Patterns for Data Mutations for numerous further usage patterns for insert and delete.

5.5 DOM Interface for Access to XForms Instance Data

As described in the Data Instance Module, each instance element defines a structure called instance data that conforms to the XPath Data Model [XPath 1.0]. XForms Instance Data processors that implement DOM representations of instance storage must provide DOM access to this instance data via the additional methods and defined in the interface below.

Note:

Instance data always has a single root element, and thus corresponds to a DOM Document.

The IDL for this interface follows:

Editorial note: Check IDL syntax

#include "dom.idl"
			
			pragma prefix "w3c.org"
			
			module xforms-data-instance-data {
			  interface XFormsDataInstanceElement : DataInstanceElement {
				boolean setvalue(contextNode, contextExpr, stringValue);
				boolean insert(contextNode, contextExpr, nodesetExpr, atExpr, positionExpr, originExpr);
				boolean delete(contextNode, contextExpr, nodesetExpr, atExpr);
			  };
			};

5.5.1 The setvalue() Method

text...

5.5.2 The insert() Method

text...

5.5.3 The delete() Method

text...

6 Processing Model

This sections defines the processing model, or behavior, associated with the XForms Data Layer.

7 XPath Functions Module

This XPath functions module provides a base collection of XPath 1.0 functions that are useful across many modules of XForms.

7.1 Introduction

This document describes an XPath Functions Module, which includes a set of useful, general-purpose XPath 1.0 functions.

This document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119].

7.2 XPath Function Library

The function library for XPath expressions includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans. The following sections define additional functions that are required to implement by this module. Other modules of the consuming profile may add more functions to the function library. Also, a number of useful community extensions are defined at [EXSLT]

7.2.1 Data Integrity Functions

7.2.1.1 The is-card-number() Function

boolean is-card-number(string?)

If the string parameter conforms to the pattern restriction of zero or more numeric digits, then this function applies the algorithm described in [Luhn Patent] and returns true if the string is empty or if the number in the string satisfies the Luhn formula. Otherwise, false is returned. If the parameter is omitted, it defaults to the string-value of the current context node.

Examples:

is-card-number(.)

returns true if and only if the context node contains a string that contains zero or more digits and satisfies the formula.

is-card-number('4111111111111111')

returns true. Other examples of string constants that will return true are : 5431111111111111, 341111111111111 and 6011601160116611.

is-card-number('123')

returns false.

7.2.1.2 The digest() Function

string digest(string, string, string?)

This function accepts a string of data, a string indicating a cryptographic hashing algorithm, and an optional string indicating an encoding method. The data string is serialized as UTF-8, the hash value is then computed using the indicated hash algorithm, and the hash value is then encoded by the indicated method, and the result is returned by the function. The following table presents the keywords for the second string parameter and the corresponding hash algorithms:

Keywords	Hash Algorithm	Status
`MD5`	The MD5 hash algorithm defined in [MD5]	Required
`SHA-1`	The SHA-1 hash algorithm defined in [SHA2]	Required
`SHA-256`	The SHA-256 hash algorithm defined in [SHA2]	Required
`SHA-384`	The SHA-384 hash algorithm defined in [SHA2]	Optional
`SHA-512`	The SHA-512 hash algorithm defined in [SHA2]	Optional
Any other NCName	Reserved. Their use results in an exception (see 4.4 XPath Function Library for the exception type)	Required
QNameButNotNCName	An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see 4.4 XPath Function Library for the exception type).	Required

This recommendation defines the values hex and base64 for the third string parameter that indicates the encoding method. If the parameter is missing, then the default is base64. The hex and base64 encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary and base64Binary, respectively. Any other string value given for the encoding method is unsupported.

digest('abc', 'SHA-1', 'hex')

returns a9993e364706816aba3e25717850c26c9cd0d89d.

digest('abc', 'MD5', 'hex')

returns 900150983cd24fb0d6963f7d28e17f72.

digest('abc', 'SHA-256', 'hex')

returns ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad

7.2.1.3 The hmac() Function

string hmac(string, string, string, string?)

This function accepts a string for a key or shared secret, a string of data, a string indicating a cryptographic hashing algorithm, and an optional string indicating an encoding method. The key and data strings are serialized as UTF-8, and they are subjected to the HMAC algorithm defined in [HMAC] and parameterized by the the hash algorithm indicated by the third parameter. The result is encoded with the method indicated by the fourth parameter, and the result is returned by the function.

The following table presents the keywords for the third string parameter and the corresponding hash algorithms:

Keywords	Hash Algorithm	Status
`MD5`	The MD5 hash algorithm defined in [MD5]	Required
`SHA-1`	The SHA-1 hash algorithm defined in [SHA2]	Required
`SHA-256`	The SHA-256 hash algorithm defined in [SHA2]	Required
`SHA-384`	The SHA-384 hash algorithm defined in [SHA2]	Optional
`SHA-512`	The SHA-512 hash algorithm defined in [SHA2]	Optional
Any other NCName	Reserved. Their use results in an exception (see 4.4 XPath Function Library for the exception type)	Required
QNameButNotNCName	An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see 4.4 XPath Function Library for the exception type).	Required

This recommendation defines the values hex and base64 for the fourth string parameter that indicates the encoding method. If the parameter is missing, then the default is base64. The hex and base64 encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary and base64Binary, respectively. Any other string value given for the encoding method is unsupported.

hmac('Jefe', 'what do ya want for nothing?', 'SHA-1', 'hex')

returns effcdf6ae5eb2fa2d27416d5f184df9c259a7c79

hmac('Jefe', 'what do ya want for nothing?', 'MD5', 'hex')

returns 750c783e6ab0b503eaa86e310a5db738

hmac('Jefe', 'what do ya want for nothing?', 'SHA-256', 'hex')

returns 5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843

7.2.2 Date and Time Functions

Note:

The following XML Schema datatypes do not have specific functions for manipulation within expressions: xsd:time, xsd:gYearMonth, xsd:gYear, xsd:gMonthDay, xsd:gDay, xsd:gMonth. Extension functions may be added to perform needed operations on these datatypes.

7.2.2.1 The local-date() Function

string local-date()

This function returns a lexical xsd:date obtained as if by the following rules: the result of now() is converted to a local date based on the user agent time zone information. If no time zone information is available, then the date portion of the result of now() is returned.

Example:

local-date()

could return 2006-10-13-07:00

substring(local-date(), 1, 10)

could return 2006-10-13

days-to-date(days-from-date(local-date()) + 31)

returns a date that is 31 days from today. For example, if local-date() returns 2006-10-13-07:00, then the result is 2006-11-13.

7.2.2.2 The local-dateTime() Function

string local-dateTime()

This function returns a lexical xsd:dateTime obtained as if by the following rules: the result of now() is converted to a local dateTime based on the user agent time zone information. If no time zone information is available, then the result of now() is returned.

Example:

local-dateTime()

could return 2006-10-13T16:04:17-07:00

adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(local-dateTime()) + 7200))

Adds two hours (7200 seconds) to the local date and time, returning the result in the local time zone. For example, if local-dateTime() returns 2007-10-02T14:26:43-07:00, then the above expression returns 2007-10-02T16:26:43-07:00

7.2.2.3 The now() Function

string now()

The now function returns the current UTC date and time as a string value in the canonical XML Schema xsd:dateTime format. If time zone information is available, it is used to convert the date and time to UTC. If no time zone information is available, then the date and time are assumed to be in UTC.

now()

returns 2006-10-14T01:04:17Z if local-dateTime() returns 2006-10-13T18:04:17-07:00

seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)

Computes two hours from now, returning the result in UTC time. For example, if now() returns 2007-10-02T21:26:43Z, then the above expression returns 2007-10-02T23:26:43Z

7.2.2.4 The days-from-date() Function

number days-from-date(string)

This function returns a whole number of days, according to the following rules:

If the string parameter represents a legal lexical xsd:date or xsd:dateTime, the return value is equal to the number of days difference between the specified date or dateTime (normalized to UTC) and 1970-01-01. Hour, minute, and second components are ignored after normalization. Any other input parameter causes a return value of NaN.

Note:

If an xsd:date is given as the parameter, the timezone is ignored if provided because there is no way to normalize to the date in the UTC timezone without both the time and timezone.

Examples:

days-from-date("2002-01-01")

returns 11688

days-from-date("2002-01-01-07:00")

returns 11688

days-from-date("1969-12-31")

returns -1

7.2.2.5 The days-to-date() Function

string days-to-date(number)

This function returns a string containing a lexical xsd:date that corresponds to the number of days passed as the parameter according to the following rules:

The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired date and 1970-01-01. An input parameter value of NaN results in output of the empty string.

Examples:

days-to-date(11688)

returns 2002-01-01

days-to-date(-1)

returns 1969-12-31

7.2.2.6 The seconds-from-dateTime() Function

number seconds-from-dateTime(string)

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical xsd:dateTime, the return value is equal to the number of seconds difference between the specified dateTime (normalized to UTC) and 1970-01-01T00:00:00Z. If no time zone is specified, UTC is used. Any other input string parameter causes a return value of NaN. This function does not support leap seconds.

Example:

seconds-from-dateTime('1970-01-01T00:00:00Z')

returns 0

seconds-from-dateTime('1970-01-01T00:00:00-08:00')

returns 28800 because it is eight hours later than 1970-01-01T00:00:00Z

seconds-from-dateTime('1970-01-02T00:00:00Z')

returns 86400

seconds-from-dateTime('1969-12-31T00:00:00Z')

returns -86400, which is negative because it is one day before 1970-01-01T00:00:00Z

7.2.2.7 The seconds-to-dateTime() Function

string seconds-to-dateTime(number)

This function returns a string containing a lexical xsd:dateTime that corresponds to the number of seconds passed as the parameter according to the following rules:

The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired UTC dateTime and 1970-01-01T00:00:00Z. An input parameter value of NaN results in output of the empty string. This function does not support leap seconds.

Examples:

seconds-to-dateTime(0)

returns 1970-01-01T00:00:00Z

seconds-from-dateTime(28800)

returns 1970-01-01T08:00:00Z

seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)

Computes two hours from now, returning the result in UTC time. For example, if now() returns 2007-10-02T21:26:43Z, then the above expression returns 2007-10-02T23:26:43Z

adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))

Computes two hours from now, returning the result in the local time zone. For example, if now() returns 2007-10-02T21:26:43Z and the local date and time is 2007-10-02T14:26:43-07:00, then the above expression returns 2007-10-02T16:26:43-07:00

7.2.2.8 The adjust-dateTime-to-timezone() Function

string adjust-dateTime-to-timezone(string)

This function adjusts a legal lexical xsd:dateTime received as the string parameter to the local time zone of the implementation, and returns the result. If the string argument contains no time zone, then the result is the string argument with the local time zone as the time zone component. If the implementation does not have access to time zone information, UTC is used. The result is empty string if the string argument is the empty sequence or not a legal lexical xsd:dateTime.

Examples:

adjust-dateTime-to-timezone('2007-10-07T02:22:00')

returns 2007-10-07T02:22:00-07:00 in the Pacific time zone since daylight savings time applies.

adjust-dateTime-to-timezone('2007-10-02T21:26:43Z')

returns 2007-10-02T14:26:43-07:00 in the Pacific time zone since daylight savings time applies.

adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))

7.2.2.9 The seconds() Function

number seconds(string)

This function returns a possibly fractional number of seconds, according to the following rules:

If the string parameter represents a legal lexical xsd:duration, the return value is equal to the number specified in the seconds component plus 60 * the number specified in the minutes component, plus 60 * 60 * the number specified in the hours component, plus 60 * 60 * 24 * the number specified in the days component. The sign of the result will match the sign of the duration. Year and month components, if present, are ignored. Any other input parameter causes a return value of NaN.

Editorial note
What is the meaning of this note? Even though this function is defined based on a lexical `xsd:duration`, it is intended for use only with derived-from-`xsd:duration` datatypes, specifically `xforms:dayTimeDuration`.

Examples:

seconds("P3DT10H30M1.5S")

returns 297001.5 (3 days, 10 hours, 30 minutes, and 1.5 seconds)

seconds("P1Y2M")

returns 0 because the year and month parts of the duration are ignored and the remaining portions are unspecified and default to 0

seconds("3")

returns NaN because the parameter is not a lexically valid duration

7.2.2.10 The months() Function

number months(string)

This function returns a whole number of months, according to the following rules:

If the string parameter represents a legal lexical xsd:duration, the return value is equal to the number specified in the months component plus 12 * the number specified in the years component. The sign of the result will match the sign of the duration. Day, hour, minute, and second components, if present, are ignored. Any other input parameter causes a return value of NaN.

Editorial note
What is the meaning of this note? Even though this function is defined based on a lexical `xsd:duration`, it is intended for use only with derived-from-`xsd:duration` datatypes, specifically `xforms:yearMonthDuration`.

Examples:

months("P1Y2M")

returns 14 (1 year and 2 months)

months("-P19M")

returns -19 because the duration is negative and expresses 0 years and 19 months

7.2.3 Conditional Functions

7.2.3.1 The if() Function

string if(boolean, string, string)

Function if evaluates the first parameter as boolean, returning the second parameter when true, otherwise the third parameter.

Note:

This function is deprecated due to a conflict with [XPath 2.0], which contains an if construct that is incompatible with this function. Authors and design tools are encouraged to use the function choose() from Section 7.2.3.2 The choose() Function instead of this function.

7.2.3.2 The choose() Function

object choose(boolean, object, object)

This function provides a conditional test that chooses an object to return based on the boolean parameter. If the boolean parameter is true, then the first object is returned, otherwise the second object is returned. Each of the object parameters can be of any XPath datatype as described in [XPath 1.0], and this function does no type conversion of the parameter it chooses to return.

Note:

All parameters of an XPath function are evaluated, so the parameter that is not returned by this function is still evaluated, and its result is discarded by this function.

Note:

Form authors and design tools are encouraged to use this function instead of the function if() described in Section 7.2.3.1 The if() Function, which has been deprecated. Because this function returns an object instead of a string, migrating from if() to choose() may occasionally require conversion of the return result using the string() function.

Example:

choose(count(x) > 0, x, y)

Returns the node-set of matching x if it is non-empty and the node-set matching y otherwise.

choose(@x, @x, 0)

If the context node of the function contains attribute x, then the nodeset containing that attribute is returned. Otherwise, the number 0 is returned.

7.2.3.3 The compare() Function

number compare(string, string)

This function returns -1, 0, or 1, depending on whether the value of the first argument is respectively less than, equal to, or greater than the value of second argument based on lexicographic comparison using Unicode code point values [Unicode Collation Algorithm].

Example:

compare('apples', 'oranges')

returns -1

7.2.3.4 The count-non-empty() Function

number count-non-empty(node-set)

Function count-non-empty returns the number of non-empty nodes in argument node-set. A node is considered non-empty if it is convertible into a string with a greater-than zero length.

Example:

choose(count-non-empty(x) > 0, x, y)

Returns the node-set of matching x if it is has any non-empty nodes. Otherwise, the node-set matching y is returned.

7.2.3.5 The boolean-from-string() Function

boolean boolean-from-string(string)

Function boolean-from-string returns true if the required parameter string is "true" or "1", or false if parameter string is "false", or "0". This is useful when referencing a Schema xsd:boolean datatype in an XPath expression. If the parameter string matches none of the above strings, according to a case-insensitive comparison, the return value is false.

Example:

choose(boolean-from-string(isMinor), parentApplicant, primaryApplicant)

Returns the node-set matching parentApplicant if the content of node isMinor matches a truth value. Otherwise, the node-set matching primaryApplicant is returned. Note that a simple boolean cast of isMinor is a test for node existence, not a test on the node content, so if isMinor exists but contains false, then this function returns false whereas a boolean cast returns true.

7.2.3.6 The current() Function

node-set current()

Returns the context node used to initialize the evaluation of the containing XPath expression.

Example:

For the following XML data:

<data xmlns="">
	<converter>
		<amount>100</amount>
		<currency>jpy</currency>
	</converter>

	<convTable date="20040212" currency="cdn">
		<rate currency="eur">0.59376</rate>
		<rate currency="mxn">8.37597</rate>
		<rate currency="jpy">80.23451</rate>
		<rate currency="usd">0.76138</rate>
	</convTable>
</data>

If the evaluation context node of the following XPath expression is data, then the result of the expression is the converted currency amount:

converter/amount * convTable/rate[@currency = current()/converter/currency]

Editorial note
An example of the current() function must be moved to the calculate module.

Editorial note
An example of the current() function must be moved to repeat module.

7.2.4 Math Functions

7.2.4.1 The avg() Function

number avg(node-set)

Function avg returns the arithmetic average of the result of converting the string-values of each node in the argument node-set to a number. The sum is computed with sum(), and divided with div by the value computed with count(). If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.

7.2.4.2 The min() Function

number min(node-set)

Function min returns the minimum value of the result of converting the string-values of each node in argument node-set to a number. "Minimum" is determined with the < operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.

7.2.4.3 The max() Function

number max(node-set)

Function max returns the maximum value of the result of converting the string-values of each node in argument node-set to a number. "Maximum" is determined with the < operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN, the return value is NaN.

7.2.4.4 The power() Function

number power(number, number)

Raises the first argument to the power of the second argument, returning the result. If the calculation does not result in a real number, then NaN is returned.

Examples:

power(2, 3)

returns 8

power(-1, 0.5)

returns NaN.

if (prin>0 and dur>0 and rate>0, prin*rate/(1-power(1+rate, -dur)), 0)

returns a compounded interest payment value given a non-zero principal (prin), duration (dur) and periodic interest rate (rate).

7.2.4.5 The random() Function

number random(boolean?)

This function generates and returns a uniformly distributed random or pseudorandom number in the range from 0.0 up to but excluding 1.0. This function accepts an optional boolean parameter that is false by default. If true, the random number generator for this function is first seeded with a source of randomness before generating the return value. A typical implementation may seed the random number generator with the current system time in milliseconds when random(true) is invoked, and it may apply a linear congruential formula to generate return values on successive invocations of the function.

Example:

random()

could return 0.14159265358979

8 Glossary Of Terms

Binding: [Definition: A "binding" connects an instance data node to a form control or to a model item property by using a binding expression as a locator.]
Binding expression: [Definition: An [XPath 1.0] expression used in a binding.]
Compound Document: A [CDRF 1.0] Compound Document is a document that combines multiple document formats either by reference, by inclusion or both.
Computed expression: [Definition: An [XPath 1.0] expression used by model item properties such as relevant and calculate to include dynamic functionality in XForms.]
Containing document: [Definition: A specific document, for example an XHTML document, in which one or more <model> elements are found.]
Datatype: [Definition: From XML Schema [XML Schema part 2]: A 3-tuple, consisting of a) a set of distinct values, called its value space, b) a set of lexical representations, called its lexical space, and c) a set of facets that characterize properties of the value space, individual values or lexical items.]
Facet: [Definition: From XML Schema [XML Schema part 2]: A single defining aspect of a value space. Generally speaking, each facet characterizes a value space along independent axes or dimensions.]
First node rule: [Definition: When a UI Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set is used.]
Form control: [Definition: An XForms user interface control that serves as a point of user interaction (a core form control) or as a container for other form controls (a container form control).]
Host language: [Definition: An XML vocabulary, such as XHTML, into which XForms is embedded.]
Instance data: [Definition: An internal tree representation of the values and state of all the instance data nodes associated with a particular form.]
Instance data node: [Definition: An [XPath 1.0] node from the instance data.]
Lax schema processing: [Definition: From XML Schema [XML Schema part 1]: For an element or attributes Schema validity to be assessed, then the applicable schema must provide a definition of the item. If not, Schema validation makes no contribution to the validity test for the item.]
Lexical space: [Definition: From XML Schema [XML Schema part 2]: A lexical space is the set of valid literals for a datatype.] The XML serialization that may occur during submission expresses the instance data using lexical space literals.
Model Binding expression: [Definition: An [XPath 1.0] expression used in the nodeset attribute of a bind element in an XForms model. Often, a bind also declares computed expressions for model item properties of the nodes. ]
Model item: [Definition: An instance data node with associated constraints.]
Model item property: [Definition: An XForms-specific annotation to an instance data node.]
Non-relevant Form Control: [Definition: A form control satisfying at least one of the form control non-relevance conditions.]
QNameButNotNCName: [Definition: A QName that is not an NCName. In 2006, the W3C named this a PrefixedName. ]
Relevant Form Control: [Definition: A form control satisfying none of the form control non-relevance conditions.]
Schema constraint: [Definition: A restriction, applied to form data, based on XML Schema datatypes.]
Strict schema processing: [Definition: From XML Schema [XML Schema part 1]: If the applicable schema does not provide a definition for an element or attribute, then Schema validation marks the item as invalid.]
UI Binding Expression: [Definition: An [XPath 1.0] expression used in binding a form control to the instance.]
Valid node: [Definition: An instance data node is valid if and only if the constraint model item property is true, the value is non-empty if the required model item property is true, and the node satisfies all applicable XML Schema definitions (including those associated byt the type model item property, by xsi:type or by an external or inline schema).]
Value space: [Definition: From XML Schema [XML Schema part 2]: A set of values for a given datatype. Each value in the value space of a datatype is denoted by one or more literals in its lexical space.]
versionList: [Definition: A list ([XML Schema part 2]) with an atomic datatype ([XML Schema part 2]) of versionNumber.]
versionNumber: [Definition: A string consisting of a non-zero digit (1 to 9) followed by zero or more digits (0 to 9), then a period character (.), and then one or more digits (0-9). A version number is derived from string by restriction based on the following pattern value (excluding the quote marks): "[1-9]\d*\.\d+".]
XForms Model: [Definition: The non-visible definition of an XML form as specified by XForms. The XForms Model defines the individual model items and constraints and other run-time aspects of XForms.]
XForms Processor: [Definition: A software application or program that implements and conforms to the XForms specification.]

A References

A.1 Normative References

Exc-C14N: Exclusive XML Canonicalization Version 1.0, J. Boyer, D. Eastlake 3rd, J. Reagle, 2002. W3C Recommendation available at http://www.w3.org/TR/2002/REC-xml-exc-c14n-20020718/.
HMAC: RFC 2104 - HMAC: Keyed-Hashing for Message Authentication, H. Krawczyk, M. Bellare, R. Canetti, 1997. Available at http://www.ietf.org/rfc/rfc2104.txt
Luhn Patent: Computer for Verifying Numbers, H. P. Luhn, U.S. Patent 2,950,048, 1960.
MD5: RFC 1321: The MD5 Message-Digest Algorithm, R. Rivest, 1992. Available at http://www.ietf.org/rfc/rfc1321.txt
RFC 2119: RFC 2119: Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, 1997. Available at http://www.ietf.org/rfc/rfc2119.txt.
RFC 2387: RFC 2387: The MIME Multipart/Related Content-type, E. Levinson, 1998. Available at: http://www.ietf.org/rfc/rfc2387.txt.
RFC 2388: RFC 2388: Returning Values from Forms: multipart/form-data, L. Masinter, 1998. Available at: http://www.ietf.org/rfc/rfc2388.txt.
RFC 2396: RFC 2396: Uniform Resource Identifiers (URI): Generic Syntax, T. Berners-Lee, R. Fielding, L. Masinter, 1998. Available at: http://www.ietf.org/rfc/rfc2396.txt.
RFC 2616: RFC 2616: Hypertext Transfer Protocol -- HTTP/1.1, R. Fielding, J. Gettys, J. Mogul, H. Frystyk, L. Masinter, P. Leach, T. Berners-Lee,1999. Available at: http://www.ietf.org/rfc/rfc2616.txt.
RFC 2822: RFC 2822: Internet Message Format, P. Resnick, 2001. Available at: http://www.ietf.org/rfc/rfc2822.txt.
RFC 3023: RFC 3023: XML Media Types, M Murata, S. St. Laurent, D. Kohn, 2001. Available at: http://www.ietf.org/rfc/rfc3023.txt.
SHA2: SECURE HASH STANDARD. FIPS PUB 180-2, August 2002. Available at http://csrc.nist.gov/publications/fips/fips180-2/fips180-2.pdf
SOAP 1.1: Simple Object Access Protocol (SOAP) 1.1 , D. Box, D. Ehnebuske, G. Kakivaya, A. Layman, N. Mendelsohn, H. F. Nielsen, S. Thatte, D. Winer, 2000. Available at: http://www.w3.org/TR/2000/NOTE-SOAP-20000508/.
SOAP 1.2: SOAP Version 1.2 Part 1: Messaging Framework, M. Gudgin, M. Hadley, N. Mendelsohn, J.-J. Moreau, H. F. Nielsen, 2003. Available at: http://www.w3.org/TR/2003/REC-soap12-part1-20030624/.
Unicode Collation Algorithm: Unicode Technical Standard #10, Unicode Collation Algorithm, Available at: http://www.unicode.org/unicode/reports/tr10/.
XHTML Modularization: Modularization of XHTML, M. Altheim, et al., 2001. W3C Recommendation available at http://www.w3.org/TR/2001/REC-xhtml-modularization-20010410/.
XML Base: XML Base, Jonathan Marsh, 2001. W3C Recommendation available at: http://www.w3.org/TR/2001/REC-xmlbase-20010627/.
XML Events: XML Events - An events syntax for XML, Steven Pemberton, T. V. Raman, Shane P. McCarron, 2003. W3C Recommendation available at: http://www.w3.org/TR/2003/REC-xml-events-20031014/.
XHTML 1.0: XHTML 1.0: The Extensible HyperText Markup Language - A Reformulation of HTML 4 in XML 1.0, Steven Pemberton, et al., 2002. W3C Recommendation available at: http://www.w3.org/TR/2002/REC-xhtml1-20020801/.
XML 1.0: Extensible Markup Language (XML) 1.0 (Fourth Edition), Tim Bray, Jean Paoli, C. M. Sperberg-McQueen, Eve Maler, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml-20060816/
XML Names: Namespaces in XML (Second Edition), Tim Bray, Dave Hollander, Andrew Layman, and Richard Tobin, 2006. W3C Recommendation available at: http://www.w3.org/TR/2006/REC-xml-names-20060816/.
XPath 1.0: XML Path Language (XPath) Version 1.0, James Clark, Steve DeRose, 1999. W3C Recommendation available at: http://www.w3.org/TR/1999/REC-xpath-19991116.
XML Schema part 1: XML Schema Part 1: Structures, Henry S. Thompson, David Beech, Murray Maloney, Noah Mendelsohn, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/.
XML Schema part 2: XML Schema Part 2: Datatypes, Paul V. Biron, Ashok Malhotra, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/.
XSLT 1.0: XSL Transformations (XSLT) Version 1.0, James Clark, 1999. W3C Recommendation available at: http://www.w3.org/TR/1999/REC-xslt-19991116.

A.2 Informative References

Algorithms: The Art of Computer Programming: Volume 1 Fundamental Algorithms, D. E. Knuth, Addison-Wesley, Reading, MA. 1968. Third edition, 1997. ISBN:0-2018-9683-4.
AUI97: Auditory User Interfaces--Toward The Speaking Computer, T. V. Raman, Kluwer Academic Publishers, 1997. ISBN:0-7923-9984-6.
CDRF 1.0: Compound Document by Reference Framework 1.0, Timur Mehrvarz, Lasse Pajunen, Julien Quint, and Daniel Applequist, 2007. W3C Candidate Recommendation available at: http://www.w3.org/TR/2007/CR-CDR-20070718/.
CSS2: Cascading Style Sheets, level 2 (CSS2) Specification, Bert Bos, Håkon Wium Lie, Chris Lilley, Ian Jacobs, 1998. W3C Recommendation available at: http://www.w3.org/TR/1998/REC-CSS2-19980512/.
DDJ-ArrayDoubling: Resizable Arrays, Heaps and Hash Tables, John Boyer, Doctor Dobb's Journal, CMP Media LLC, January 1998 Issue.
DOM2 Core: Document Object Model (DOM) Level 2 Core Specification, Tom Pixley, 2000. W3C Recommendation available at: http://www.w3.org/TR/2000/REC-DOM-Level-2-Core-20001113/.
DOM2 Events: Document Object Model (DOM) Level 2 Events Specification, Tom Pixley, 2000. W3C Recommendation available at: http://www.w3.org/TR/2000/REC-DOM-Level-2-Events-20001113/.
EXSLT: EXSLT Web site. Available at http://www.exslt.org.
Java Unicode Blocks: Java 2 Platform, Standard Edition, v 1.4.2 API Specification; Class Character.UnicodeBlock, Sun Microsystems, Inc, 2003. Available at http://java.sun.com/j2se/1.4.2/docs/api/java/lang/Character.UnicodeBlock.html.
ODF 1.1: Open Document Format for Office Applications (OpenDocument) v1.1, Patrick Durusau, Michael Brauer, and Lars Oppermann (editors), 2007. OASIS Standard available at: http://docs.oasis-open.org/office/v1.1/OS/OpenDocument-v1.1-html/OpenDocument-v1.1.html.
P3P 1.0: The Platform for Privacy Preferences 1.0 (P3P1.0) Specification, Lorrie Cranor, Marc Langheinrich, Massimo Marchiori, Martin Presler-Marshall, Joseph Reagle, 2002. W3C Recommendation available at: http://www.w3.org/TR/2002/REC-P3P-20020416/.
SVG 1.1: SVG 1.1, Jon Ferraiolo, FUJISAWA Jun, Dean Jackson, 2003. W3C Recommendation available at: http://www.w3.org/TR/2003/REC-SVG11-20030114/.
TAG Finding 7: TAG Finding: URIs, Addressability, and the use of HTTP GET, Ian Jacobs, 2004. Available at: http://www.w3.org/2001/tag/doc/whenToUseGet-20040321
Unicode Script Names: ISO 15924: Codes for the representation of names of scripts, Available at: http://unicode.org/iso15924/iso15924-codes.html.
UAAG 1.0: User Agent Accessibility Guidelines 1.0, Ian Jacobs, Jon Gunderson, Eric Hansen, 2002. Working Draft available at http://www.w3.org/TR/UAAG10/.
Unicode Scripts: Script Names, Mark Davis, 2001. Unicode Technical Report #24 available at http://www.unicode.org/unicode/reports/tr24/.
XForms 1.0: XForms 1.0 Third Edition, John Boyer, 2007. W3C Recommendation available at: http://www.w3.org/TR/2007/REC-xforms-20071029/.
XForms Basic: XForms Basic Profile, Micah Dubinko, T. V. Raman, 2003. W3C Candidate Recommendation available at: http://www.w3.org/TR/2003/CR-xforms-basic-20031014/.
XLink 1.0: XML Linking Language (XLink) Version 1.0, Steve DeRose, Eve Maler, David Orchard, 2001. W3C Recommendation available at: http://www.w3.org/TR/2001/REC-xlink-20010627/.
XPath 2.0: XML Path Language (XPath) 2.0, Anders Berglund, Scott Boag, Don Chamberlin, Mary F. Fernández, Michael Kay, Jonathan Robie, and Jérôme Siméon, 2007. W3C Recommendation available at: http://www.w3.org/TR/2007/REC-xpath20-20070123/.
XML Schema part 0: XML Schema Part 0: Primer Second Edition, David C. Fallside and Priscilla Walmsley, 2004. W3C Recommendation available at: http://www.w3.org/TR/2004/REC-xmlschema-0-20041028/.

B Insert and Delete Action Patterns for Data Mutations

This appendix provides several usage patterns for the insert and delete actions that perform various kinds of mutations of instance data elements and attributes.

B.1 Prepend Element Copy

Pattern: <insert context="parent of new element" origin="element to copy"/>

Note:

The context attribute is used so that this pattern will work whether or not the parent element is empty.

Operation: Prepend a new, empty person element into a list of people

<xforms:insert context="people" origin="instance('prototypes')/person"/>

Data Before Operation

<xforms:instance>
   <data xmlns="">
       <people>
           <person>
               <name>Jane Doe</name>
           </person>
       </people>
   </data>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name/>
        </person>
    </prototypes>
</xforms:instance>

Data After Operation

<xforms:instance>
   <data xmlns="">
       <people>
           <person>
               <name/>
           </person>
           <person>
               <name>Jane Doe</name>
           </person>
       </people>
   </data>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name/>
        </person>
    </prototypes>
</xforms:instance>

B.2 Append Element Copy

Pattern: <insert context="parent of new element" nodeset="*" origin="element to copy"/>

Note:

The context attribute is used so that this pattern will work whether or not the parent element is empty.

Operation: Append a new, empty person element into a list of people

<xforms:insert context="people" nodeset="person" origin="instance('prototypes')/person"/>

Data Before Operation

<xforms:instance>
   <data xmlns="">
       <people>
           <person>
               <name>Jane Doe</name>
           </person>
       </people>
   </data>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name/>
        </person>
    </prototypes>
</xforms:instance>

Data After Operation

<xforms:instance>
   <data xmlns="">
       <people>
           <person>
               <name>Jane Doe</name>
           </person>
           <person>
               <name/>
           </person>
       </people>
   </data>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name/>
        </person>
    </prototypes>
</xforms:instance>

B.3 Duplicate Element

Pattern: <insert nodeset="exact element to duplicate"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate an exact element to duplicate, so nodeset is used. If the element does not exist, the operation will have no effect.

Operation: Duplicate the selected element and place it as a following sibling

<xforms:insert nodeset="paragraph[2]"/>

Data Before Operation

<xforms:instance>
    <document xmlns="">
        <header>Lorem ipsum</header>
        <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
        <paragraph>Primis abhorreant delicatissimi ..</paragraph>
        <header>Lorem ipsum</header>
        <header>Lorem ipsum</header>
    </document>
</xforms:instance>

Data After Operation

<xforms:instance>
    <document xmlns="">
        <header>Lorem ipsum</header>
        <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
        <paragraph>Primis abhorreant delicatissimi ...</paragraph>
        <paragraph>Primis abhorreant delicatissimi ...</paragraph>
        <header>Lorem ipsum</header>
        <header>Lorem ipsum</header>
    </document>
</xforms:instance>

B.4 Set Attribute

Pattern: <insert context="container element receiving attribute" origin="attribute to copy"/>

Note:

The nodeset attribute is not used because this pattern cannot indicate an exact attribute sibling of the attribute being inserted. This is true not only because attribute order is not guaranteed but also because the attribute being inserted may already exist, in which case the existing attribute is replaced. The context attribute is used when it is necessary to indicate the parent of the node being inserted.

Operation: Create or replace an attribute with a copy of a given attribute

<xforms:insert context="item[2]" origin="../item[1]/@rating"/>
<xforms:insert context="item[3]" origin="../item[1]/@rating"/>

Data Before Operation

<xforms:instance>
    <items xmlns="">
        <item key="23" rating="classified"/>
        <item key="42"/>
        <item key="68" rating="unknown"/>
    </items>
</xforms:instance>

Data After Operation

<xforms:instance>
    <items xmlns="">
        <item key="23" rating="classified"/>
        <item key="42" rating="classified"/>
        <item key="68" rating="classified"/>
    </items>
</xforms:instance>

B.5 Remove Element

Pattern: <delete nodeset="exact element to remove"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate an exact element to remove, so nodeset is used. If the element does not exist, the operation will have no effect.

Operation: Remove item element in case it exists

<xforms:delete nodeset="item[2]"/>

Data Before Operation

<xforms:instance>
    <shoppingcart xmlns="">
        <item>
            <product>SKU-0815</product>
            <quantity>1</quantity>
            <unitcost>29.99</unitcost>
            <price>29.99</price>
        </item>
        <item>
            <product>SKU-4711</product>
            <quantity>3</quantity>
            <unitcost>7.49</unitcost>
            <price>22.47</price>
        </item>
    </shoppingcart>
</xforms:instance>

Data After Operation

<xforms:instance>
    <shoppingcart xmlns="">
        <item>
            <product>SKU-0815</product>
            <quantity>1</quantity>
            <unitcost>29.99</unitcost>
            <price>29.99</price>
        </item>
    </shoppingcart>
</xforms:instance>

B.6 Remove Attribute

Pattern: <delete nodeset="exact attribute to remove"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate an exact attribute to remove, so nodeset is used. If the attribute does not exist, the operation will have no effect.

Operation: Remove rating attribute in case it exists

<xforms:delete nodeset="item/@rating"/>

Data Before Operation

<xforms:instance>
    <items xmlns="">
        <item key="23" rating="classified"/>
    </items>
</xforms:instance>

Data After Operation

<xforms:instance>
    <items xmlns="">
        <item key="23"/>
    </items>
</xforms:instance>

B.7 Remove Nodeset

Pattern: <delete nodeset="nodeset to remove"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate a nodeset to remove, so nodeset is used. If the nodeset does not exist, the operation will have no effect.

Operation: Remove track nodeset in case it exists

<xforms:delete nodeset="track"/>

Data Before Operation

<xforms:instance>
    <playlist xmlns="">
        <name>Music for Airports</name>
        <track id="382"/>
        <track id="461"/>
        <track id="629"/>
    </playlist>
</xforms:instance>

Data After Operation

<xforms:instance>
    <playlist xmlns="">
        <name>Music for Airports</name>
    </playlist>
</xforms:instance>

B.8 Copy Nodeset

Pattern: <insert context="parent of new nodeset" nodeset="*" origin="nodeset to copy"/>

Note:

The context attribute is used so that this pattern will work whether or not the parent element is empty.

Operation: Append a person nodeset into a list of people

<xforms:insert context="people" nodeset="person" origin="instance('prototypes')/person"/>

Data Before Operation

<xforms:instance>
    <data xmlns="">
        <people/>
    </data>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name>Jane Doe</name>
        </person>
        <person>
            <name>John Doe</name>
        </person>
        <person>
            <name>Joe Sixpack</name>
        </person>
    </prototypes>
</xforms:instance>

Data After Operation

<xforms:instance>
    <data xmlns="">
        <people>
            <person>
                <name>Jane Doe</name>
            </person>
            <person>
                <name>John Doe</name>
            </person>
            <person>
                <name>Joe Sixpack</name>
            </person>
        </people>
    </data>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name>Jane Doe</name>
        </person>
        <person>
            <name>John Doe</name>
        </person>
        <person>
            <name>Joe Sixpack</name>
        </person>
    </prototypes>
</xforms:instance>

B.9 Copy Attribute List

Pattern: <insert nodeset="exact element receiving attribute list" origin="attribute list to copy"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate an exact element to receive an attribute list, so nodeset is used.

Operation: Copy attribute list from one item to another

<xforms:insert nodeset="item[2]" origin="item[1]/@*"/>

Data Before Operation

<xforms:instance>
    <items xmlns="">
        <item key="0" rating="classified"/>
        <item/>
    </items>
</xforms:instance>

Data After Operation

<xforms:instance>
    <items xmlns="">
        <item key="0" rating="classified"/>
        <item key="0" rating="classified"/>
    </prototypes>
</xforms:instance>

B.10 Replace Element

Pattern: <insert nodeset="exact element to replace" origin="element to copy"/> <delete nodeset="exact element to replace"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate an exact element to replace, so nodeset is used. If the element does not exist, both insert and delete operation will have no effect.

Operation: Replace a person element by copying a new one and removing the old one

<xforms:insert nodeset="person[1]" origin="instance('prototypes')/person"/>
<xforms:delete nodeset="person[1]"/>

Data Before Operation

<xforms:instance>
    <people xmlns="">
        <person>
            <name>John Doe</name>
        </person>
    </people>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name/>
        </person>
    </prototypes>
</xforms:instance>

Data After Operation

<xforms:instance>
    <people xmlns="">
        <person>
            <name/>
        </person>
    </people>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <person>
            <name/>
        </person>
    </prototypes>
</xforms:instance>

B.11 Replace Attribute

Pattern: <insert nodeset="exact attribute to replace" origin="attribute to copy"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate an exact attribute to replace, so nodeset is used. If the attribute does not exist, the operation will have no effect. Insert implements special handling for attributes ensuring that an attribute is not duplicated for a certain element, thus a delete operation is not necessary.

Operation: Replace an attribute with the copy of a given attribute

<xforms:insert nodeset="item[2]/@key" origin="item[1]/@key"/>

Data Before Operation

<xforms:instance >
    <items xmlns="">
        <item key="0"/>
        <item key="4711"/>
    </items>
</xforms:instance>

Data After Operation

<xforms:instance >
    <items xmlns="">
        <item key="0"/>
        <item key="0"/>
    </items>
</xforms:instance>

B.12 Replace Instance with Insert

Pattern: <insert nodeset="root node of instance to replace" origin="element to copy"/>

Note:

The context attribute is not used because this pattern assumes the ability to indicate an instance root node to replace, so nodeset is used. Since an instance cannot be empty, nodeset will always be non-empty. Insert implements special handling for instance root nodes, thus a delete operation is not necessary.

Operation: Replace instance root node with an empty shoppingcart element

<xforms:insert nodeset="." origin="instance('prototypes')/shoppingcart"/>

Data Before Operation

<xforms:instance>
    <shoppingcart xmlns="">
        <item>
            <product>SKU-0815</product>
            <quantity>1</quantity>
            <unitcost>29.99</unitcost>
            <price>29.99</price>
        </item>
        <item>
            <product>SKU-4711</product>
            <quantity>3</quantity>
            <unitcost>7.49</unitcost>
            <price>22.47</price>
        </item>
    </shoppingcart>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <shoppingcart/>
    </prototypes>
</xforms:instance>

Data After Operation

<xforms:instance>
    <shoppingcart xmlns=""/>
</xforms:instance>

<xforms:instance>
    <prototypes xmlns="">
        <shoppingcart/>
    </prototypes>
</xforms:instance>

B.13 Move Element

Pattern: <insert context="new parent of element" nodeset="*" origin="exact element to move"/> <delete nodeset="exact element to move"/>

Note:

The context attribute is used for insert so that this pattern will work whether or not the new parent element is empty. For delete the nodeset attribute is used instead because this pattern assumes the ability to indicate an exact element to move. If the element to be moved does not exist, both insert and delete operation will have no effect.

Operation: Copy an existing element to a new parent and remove the original

<xforms:insert context="playlist[2]" nodeset="track" origin="../playlist[1]/track[2]"/>
<xforms:delete nodeset="playlist[1]/track[2]"/>

Data Before Operation

<xforms:instance>
    <library xmlns="">
        <playlist>
            <name>Music for Airports</name>
            <track id="382"/>
            <track id="461"/>
            <track id="629"/>
        </playlist>
        <playlist>
            <name>Lullabies</name>
            <track id="251"/>
            <track id="331"/>
        </playlist>
    </library>
</xforms:instance>

Data After Operation

<xforms:instance>
    <library xmlns="">
        <playlist>
            <name>Music for Airports</name>
            <track id="382"/>
            <track id="629"/>
        </playlist>
        <playlist>
            <name>Lullabies</name>
            <track id="251"/>
            <track id="331"/>
            <track id="461"/>
        </playlist>
    </library>
</xforms:instance>

B.14 Move Attribute

Pattern: <insert nodeset="exact element receiving attribute" origin="exact attribute to move"/> <delete nodeset="exact attribute to move"/>

Note:

The context attribute is not used for insert because this pattern assumes the ability to indicate an exact element to receive an attribute, so nodeset is used. If the attribute to be moved does not exist, both insert and delete operation will have no effect.

Operation: Copy an existing attribute to a new element and remove the original

<xforms:insert nodeset="item[2]" origin="item[1]/@rating"/>
<xforms:delete nodeset="item[1]/@rating"/>

Data Before Operation

<xforms:instance>
    <items xmlns="">
        <item key="23" rating="classified"/>
        <item key="42"/>
    </items>
</xforms:instance>

Data After Operation

<xforms:instance>
    <items xmlns="">
        <item key="23"/>
        <item key="42" rating="classified"/>
    </items>
</xforms:instance>

B.15 Insert Element into Non-Contiguous, Heterogeneous Nodeset

Pattern: <insert nodeset="non-contiguous, heterogeneous nodeset" origin="element to copy" at="insert location"/>

Note:

The context attribute is not used because it adheres to the first node rule and therefore would not allow to select a non-contiguous nodeset. The nodeset attribute is used instead to select a nodeset consisting of nodes with different names and different parents. The parent of the new node is the same as the parent of the insert location node selected by the combination of nodeset and at.

Operation: Copy an existing element into a non-contiguous, heterogeneous nodeset at a specified position

<xforms:insert nodeset="chapter/*" origin="instance('prototypes')/paragraph" at="7" position="before"/>

Data Before Operation

<xforms:instance>
    <document xmlns="">
        <chapter>
            <header>Lorem ipsum</header>
            <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
            <diagram>Exemplum 1</diagram>
            <diagram>Exemplum 2</diagram>
            <paragraph>Primis abhorreant delicatissimi ...</paragraph>
        </chapter>
        <chapter>
            <header>Lorem ipsum</header>
            <diagram>Exemplum 3</diagram>
        </chapter>
    </document>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <chapter/>
        <header/>
        <paragraph/>
        <diagram/>
    </prototypes>
</xforms:instance>

Data After Operation

<xforms:instance>
    <document xmlns="">
        <chapter>
            <header>Lorem ipsum</header>
            <paragraph>Lorem ipsum verterem voluptaria ...</paragraph>
            <diagram>Exemplum 1</diagram>
            <diagram>Exemplum 2</diagram>
            <paragraph>Primis abhorreant delicatissimi ...</paragraph>
        </chapter>
        <chapter>
            <header>Lorem ipsum</header>
            <paragraph/>
            <diagram>Exemplum 3</diagram>
        </chapter>
    </document>
</xforms:instance>

<xforms:instance id="prototypes">
    <prototypes xmlns="">
        <chapter/>
        <paragraph/>
        <diagram/>
    </prototypes>
</xforms:instance>

C Acknowledgements (Non-Normative)

This document was produced with the participation of Forms Working Group participants. Current participants include:

John M. Boyer, IBM (Chair, Editor)
Steven Pemberton, W3C/CWI (Activity Lead, W3C Team Contact)
Blake Jones, DAISY Consortium and ViewPlus Technologies
Ulrich Nicolas Lissé, DreamLab
Sebastian Schnitzenbaumer, DreamLab (Co-chair until 2003)
Joern Turner, DreamLab
T. V. Raman, Google
Keith Wells, IBM
Charlie Wiecha, IBM
Nick Van den Bleeken, Inventive Designers n.v.
Erik Bruchez, Orbeon
Mark Seaborne, PicoForms
Kenneth Sklander, PicoForms
Susan Borgrink, Progeny Systems
Rafael Benito Ruiz de Villa, SATEC
Rogelio Pérez Cano, SATEC
Lars Oppermann, Sun Microsystems
Mark Birbeck, x-port.net Ltd. (Invited Expert)
Leigh L. Klotz, Jr., Xerox Corporation

D Production Notes (Non-Normative)

This document was encoded in the XMLspec DTD v2.6. The XML sources were transformed using diffspec and xmlspec stylesheets, version 2.6. The XML Schema portion of the Appendix was rendered into HTML with the xmlverbatim XSLT stylesheet (used with permission). The primary tool used for editing was XMLSpy. The XML was transformed using the XSLT processor in Java 6. The editor(s) use the W3C CVS repository and the W3C IRC server for collaborative authoring.

Editorial note: Need to move to Model module
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.

XForms 1.2 Data Layer

W3C First Public Working Draft 03 February 2009

Abstract

Status of this Document

Table of Contents

Appendices

1 About the XForms Data Layer Specification

1.1 Background

1.2 Reading the Specification

1.3 How the Specification is Organized

1.4 Documentation Conventions

2 Introduction to the XForms Data Layer

2.1 Providing XML Instance Data

3 Data Island Module

3.1 The instance Element

3.1.1 Instance element attributes

3.1.2 Instance element processing

3.2 XML Data Island Events overview

3.2.1 The data-instance-load Event

3.2.2 The data-instance-ready Event

3.2.3 The data-link-error Event

3.3 DOM Interface for Access to XML Instance Data

3.3.1 The getInstanceDocument() Method

3.3.2 The setInstanceDocument() Method

3.3.3 The load() Method

4 Binding Attributes Module

4.1 Introduction

4.2 Bindings

4.2.1 Single-Node Binding Attribute Group

4.2.2 Node-Set Binding Attribute Group

4.3 Evaluation Context

4.4 XPath Function Library

4.4.1 Node-set Functions

4.4.1.1 The context() Function

4.5 References, Dependencies, and Dynamic Dependencies

5 Data Accessors Module

5.1 The instance Element

5.2 The setvalue Element

5.2.1 Setvalue attributes

5.2.2 Setvalue processing

5.3 The insert Element

5.3.1 Insert attributes

5.3.2 The xforms-insert Event

5.3.3 Insert action processing

5.3.4 Insert action examples

5.4 The delete Element

5.4.1 Delete action attributes

5.4.2 The xforms-delete Event

5.4.3 Delete action processing

5.4.4 Delete action examples

5.5 DOM Interface for Access to XForms Instance Data

5.5.1 The setvalue() Method

5.5.2 The insert() Method

5.5.3 The delete() Method

6 Processing Model

7 XPath Functions Module

7.1 Introduction

7.2 XPath Function Library

7.2.1 Data Integrity Functions

7.2.1.1 The is-card-number() Function

7.2.1.2 The digest() Function

7.2.1.3 The hmac() Function

7.2.2 Date and Time Functions

7.2.2.1 The local-date() Function

7.2.2.2 The local-dateTime() Function

7.2.2.3 The now() Function

7.2.2.4 The days-from-date() Function

7.2.2.5 The days-to-date() Function

7.2.2.6 The seconds-from-dateTime() Function

7.2.2.7 The seconds-to-dateTime() Function

7.2.2.8 The adjust-dateTime-to-timezone() Function

7.2.2.9 The seconds() Function

7.2.2.10 The months() Function

7.2.3 Conditional Functions

7.2.3.1 The if() Function

7.2.3.2 The choose() Function

7.2.3.3 The compare() Function

7.2.3.4 The count-non-empty() Function

7.2.3.5 The boolean-from-string() Function

7.2.3.6 The current() Function

5.3 The `insert` Element

5.4 The `delete` Element