XForms Instance Data Module

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

1.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 processing halts after dispatching an xforms-link-exception 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 processing halts after dispatching an xforms-link-exception 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 exception 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.

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 bind="put-here" value="a/b/c"/>

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

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.

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:

Default Action: None; notification event only.

1.3.3 Insert action processing

Processing for the insert action is as follows:

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

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

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

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

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

6. Each node in the origin node-set is cloned in the order it appears in the origin node-set.

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

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

9. The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.

10. The insert action is successfully completed by dispatching the xforms-insert event with appropriate context information.

    Note:

    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.

1.3.4 Insert action examples

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

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

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

Default Action: None; notification event only.

1.4.3 Delete action processing

Processing for the delete action is as follows:

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

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

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

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

5. The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.

6. The delete action is successfully completed by dispatching the xforms-delete event with appropriate context information.

1.4.4 Delete action examples

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

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

See Appendix ??? for numerous further usage patterns for insert and delete.