XForms Instance Data Module

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

1.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.

1.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).

1.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.

1.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 ??? 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 [ref-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.

1.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.

1.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.

1.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.

1.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.

1.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 1.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 ??? for numerous further usage patterns for `insert` and `delete`.

1.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.

1.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.

1.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.

1.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.

1.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 ??? for numerous further usage patterns for insert and delete.

1.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 [ref-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 {
				void setvalue(contextNode, contextExpr, stringValue);
				boolean insert(contextNode, contextExpr, nodesetExpr, atExpr, positionExpr, originExpr);
				boolean delete(contextNode, contextExpr, nodesetExpr, atExpr);
			  };
			};

1.5.1 The setvalue() Method

text...

1.5.2 The insert() Method

text...

1.5.3 The delete() Method

text...

XForms Instance Data Module

W3C First Public Working Draft 12 October 2008

Abstract

Status of this Document

Table of Contents

1 The XForms Instance Data Module

1.1 The instance Element

1.2 The setvalue Element

1.2.1 Setvalue attributes

1.2.2 Setvalue processing

1.3 The `insert` Element

1.3.1 Insert attributes

1.3.2 The xforms-insert Event

1.3.3 Insert action processing

1.3.4 Insert action examples

1.4 The `delete` Element

1.4.1 Delete action attributes

1.4.2 The xforms-delete Event

1.4.3 Delete action processing

1.4.4 Delete action examples

1.5 DOM Interface for Access to XForms Instance Data

1.5.1 The setvalue() Method

1.5.2 The insert() Method

1.5.3 The delete() Method

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 Instance Data Module

W3C First Public Working Draft 12 October 2008

Abstract

Status of this Document

Table of Contents

1 The XForms Instance Data Module

1.1 The instance Element

1.2 The setvalue Element

1.2.1 Setvalue attributes

1.2.2 Setvalue processing

1.3 The insert Element

1.3.1 Insert attributes

1.3.2 The xforms-insert Event

1.3.3 Insert action processing

1.3.4 Insert action examples

1.4 The delete Element

1.4.1 Delete action attributes

1.4.2 The xforms-delete Event

1.4.3 Delete action processing

1.4.4 Delete action examples

1.5 DOM Interface for Access to XForms Instance Data

1.5.1 The setvalue() Method

1.5.2 The insert() Method

1.5.3 The delete() Method

1.3 The `insert` Element

1.4 The `delete` Element