XForms 1.1

2.1 An Example

In the XForms approach, forms are comprised of a section that describes what the form does, called the XForms Model, and another section that describes how the form is to be presented.

Consider a simple electronic commerce form that might be rendered as follows:

It is clear that we are collecting a value that represents whether cash or a credit card is being used, and if a credit card, its number and expiration date.

This can be represented in the XForms model element, which in XHTML would typically be contained within the head section:

<xforms:model>
  <xforms:instance>
    <ecommerce xmlns="">
      <method/>
      <number/>
      <expiry/>
    </ecommerce>
  </xforms:instance>
  <xforms:submission action="http://example.com/submit" method="post" id="submit" includenamespaceprefixes=""/>
</xforms:model>

This simply says that we are collecting three pieces of information (note that we have as yet not said anything about their types), and that they will be submitted using the URL in the action attribute.

XForms defines a device-neutral, platform-independent set of form controls suitable for general-purpose use. The controls are bound to the XForms Model via the XForms binding mechanism, in this simple case using the ref attribute on the controls. In XHTML, this markup would typically appear within the body section (note that we have intentionally defaulted the XForms namespace prefix here):

<select1 ref="method">
  <label>Select Payment Method:</label>
  <item>
    <label>Cash</label>
    <value>cash</value>
  </item>
  <item>
    <label>Credit</label>
    <value>cc</value>
  </item>
</select1>
<input ref="number">
  <label>Credit Card Number:</label>
</input>
<input ref="expiry">
  <label>Expiration Date:</label>
</input>
<submit submission="submit">
  <label>Submit</label>
</submit>

Notice the following features of this design:

• The user interface is not hard-coded to use radio buttons. Different devices (such as voice browsers) can render the concept of "select one" as appropriate.

• Core form controls always have labels directly associated with them as child elements— this is a key feature designed to enhance accessibility.

• There is no need for an enclosing form element, as in HTML. (See 2.4 Multiple Forms per Document for details on how to author multiple forms per document)

• Markup for specifying form controls has been simplified in comparison with HTML forms.

The fact that you can bind form controls to the model like this simplifies integrating XForms into other host languages, since any form control markup may be used to bind to the model.

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

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

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

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

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

2.3 Constraining Values

XForms allows data to be checked for validity as the form is being filled. In the absence of specific information about the types of values being collected, all values are returned as strings, but it is possible to assign types to values in the instance data. In this example, number should accept digits only, and should have between 14 and 18 digits and expiry should accept only valid month/date combinations.

Furthermore, the credit card information form controls for number and expiry are only relevant if the "cc" option is chosen for method, but are required in that case.

By specifying an additional component, model item properties, authors can include rich declarative validation information in forms. Such information can be taken from XML Schemas as well as XForms-specific additions, such as relevant. Such properties appear on bind elements, while Schema constraints are expressed in an XML Schema fragment, either inline or external. For example:

... xmlns:my="http://commerce.example.com/payment"...
        
  <xforms:model>
    ...
    <xforms:bind nodeset="/my:payment/my:number"
		 relevant="/my:payment/@method = 'cc'"
		 required="true()"
		 type="my:ccnumber"/>

    <xforms:bind nodeset="/my:payment/my:expiry"
		 relevant="/my:payment/@method = 'cc'"
		 required="true()"
		 type="xsd:gYearMonth"/>

    <xs:schema ...>
      ...
      <xs:simpleType name="ccnumber">
	<xs:restriction base="xsd:string">
	  <xs:pattern value="\d{14,18}"/>
	</xs:restriction>
      </xs:simpleType>
      ...
    </xs:schema>
  </xforms:model>

2.4 Multiple Forms per Document

XForms processing places no limits on the number of individual forms that can be placed in a single containing document. When a single document contains multiple forms, each form needs a separate model element, each with an id attribute so that they can be referenced from elsewhere in the containing document.

In addition, form controls should specify which model element contains the instance data to which they bind. This is accomplished through a model attribute that is part of the binding attributes. If no model attribute is specified on the binding element, the nearest ancestor binding element's model attribute is used, and failing that, the first XForms Model in document order is used. This technique is called 'scoped resolution', and is used frequently in XForms.

The next example adds an opinion poll to our electronic commerce form.

<xforms:model>
  <xforms:instance>
    ...payment instance data...
  </xforms:instance>
  <xforms:submission action="http://example.com/submit" method="post"/>
</xforms:model>
        
<xforms:model id="poll">
  <xforms:instance>
    <helpful/>
  </xforms:instance>
  <xforms:submission id="pollsubmit" .../>
</xforms:model>

Additionally, the following markup would appear in the body section of the document:

<xforms:select1 ref="/helpful" model="poll">
  <xforms:label>How useful is this page to you?</xforms:label>
  <xforms:item>
    <xforms:label>Not at all helpful</xforms:label>
    <xforms:value>0</xforms:value>
  </xforms:item>
  <xforms:item>
    <xforms:label>Barely helpful</xforms:label>
    <xforms:value>1</xforms:value>
  </xforms:item>
  <xforms:item>
    <xforms:label>Somewhat helpful</xforms:label>
    <xforms:value>2</xforms:value>
  </xforms:item>
  <xforms:item>
    <xforms:label>Very helpful</xforms:label>
    <xforms:value>3</xforms:value>
  </xforms:item>
</xforms:select1>
        
<xforms:submit submission="pollsubmit">
  <xforms:label>Submit</xforms:label>
</xforms:submit>

The main difference here is the use of model="poll", which identifies the instance. Note that submit refers to the submission element by ID and does not require binding attributes.

More XForms examples can be found in H Complete XForms Examples.

7.1 XPath Datatypes

XPath datatypes are used only in binding expressions and computed expressions. XForms uses XPath datatypes boolean, string, number, and node-set. Additionally, the type object is used to denote a parameter or return value that can be any one of the four XPath datatypes. A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes.

7.2 Evaluation Context

Within XForms, the default model is the first model in document order. The default instance of any model is the first child instance in document order within that model. XPath expressions appearing in various XForms attributes are used to reference instance data. Every XPath expression requires an evaluation context consisting of a node, position, size, variable bindings, function set, and namespace context. For all evaluation contexts in XForms,

1. No variable bindings are in place.

2. The available function library is defined below in 7.5 The XForms Function Library.

3. Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.

4. The context node, position and size are determined according to rules described below.

A binding element is any element that is explicitly allowed to have a binding expression attribute, and a bound element is any element that explicitly declares a binding expression attribute. A binding expression attribute contains an XPath expression that references zero or more nodes of instance data. Every XPath expression requires an evaluation context. The in-scope evaluation context of a binding element provides an evaluation context for the binding expression attribute. The following rules are used in determining the node, position and size of the in-scope evaluation context:

1. A binding element is "outermost" if the element has no ancestor binding elements. If an outermost binding element is contained by a model, then the context node for the outermost binding element is the top-level document element node of the default instance of the containing model element. Otherwise, the context node for outermost binding elements is the top-level document element node of the default instance in the default model. For outermost binding elements, the context size and position are 1.

2. The context node, position and size for non-outermost binding elements is determined using the binding expression attribute or in-scope evaluation context of the nearest ancestor binding element. This is also referred to as "scoped resolution". For a non-outermost binding element:

   1. If the nearest ancestor binding element is not a bound element, then the in-scope evaluation context of the non-outermost binding element is equivalent to the in-scope evaluation context of the nearest ancestor binding element.

   2. If the nearest ancestor binding element expresses a Single-Node binding, then the in-scope evaluation context of the non-outermost binding element has a context size and position of 1 and the context node is the one resulting from the Single-Node binding of the nearest ancestor binding element.

   3. If the nearest ancestor binding element expresses a Node Set binding, then the XForms processor dynamically generates an occurrence of the non-outermost binding element for each of the nodes in the Node Set Binding of the nearest ancestor binding element. The dynamic in-scope evaluation context for each generated occurrence of the non-outermost binding element has a context size equal to the size of the nodeset identified by the Node Set Binding of the nearest ancestor binding element, the context node is the node for which the occurrence of the non-outermost binding element was generated, and the position is equal to the position of the generator node in the nodeset identified by the Node Set Binding of the nearest ancestor binding element.

   4. If the nearest ancestor binding element expresses a Node Set binding, then the non-outermost binding element has its own in-scope evaluation context separately from those of its dynamically generated occurences described above. The in-scope evaluation context has a context position of 1, and the context node and size are set by the first node and the size of the nodeset identified by the Node Set binding of the nearest ancestor binding element.

3. Once the context node of the in-scope evaluation context has been determined according to the rules above, if the binding element expresses a model attribute that refers to a model other than the one containing the context node, then the context node of the in-scope evaluation context is changed to be the top-level document element node of the default instance of the referenced model, and the context position and size are changed to 1.

The in-scope evaluation context of an element that is not a binding element is the same as if the element were a binding element. For example, the in-scope evaluation context for the setindex action element is required to provide the context for evaluating the index attribute, so it is determined as if the element could contain a binding expression attribute.

XPath expressions also appear in model item property attributes of the bind element to define computed expressions. If the bind element does not express a Node Set binding, then the in-scope evaluation context for model item property attributes of the bind is equal to the in-scope evaluation context for the bind. Otherwise, the bind has a Node Set binding, and computed expressions for each model item property attribute are generated for each node. For each computed expression generated, the evaluation context node, position and size are determined by the same method as dynamic in-scope evaluation context rule above, except the computed expression is used in lieu of a binding expression attribute such that the bind element is the nearest ancestor binding element.

XPath expressions also appear in the special attributes of several other XForms elements, such as the value attribute on setvalue and output, the at attribute of insert and delete, or the index attribute of setindex. Generally, if the containing element does not express a Single Node Binding or Node Set Binding, then the special attribute is evaluated using the in-scope evaluation context. Special attributes may be evaluated using the in-scope evaluation context even if the containing element expresses a Single Node Binding or Node Set Binding. However, for some special attributes, the evaluation context node, position and size are based on the result of the Single Node Binding or Node set Binding. Each special attribute that contains an XPath expression describes how its evaluation context node, position and size are determined.

In the following example, the group has a binding expression of level2/level3. According to the rules above, this outermost element node would have a context node of /level1, which is the document element node of the instance data. The select1 form control then inherits a context node from the parent group.

<level1>
  <level2>
    <level3 attr="xyz"/>
  </level2>
</level1>

<group ref="level2/level3">
  <select1 ref="@attr" ... >
     <label>...</label>
  </select1>
</group>

This section describes how the in-scope evaluation context of an element is determined, not whether the in-scope evaluation will be used. The Single-Node Binding or Node Set Binding of a non-outermost binding element is not evaluated if the in-scope evaluation context does not contain a context node. This can occur if the Single-Node Binding or Node Set Binding of the nearest ancestor bound element produces an empty nodeset. Also, if the Single-Node Binding or Node Set Binding of an element is expressed with the bind attribute, then the resulting node or nodeset is obtained from the referenced bind element. The nodeset attribute of a bind element is evaluated using the in-scope evaluation of the bind element, not the in-scope evaluation context of an element that references it with a bind attribute.

7.3 References, Dependencies, and Dynamic Dependencies

An XPath expression references a node of instance 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 instance nodes that it references.

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

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

The referencing of a repeat index by the index() function is handled as a special case. Implementations must behave as if each occurrence of a repeat is associated with an implicitly managed instance data node containing the repeat index. If a repeat identified as R1 contains a repeat identified as R2, then a repeat index instance node is managed for each occurrence of R2 that is generated by R1. An invocation of the function index() in an XPath expression is considered to reference the repeat index instance node corresponding to the repeat index value that it returns.

If an XPath expression references an instance node, then the expression result is dependent on the instance node. A dependency list for an instance node is the list of XPath expressions of a given category that are dependent upon the instance node. For example, in Section 4.3.2 The xforms-recalculate Event, the dependency list of computed expressions for each instance node helps establish the recalculation order for the computed expressions when the values of instance data nodes are changed.

The references of an XPath expression may be altered by insertion of instance 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 instance nodes that are being referenced by the XPath expression. An XPath expression is dynamically dependent on an instance node if its reference list is altered by inserting, deleting or changing the value of the instance node. An instance node is a dynamic dependency for an XPath expression if the expression is dynamically dependent on the instance node. If an XPath expression contains a dynamic dependency and the XForms processor is maintaining dependency lists for the category of the XPath expression, then changing the dynamic dependency implies a change to the dependency lists of instance nodes referenced by the XPath expression.

The computational dependency data structure described in Section 4.3.2 The xforms-recalculate Event essentially stores the dependency lists of instance nodes corresponding to all the references made by computed expressions (see Appendix C Recalculation Sequence Algorithm for details). The computational dependency data structure is not reconstructed in response to a dynamic dependency change. Instead, the form author may request a rebuild of the computational dependency data structures using the rebuild action. Additionally, the insert and delete actions set a rebuild flag so that computational dependency data structures will be rebuild at the end of an action sequence.

Due to the rebuild flag setting on insert and delete, a form author can use many kinds of dynamic dependencies in model binding expressions and computed expressions without ever explicitly invoking the rebuild action. This includes the use of functions such as position(), last(), and count() on element and attribute nodes because the return values of the functions in these cases is fixed except when an insert or delete occurs. By comparison, functions such as id(), instance(), and index() can establish dynamic dependencies that can necessitate invoking a rebuild if they are used in model binding expressions or computed expressions because the results of the functions are affected by changing the values of instance nodes, not by inserting or deleting nodes.

7.4 Expression Categories

There are several different categories of XPath expressions used in XForms, and they are processed at different times depending on the category. A binding expression is an XPath expression used to bind a model item property to one or more instance nodes, or to bind a form control to instance data, or to specify the node or node set for operation by an action. The evaluation schedule for binding expressions differs based on whether the binding expression is a model binding expression, UI binding expression, or a binding expression for an XForms action. XPath expressions are also used in various other attributes of XForms binds, actions, form controls, and submissions, and their descendant elements. These expressions follow one of the three schedules associated with binding expressions as described below.

<html:input type="text" name="..." xforms:bind="fn"/>

<xforms:model id="orders">
  <xforms:instance xmlns="">
    <orderForm>
      <shipTo>
        <firstName>John</firstName>
      </shipTo>
    </orderForm>
  </xforms:instance>
  <xforms:bind nodeset="/orderForm/shipTo/firstName" id="fn" />
</xforms:model>

<xforms:input ref="/orderForm/shipTo/firstName">...

<xforms:input bind="fn">...

<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...

7.5 The XForms Function Library

The XForms Function Library includes the entire [XPath 1.0] Core Function Library, including operations on node-sets, strings, numbers, and booleans.

The following sections define additional required functions for use within XForms : 7.6 Boolean Functions, 7.7 Number Functions, 7.8 String Functions, 7.9 Date and Time Functions, 7.10 Node-set Functions , and 7.11 Object Functions.

The function library provided by an XForms processor may also contain other extension functions as described in 7.12 Extension Functions.

If an error occurs in an XPath function, then an 4.5.2 The xforms-compute-exception Event or 4.5.1 The xforms-binding-exception Event occurs..

7.6 Boolean Functions

is-card-number('4111111111111111')

7.7 Number Functions

<xforms:trigger>
  <xforms:label>Add to Shopping Cart</xforms:label>
  <xforms:insert ev:event="DOMActivate" position="after"
                 nodeset="items/item" at="index('cartUI')"/>
</xforms:trigger>

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

compare('apple', 'orange')

7.8 String Functions

property('conformance-level')

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

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

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

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

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

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

7.9 Date and Time Functions

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

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

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

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

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

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

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

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

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

seconds-from-dateTime(28800)

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

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

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

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

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

seconds("P3DT10H30M1.5S")

7.10 Node-set Functions

<xforms:instance xmlns="" id="orderform">
  <orderForm>
    <shipTo>
      <firstName>John</firstName>
    </shipTo>
  </orderForm>
</xforms:instance>

ref="instance('orderform')/shipTo/firstName"

<xforms:instance xmlns="">
   <converter>
      <amount>100</amount>
      <currency>jpy</currency>
      <convertedAmount></convertedAmount>
   </converter>
</xforms:instance>
	
<xforms:instance xmlns="" id="convTable">
   <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>
</xforms:instance>

<bind nodeset="convertedAmount" 
      calculate="../amount * 
                 instance('convTable')/rate[@currency=current()/../currency]"/>

<xforms:instance xmlns="" id="i1">
   <months>
      <mon>01</mon>
      <mon>02</mon>
      <mon>03</mon>
   </months>
</xforms:instance>
<xforms:instance xmlns="" id="i2">
   <months>
      <month code="01">Jan</month>
      <month code="02">Feb</month>
      <month code="03">Mar</month>
   </months>
</xforms:instance>

<repeat nodeset="mon">
   <output value="instance('i2')/month[@code = current()]/>
</repeat>
	

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

7.11 Object Functions

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

7.12 Extension Functions

XForms documents may use additional XPath extension functions beyond those described here. A number of useful community extensions are defined at [EXSLT]. The names of any such extension functions must be declared in attribute functions on element model. Such declarations are used by the XForms Processor to check against available extension functions. XForms Processors perform this check at the time the document is loaded, and halt processing by signaling an exception (4.5.2 The xforms-compute-exception Event) if the XForms document declares an extension function for which the processor does not have an implementation.

Note:

XForms itself defines no method for script-based event handling. The definition of such facilities is a responsibility of the hosting language.

(action|setvalue|insert|delete|setindex|toggle|setfocus|dispatch|rebuild|recalculate|revalidate|refresh|reset|
load||send|message)*

Action Syntax

<xforms:trigger>
  <xforms:label>Reset</xforms:label>
  <xforms:reset ev:event="DOMActivate" model="thismodel"/>
</xforms:trigger>

Note:

The XForms processor is not considered to be executing an outermost action handler at the time that it performs deferred update behavior for XForms models. Therefore, event handlers for events dispatched to the user interface during the deferred refresh behavior are considered to be new outermost action handler.

10.1 The action Element

This action causes its child actions to be invoked in the order that they are specified in the document.

Common Attributes: Common, Events, Action Common

<trigger>
  <label>Click me</label>
  <action ev:event="DOMActivate">
    <reset model="thismodel"/>
    <setvalue ref="."/>
  </action>
</trigger>

10.2 The setvalue Element

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

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

Special Attributes:

value

Author-optional attribute containing an 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.

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

10.3 The insert Element

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.

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

Special Attributes:

context

Author-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 7.2 Evaluation Context 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 subsequent evaluation of many other attributes that can appear on insert, including if, while, nodeset and origin.

origin

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

Author-optional attribute containing an XPath expression evaluated using the Node Set Binding node-set to help determine the insert location node. 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

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

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. Namespace nodes and root nodes (parents of document elements) are removed from the origin node-set. 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 author-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 parent node of the target location is the instance root node (which is the parent of the root document element of the instance), and if the cloned node is an element, then the instance root element is deleted before the cloned node is inserted at the target location. If the cloned node is a duplicate of another attribute in its parent element, then either the duplicate attribute is first removed or the existing attribute value is updated. 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. Each cloned node that is inserted is added to the inserted-nodes list that will be provided in the xforms-insert event context information. For each cloned node used to update an existing attribute node, the existing attribute node is added to the list of inserted-nodes.

   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. If the list of inserted-nodes is empty, then the insert action is terminated with no effect.

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

11. 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 9.3.3 Repeat Processing for details.

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 10.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 Patterns for Data Mutations for numerous further usage patterns for sevalue, insert and delete.

10.4 The delete Element

This action deletes one or more nodes from instance data.

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

Special Attributes:

context

Author-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 7.2 Evaluation Context 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

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

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 behavior of the delete action is undefined if the Node Set Binding node-set contains nodes from more than one instance. 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, a namespace node, a root 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.

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 B Patterns for Data Mutations for numerous further usage patterns for sevalue, insert and delete.

10.5 The setindex Element

This XForms Action begins by invoking the deferred update behavior. This action then marks a specific item as current in a repeating sequence (within 9.3.1 The repeat Element).

Common Attributes: Common, Events, Action Common

Special Attributes:

repeat

Required reference to a repeating element.

index

Required XPath expression that evaluates to a 1-based offset into the sequence. The evaluation context is determined in the same manner as the evaluation context for a Single-Node Binding (see 7.2 Evaluation Context).

If the selected index is 0 or less, an xforms-scroll-first event is dispatched and the index is set to 1. If the selected index is greater than the index of the last repeat item, an xforms-scroll-last event is dispatched and the index is set to that of the last item. If the index evaluates to NaN the action has no effect.

10.6 The toggle Element

This XForms Action begins by invoking the deferred update behavior. This action then selects one possible case from an exclusive list of alternatives in a switch.

This action performs the following:

1. Dispatches an xforms-deselect event to the currently selected case in the switch containing the identified case.

2. Adjusts the selected states (not the attribute values) on the affected cases to reflect the new state of the switch containing the identified case.

3. Dispatches an xform-select event to the case just selected.

Common Attributes: Common, Events, Action Common

Special Attributes:

case

Author-optional reference to a case element. The case to select is specified by this attribute or by the child element case.

The case to be selected by the switch is identified by IDREF either by the attribute case or by a child case element. If no case element contains the given identifier, then this action has no effect.

<toggle>
<case value="concat('case_', ../addressBlockType)"/>
</toggle>

10.7 The setfocus Element

This XForms Action begins by invoking the deferred update behavior. This action then dispatches an xforms-focus event (4.3.7 The xforms-focus Event) to the element identified by attribute control or child element control.

Common Attributes: Common, Events, Action Common

Special Attributes:

control

Author-optional reference to a form control. The form control is specified by this attribute or by the child element control.

The identity of the element to which the setfocus action dispatches xforms-focus is given by the control attribute or the control element. If no such element contains the given identifier, then this action has no effect.

<setfocus>
	<control value="concat('input_', ../paymentType)"/>
</setfocus>

10.8 The dispatch Element

This action dispatches an XML Event to a specific target element. Two kinds of event can be dispatched:

1. Predefined XForms events (i.e., xforms-event-name), in which case the bubbles and cancelable attributes are ignored and the standard semantics as defined in 4 Processing Model apply.

2. An event created by the XForms author with no predefined XForms semantics and as such not handled by default by the XForms Processor.

Common Attributes: Common, Events, Action Common

Special Attributes:

name

Author-optional attribute for specifying the name of the event to dispatch.

targetid

Author-optional attribute for specifying the reference to the event target.

delay

Author-optional attribute that indicates the minimum number of milliseconds to delay dispatching of the event to the target. The default is the empty string, which indicates no delay.

bubbles

Author-optional attribute containing a boolean indicating if this event bubbles—as defined in [DOM2 Events]. The default value is true for a custom event. For predefined events, this attribute has no effect.

cancelable

Author-optional attribute containing a boolean indicating if this event is cancelable—as defined in [DOM2 Events]. The default value is true for a custom event. For predefined events, this attribute has no effect.

The event to be dispatched is given by the name attribute or the name child element. Due to the addition of the name element, the name attribute is not required, but either the name attribute or the name element must appear. If the event name is not specified or empty string, then this action has no effect.

The element to which the event is to be dispatched is identified by the targetid attribute or the targetid chlid element. Due to the addition of the targetid element, the targetid attribute is not required, but this action has no effect unless the target identifier is specified by the element or attribute. For backwards compatibility with documents created for earlier versions of the specification, the processor of the dispatch element may allow the attribute named target and the child element target to be used. The attribute and element named target provide exactly the same behaviors as the targetid attribute and element, except that the target attribute and element are ignored if the dispatch element also bears a targetid attribute or contains a targetid child element.

The event may be dispatched immediately or after a specified non-negative number of milliseconds of delay. The event delay is specified the delay attribute or by the child element delay. If the delay is not specified or if the given value does not conform to xsd:nonNegativeInteger, then the event is dispatched immediately as the result of the dispatch action. Otherwise, the specified event is added to the delayed event queue unless an event with the same name and target element already exists on the delayed event queue. The dispatch action has no effect if the event delay is a non-negative integer and the specified event is already in the delayed event queue.

If a run-time element is destroyed, then any delayed events targeted at that element are removed from the delayed event queue. A run-time element may be destroyed for a number of reasons, including shutdown of the form or removal of form controls associated by a repeat with an instance data node that is destroyed.

As soon as possible after the specified delay in milliseconds has elapsed, the event is removed from the delayed event queue and then dispatched. In the same manner used to handle user-generated events or the completion of an asynchronous submission, the dispatch and processing of delayed events is done without interrupting the processing of another event and its event handlers.

10.9 The rebuild Element

This action causes the default processing of xforms-rebuild to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-rebuild event). This action results in the XForms Processor rebuilding any internal data structures used to track computational dependencies among instance data nodes —see 4.3.1 The xforms-rebuild Event.

Common Attributes: Common, Events, Action Common

Special Attributes:

model

Author-optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the model associated with the in-scope evaluation context node.

10.10 The recalculate Element

This action causes the default processing of xforms-recalculate to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-recalculate event). As a result, instance data nodes whose values need to be recalculated are updated as specified in the processing model—see 4.3.2 The xforms-recalculate Event.

Common Attributes: Common, Events, Action Common

Special Attributes:

model

Author-optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the model associated with the in-scope evaluation context node.

10.11 The revalidate Element

This action causes the default processing of xforms-revalidate to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-revalidate event). This results in the instance data being revalidated as specified by the processing model—see 4.3.3 The xforms-revalidate Event.

Common Attributes: Common, Events, Action Common

Special Attributes:

model

Author-optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the model associated with the in-scope evaluation context node.

10.12 The refresh Element

This action causes the default processing of xforms-refresh to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-refresh event). This action results in the XForms user interface being refreshed, and the presentation of user interface controls being updated to reflect the state of the underlying instance data—see 4.3.4 The xforms-refresh Event.

Common Attributes: Common, Events, Action Common

Special Attributes:

model

Author-optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the model associated with the in-scope evaluation context node.

10.13 The reset Element

This action initiates reset processing by dispatching an xforms-reset event to the specified model. Processing of event xforms-reset is defined in the processing model—see 4.3.5 The xforms-reset Event.

Common Attributes: Common, Events, Action Common

Special Attributes:

model

Author-optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the model associated with the in-scope evaluation context node.

10.14 The load Element

This action traverses the specified link.

Common Attributes: Common, Events, Action Common, Single-Node Binding (author-optional)

Special Attributes:

resource

Author-optional attribute. Link to an external resource to load.

show

Author-optional link behavior specifier. The allowed values are "replace" and "new". If this attribute is missing, a default value of "replace" is assumed.

The URI specifying the link to traverse may be pointed to by the Single Node Binding attributes, if given, or by the resource attribute or the name child element. Individually, the Single Node Binding, resource element and resource attribute are not required. If none are given, the action has no effect. If the Single Node Binding is present and does not select an instance data node, then this action has no effect. If the Single Node Binding is given in addition to one of the resource attribute or resource element, then the action has no effect.

The URI obtained in this manner is treated as a link to an external resource, defined as an [XLink 1.0] link between the load element and the remote resource indicated. No XLink actuate value is defined, since control of actuation is defined by XML Events. The XLink show value depends on the show attribute.

The link indidicated by the URI obtained above is traversed. If the link traversal fails, then an implementation-specific means of conveying the link traversal failure occurs. Otherwise, processing for the document (or portion of the document) reached by traversing the link is specified by the show attribute. The following are the possible values for the show attribute and the corresponding processing behaviors:

new

The document is loaded into a new presentation context, e.g., a new window. Form processing in the original window continues.

replace

The document is loaded into the current window. Form processing is interrupted, exactly as if the user had manually requested navigating to a new document.

10.15 The send Element

This action initiates submit processing by dispatching an xforms-submit event. Processing of event xforms-submit is defined in the processing model—see 4.3.9 The xforms-submit Event.

Common Attributes: Common, Events, Action Common

Special Attributes:

submission

Author-optional attribute containing a reference to a submission element. If this attribute is given but does not identify a submission element, then the send action has no effect. If this attribute is omitted, then the first submission in document order from the model associated with the in-scope evaluation context is used.

10.16 The message Element

This action encapsulates a message to be displayed to the to the user.

Common Attributes: Common, Events, Action Common, Single Node Binding (author-optional)

Special Attributes:

level

Author-optional attribute containing a message level identifier, one of ("ephemeral"|"modeless"|"modal"|QNameButNotNCName). The default is "modal" if the attribute is not specified. This specification does not define behavior for QNameButNotNCName values.

The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: single node binding attributes, inline text.

The user interface for the message action is considered to be created at the time the action occurs. If the message is obtained from the inline content of the message action, then the output of any output controls in the message content is determined based on the instance data available when the message action occurs. For example, the following example displays the message Hello, world! as the form starts up:

<model>
     <instance>
         <data xmlns="">
             <name>John</name>
         </data>
     </instance>
   
     <action ev:event="xforms-ready">
         <setvalue ref="name">world</setvalue>
         <message level="modal">Hello, <output ref="name"/>!</message>
  ...</action>
</model>

In this example, the message includes the latest user input even though other form controls not in the message action are not guaranteed to be updated until the end of the xforms-refresh event processing:

<input ref="birthday">
     <label>Enter birthday:</label>
     <message ev:event="xforms-invalid"><output ref="."/> isn't a valid birthday</message>
</input>

A graphical browser might render a modal message as follows:

<model>
  <message level="modal" ev:event="xforms-ready">This is not a drill!</message>
  ...
</model>

A modeless message is the foundation for displaying a help message, which a graphical browser might render as follows:

<secret ref="/login/password">
  <label>Password</label>
  <help>Have you forgotten your password? Simply call 1-900-555-1212 and have
        a major credit card handy.</help>
</secret>

An ephemeral message is the foundation for displaying a hint message, which a graphical browser might render as follows:

<input ref="po/address/street1">
  <label>Street</label>
  <hint>Please enter the number and street name</hint>
</input>

10.17 Conditional Execution of XForms Actions

The if attribute can be added to any XForms action. It contains an [XPath 1.0] expression that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is converted to a boolean as if converted with the boolean() function defined by the [XPath 1.0] specification. If the converted result of the expression evaluates to false, then the action is not performed. If the converted result is true, then the action is performed.

If this attribute is applied to an XForms action element and the converted result of evaluation is false, then all of the actions within the action element are omitted from the execution of the XForms action sequence that invoked the action element. If the result is true, then the contained actions are performed according to the normal processing rules such as deferred update behavior and applicability of conditional and iterative attributes.

...
<input ref="areaCode" id="AreaCodeControl" incremental="true">
	<label>Area Code</label>
	<setfocus ev:event="xforms-value-changed" control="ExchangeControl" if="string-length(.)=3 and . > 0"/>
</input>
<input ref="exchange" id="ExchangeControl" incremental="true">
	<label>Exchange</label>
	<setfocus ev:event="xforms-value-changed" control="LocalControl" if="string-length(.)=3 and . > 0"/>
</input>
<input ref="local" id="LocalControl" incremental="true">
	<label>Local</label>
	<setfocus ev:event="xforms-value-changed" control="ExtensionControl" if="string-length(.)=4 and . > 0"/>
</input>
...

...
<trigger id="InsertControl">
	<label>Insert Row</label>
	<action ev:event="DOMActivate">
		<insert context="purchaseOrder/lines" nodeset="line" 
				at="index('PurchaseOrderRepeat')" origin="instance('prototype')"/>
		<setfocus control="PurchaseOrderRepeat"/>
	</action>
</trigger>
<repeat nodeset="purchaseOrder/lines/line" id="PurchaseOrderRepeat">
	...
	<trigger>
		<label>Delete Row</label>
		<action ev:event="DOMActivate">
			<setfocus control="InsertControl" if="last()=1"/>
			<delete  nodeset="../line" at="index('PurchaseOrderRepeat')"/>
		</action>
	</trigger>
	...
</repeat>

10.18 Iteration of XForms Actions

The while attribute can be added to any XForms action. It contains an [XPath 1.0] expression that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is converted to a boolean as if converted with the boolean() function defined by the [XPath 1.0] specification. If the converted result of the expression is true, then the XForms action is performed and then the expression is re-evaluated. The XForms action is executed repeatedly until the converted result of the expression evaluates to false.

If this attribute is applied to an XForms action element, then the sequence of XForms actions in its content are executed repeatedly once for each time the immediately preceding evaluation of the expression yields a result of true.

When XForms actions are iteratively executed, they are still subject to the normal action processing rules such as deferred update and applicability of conditional and iterative attributes.

An XForms action may be executed zero times due to this attribute. Furthermore, if an action bears this attribute and the if attribute, then the expressions of both attributes must evaluate to true before each iterative execution of the action.

<trigger>
   <label>Get Sum</label>
   <action ev:event="DOMActivate">
      <setvalue ref="instance('temps')/counter" value="1"/>
      <setvalue ref="instance('temps')/accumulator" value="0"/>
      <action while="instance('temps')/counter <= count(/some/nodes)">
         <setvalue ref="instance('temps')/accumulator" 
                   value=". + instance('default')/some/nodes[number(instance('temps')/counter)]"
                   if="boolean-from-string(/some/nodes[number(instance('temps')/counter)]/@selected)"/>
         <setvalue ref="instance('temps')/counter" value=". + 1"/>
      </action>
   </action>
</trigger>

11.1 The submission Element

The submission element represents declarative instructions on what to submit, and how.

Below is a more detailed decription of each attribute whose name and datatype information appears above.

Common Attributes: Common

Special Attributes:

resource

Attribute indicating the destination URI for submitting instance data. This attribute is not author-optional unless the destination URI is provided by the resource element, which can dynamically specify the URI based on instance data, or the action attribute. This attribute should be used in place of the action attribute. Behavior of relative URIs in links is determined by the host language, although [XML Base] processing is strongly recommended.

action

Deprecated author-optional attribute indicating the destination URI for submitting instance data. Behavior of relative URIs in links is determined by the host language, although [XML Base] processing is strongly recommended. Due to the addition of the resource attribute, this attribute is deprecated and optional. However, the destination URI must be specified by this attribute or by either the resource attribute or the resource element.

ref

Author-optional selector binding expression enabling submission of a portion of the instance data. The selected node, and all descendants, are selected for submission. The default value is "/".

bind

Author-optional reference to a bind element. When present, the binding reference on this attribute is used in preference to any binding reference from the ref attribute.

mode

Author-optional attribute defaulting to "asynchronous" and with legal values of "synchronous" and "asynchronous". This attribute controls whether or not the submission response processing is performed as part of the default processing of event xforms-submit. An asynchronous submission can complete default processing for this event before the submission response is received; in this case, submission response is processed once it is completely received asynchronously. For a "synchronous" submission, the submission response is received and processed during the default processing of event xforms-submit.

method

Author-optional attribute specifying the protocol operation to be used to transmit the serialized instance data. There is no default value because either the attribute method or the element method must be specified. See Section 11.9 Submission Options for information on how this attribute affects the default serialization of instance data and the HTTP method [RFC 2616].

validate

Author-optional boolean attribute that indicates whether or not the data validation checks of the submission are performed. The default value is "false" if the value of serialization is "none" and "true" otherwise.

relevant

Author-optional boolean attribute that indicates whether or not the relevance pruning of the submission is performed. The default value is "false" if the value of serialization is "none" and "true" otherwise.

serialization

Author-optional attribute that controls how and whether to serialize instance data as part of the submission. The default value of this attribute is based on the submission method as described in Section 11.9 Submission Options. If the attribute value is "none", then instance data is not serialized as part of the submission. This can be useful for requests that either require no data or that have the data already gathered in the URI.

Note:

Setting serialization to "none" will also have the default effect of preventing relevance pruning and validation. However, the author is free to override this by setting relevant and/or validate attributes to "true".

version

Author-optional attribute specifying the version of XML to be serialized. The default is "1.0".

indent

Author-optional attribute specifying whether the serializer should add extra white space nodes for readability. The default is "false".

mediatype

Author-optional attribute specifying the mediatype for XML serialization of instance data. Authors should ensure that the type specified is compatible with the data being submitted, such as application/xml for posted XML data. The default is "application/xml".

Note:

This attribute does not affect serialization and cannot be used to override the serialization attribute. It is only used to provide additional information about the submission data serialization when the serialization is application/xml. For example, this attribute could be used to indicate that the content type of the XML serialization is text/xml.

encoding

Author-optional attribute specifying an encoding for serialization. The default is "UTF-8".

omit-xml-declaration

Author-optional attribute specifying whether to omit the XML declaration on the serialized instance data. The default value is "false".

standalone

Author-optional attribute specifying whether to include a standalone declaration in the serialized XML.If the omit-xml-declaration attribute has the value true, then this attribute is ignored. Otherwise, if this attribute is omitted, then the XML declaration does not include a standalone document declaration, and if this attribute is specified, then the XML declaration includes a standalone document declaration with the same value as this attribute.

cdata-section-elements

Author-optional attribute specifying element names to be serialized with CDATA sections. The default is empty string.

replace

Author-optional attribute specifying how the information returned after submit should be applied. In the absence of this attribute, "all" is assumed. The legal values are "all", "instance", "text" and "none".

instance

Author-optional attribute specifying the instance to replace when the replace attribute value is "instance". When the attribute is absent, then the default is the instance that contains the submission data. An xforms-binding-exception (4.5.1 The xforms-binding-exception Event) occurs if this attribute does not indicate an instance in the same model as the submission.

targetref

Author-optional attribute containing an XPath expression that indicates the target node for data replacement. The in-scope evaluation context of the submission element is used to evaluate the expression. If replace is "instance", then the target node is replaced by the submission result. If replace is "text", then the content of the target node is replaced by the submission result. For other values of the replace attribute, this attribute is ignored. By default, the target node is the document element of the instance indicated by the instance attribute.

separator

Author-optional attribute specifying the separator character between name/value pairs in urlencoding. The default value is '&'. To express the default, character entity encoding is used: separator='&'.

includenamespaceprefixes

Author-optional attribute providing control over namespace serialization. If absent, all namespace nodes present in the instance data are considered for serialization. If present, specifies list of namespace prefixes to consider for serialization, in addition to those visibly utilized. As in [Exc-C14N], the special value #default specifies the default namespace.

The following examples show how various options on element submission can affect serialization as application/xml. Given the following XForms fragment:

<xforms:model xmlns:xforms="http://www.w3.org/2002/xforms"
              xmlns:my="http://ns.example.org/2003">
  <xforms:instance>
    <qname xmlns="">my:sample</qname>
  </xforms:instance>
  <xforms:submission method="post" resource="..."/>
</xforms:model>

Note that the includenamespaceprefixes attribute is not present, which causes all namespace nodes to be serialized, resulting in the following serialized instance data:

<qname xmlns:xforms="http://www.w3.org/2002/xforms"
       xmlns:my="http://ns.example.org/2003">my:sample</qname>

In particular, note that the XForms namespace has been serialized. To prevent this example from including the unneeded XForms namespace while maintaining the needed my prefix, includenamespaceprefixes="my" must be added to the submission element. When this attribute is present, the author takes responsibility to list all namespace prefixes not visibly utilized by the submitted instance data.

The following attributes correspond (in spelling, processing, and default values) to attributes on the output element of [XSLT 1.0], with the exception of using xsd:boolean to replace "yes"|"no":

version
indent
encoding
omit-xml-declaration
cdata-section-elements

The table below provides an overview of the child elements of the XForms submission element, including their attributes and content models. Elements defined in the XForms Actions module are also allowed in the content model of submission.

11.2 The xforms-submit Event

Target: submission

Bubbles: Yes

Cancelable: Yes

Context Info: None

Under no circumstances can more than a single concurrent submit process be under way for a particular XForms submission. From the start of the default action of xforms-submit for a submission, until immediately before xforms-submit-done or xforms-submit-error is dispatched to that submission, the default action for subsequent xforms-submit events dispatched to that submission is to dispatch xforms-submit-error to that submission with context information containing an error-type of submission-in-progress.

Otherwise, the default action for this event results in the following steps:

1. The data model is updated based on some of the flags defined for deferred updates.. Specifically, if the deferred update rebuild flag is set for the model containing this submission, then the rebuild operation is performed without dispatching an event to invoke the operation. Then, if the deferred update recalculate flag is set for the model containing this submission, then the recalculate operation is performed without dispatching an event to invoke the operation. This sequence of operations affects the deferred update behavior by clearing the deferred update flags associated with the operations performed.

2. If the binding attributes of submission indicate an empty nodeset or a node other than an element or an instance document root node, then submission processing is stopped after dispatching event xforms-submit-error with context information containing an error-type of no-data. Otherwise, the binding attributes of submission indicate a node of instance data.

3. The indicated node and all nodes for which it is an ancestor are selected. If the attribute relevant is true, whether by default or declaration, then any selected node which is not relevant as defined in 6.1.4 The relevant Property is deselected (pruned). If all instance nodes are deselected, then submission processing is stopped after dispatching event xforms-submit-error with context information containing an error-type of no-data.

4. If the attribute validate is true,whether by default or declaration, then all selected instance data nodes are checked for validity according to the definition in 4.3.3 The xforms-revalidate Event (no notification events are marked for dispatching due to this operation). Any selected instance data node that is found to be invalid stops submission processing after dispatching event xforms-submit-error with context information containing an error-type of validation-error.

5. The submission method is determined.

6. The submission resource is determined. If the resource is not specified, then submission processing stops after dispatching even xforms-submit-error with context information containing an error-type of resource-error.

7. If the serialization attribute value is "none", then the submission data serialization is the empty string. Otherwise, the submission data serialization is determined as follows. The event xforms-submit-serialize is dispatched. If the submission-body property of the event is changed from the initial value of empty string, then the content of the submission-body property string is used as the submission data serialization. Otherwise, the submission data serialization consists of a serialization of the selected instance data according to the rules stated in 11.9 Submission Options.

8. The submission headers are determined using the header entries produced by the header element(s) in the submission and the mediatype attribute or its default.

9. The submission is performed based on the submission headers, submission method, submission resource, and submission data serialization. The exact rules of submission are based on the URI scheme and the submission method, as defined in 11.9 Submission Options.

If the mode of the submission is asynchronous, then default processing for this event ends after the above steps, and submission processing is resumed once the response from the submission is returned. In the same manner used to handle user-generated events or the dispatch and processing of delayed events, the processing of the asynchronous submission response is done without interrupting the processing of any other event and its event handlers. If the mode of the submission is synchronous, then the XForms processor suspends user interaction with all form controls of the document and action processing is blocked within the default processing for this event until the response from the submission is returned.

The response returned from the submission is applied as follows:

• For a success response including a body, when the value of the replace attribute on element submission is "all", the event xforms-submit-done may be dispatched with appropriate context information, and submit processing concludes with entire containing document being replaced with the returned body.

• For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023]), when the value of the replace attribute on element submission is "instance", the response is parsed as XML. If the parse fails, then submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of parse-error. However, if the XML parse succeeds, then instance data replacement is performed according to the rules specified in 11.10 Replacing Data with the Submission Response. This operation may fail for a number of reasons, including if processing of the targetref attribute yields a readonly node (if replace="text") or a node that either has a readonly parent or is not an element (if replace="instance"). In this case, submission ends after dispatching event xforms-submit-error with appropriate context information, including an error-type of target-error. Otherwise, the instance data replacement succeeds. Submission processing then concludes after dispatching xforms-submit-done with appropriate context information.

• For a success response including a body of a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023]), when the value of the replace attribute on element submission is "instance", nothing in the document is replaced and submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error.

• For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023]) or a text media type (as defined by a content type of text/*), when the value of the replace attribute on element submission is "text", the response is encoded as text. Then, the content replacement is performed according to the rules specified in 11.10 Replacing Data with the Submission Response. If the processing of the targetref attribute (including its default) fails, then the submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of target-error. Otherwise, submission processing then concludes after dispatching xforms-submit-done with appropriate context information.

• For a success response including a body that is both a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023]) and a non-text type (i.e. with a content type not matching text/*), when the value of the replace attribute on element submission is "text", nothing in the document is replaced and submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error.

• For a success response including a body, when the value of the replace attribute on element submission is "none", submission processing concludes after dispatching xforms-submit-done with appropriate context information.

• For a success response not including a body, submission processing concludes after dispatching xforms-submit-done with appropriate context information.

• Behaviors of other possible values for attribute replace are not defined in this specification.

• For an error response, when the value of the replace attribute on element submission is "all", either the document is replaced with an implementation-specific indication of an error or submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error.

• For an error response, when the value of the replace attribute on element submission is not "all", nothing in the document is replaced, and submission processing concludes after dispatching xforms-submit-error with appropriate context information, including an error-type of resource-error.

In addition to initiating a submission with its default processing, XForms actions can also provide handlers for the xforms-submit event to peform tasks such as data preparation.

Example:

<submission resource="http://example.com/searchDoctors" method="post" ref="instance('doctorSearchParams')"
            replace="instance" targetref="instance('doctorList')" > 
    <action ev:event="xforms-submit"> 
        <setvalue ref="diagnosis" value="instance('patientRecord')/malady"/> 
        <setvalue ref="city" value="instance('patientRecord')/city"/> 
    </action> 
</submission>

11.3 The xforms-submit-serialize Event

Dispatched at the beginning of submission serialization (see 11.2 The xforms-submit Event).

Target: submission

Bubbles: Yes

Cancelable: No

Context Info:

Default Action: If the event context submission-body property string is empty, then no operation is performed so that the submission will use the normal serialization data (see 11.2 The xforms-submit Event). Otherwise, if the event context submission-body property string is non-empty, then the serialization data for the submission is set to be the content of the submission-body string.

Example:

<submission resource="http://example.com/greeter" method="post" mediatype="text/plain"> 
    <setvalue ev:event="xforms-submit-serialize" ref="event('submission-body')" value="my/text"/> 
</submission>

11.4 The xforms-submit-done Event

Dispatched as an indication of: successful completion of a submission process

Target: submission

Bubbles: Yes

Cancelable: No

Context Info:

Default Action: None; notification event only.

Example:

<submission resource="https://example.com/getRecord" method="post" replace="instance" instance="record"> 
    <send ev:event="xforms-submit-done" submission="chargeForRecord"/> 
</submission>
<submission id="chargeForRecord" resource="https://example.com/chargeForRecord" method="get" serialization="none" replace="none"/>

11.5 The xforms-submit-error Event

Dispatched as an indication of: failure of a submission process

Target: submission

Bubbles: Yes

Cancelable: No

Context Info:

Default Action: None; notification event only.

Example:

<submission resource="https://example.com/getRecord" method="post" replace="instance" instance="record"> 
    <message ev:event="xforms-submit-error">A submission error (<output value="event('error-type')"/>) occurred.</message>
</submission>

11.6 The Submission Resource

The submission resource is the URI for the submission. It is of type xsd:anyURI.

In XForms 1.0, the URI for submission was provided by the action attribute. For consistency, form authors should now use the attribute resource of type xsd:anyURI, which deprecates the action attribute. If both action and resource are present, then the resource attribute takes precedence.

The resource element provides the submission URI, overriding the resource attribute and the action attribute. If a submission has more than one resource child element, the first resource element child must be selected for use. Individually, the resource element, the resource attribute and the action attribute are not required. However, one of the three is mandatory as there is no default submission resource.

<submission method="post"> 
    <resource value="instance('params')/anyURI"/> 
</submission>

11.7 The Submission Method

The submission method indicates the submission protocol operation to be performed.

The submission method may be specified by the method attribute. The submission element can have a child element named method, which overrides the submission method setting obtained from the method attribute if both are specified. If more than one method element is given, the first occurrence in document order must be selected for use. Individually, the method element and the method attribute are not required. However, one of the two is mandatory as there is no default submission method.

11.8 The header Element

The header element can be used to contribute information to the preamble of a submission in a manner appropriate to the protocol. The submission element can contain zero or more header child elements. Each produces zero or more header entries containing a name, a value, and a combination. The entries are provided to the submission protocol in the specified order. It is the responsibility of the submission protocol implementation to combine the entries and to serialize the result into submission protocol headers. Accordingly, entries may be re-ordered, combined, or otherwise altered in accordance with the specific protocol implementation requirements.

Common Attributes: None

Special Attributes:

nodeset

Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. One or more header entries are generated for each node selected by this attribute.

combine

Author-optional attribute defaulting to "append" and with legal values of "append", "prepend", and "replace". This attribute controls the method of combination for entries produced by this element header with other entries produced by other header elements. This attribute and its default also provide information for the protocol implementation, which may use some or all of the information to combine XForms submission headers with headers provided by the user agent.

Content: (name, value+) | (value+, name)

If the header element does not contain a nodeset attribute, then one header entry is created for each value element. If the header element contains a nodeset attribute, then for each selected node, one header entry is created for each value element. The name and value of the header entry are obtained from the required child elements name (11.8.1 The name Element) and value (11.8.2 The value Element). If the name obtained from the name element is the empty string, then the header entry is omitted.

The header entry order is determined as follows:

1. document order of header elements

2. node order of nodes in nodeset attribute

3. document order of value elements

The application of this order information to header serialization is determined by the submission protocol.

If a header element defines the Content-type header, then this setting overrides a Content-type set by the mediatype attribute.

In the case of a multipart submission, the header entries are combined with those for the first part of the submission.

Example:

<submission id="loadConcepts" 
            resource="http://example.com/taxonomy/concepts" method="get" 
            ref="instance('conceptsList')" replace="instance"> 
  <header combine="replace"> 
    <name>Accept</name>
    <value>application/sparql-results+xml</value> 
  </header> 
</submission>

11.9 Submission Options

The XForms Model specifies a submission element containing the following attributes and child elements that affect serialization and submission. This section summarizes the behaviors for the allowable values of these attributes and child elements, and presents subsections that define the behavior for submission and serialization.

For the submission protocol obtained from the URI scheme in the submission resource, XForms normatively defines a binding to HTTP/1.1 [RFC 2616].

The submission method determines the default data serialization format, and both the submission method and the URI scheme in the submission resource determine the submission protocol operation, according to the following table:

<submission resource="http://example.com/search" method="get"/>

<submission resource="file:data.xml" method="get" serialization="none" replace="instance" instance="data" />

<submission resource="https://example.com/jsp/orders" method="post" ref="/purchaseOrder" />

<submission resource="http://example.com/login" method="urlencoded-post"/>

<submission resource="file:data.xml" ref="instance('data')" method="put" validate="false" relevant="false" replace="none" />

<submission method="multipart-post" resource="http://example.com/photo" />

POST /photo HTTP/1.0
Host: example.com
Content-Type: multipart/related; boundary=f93dcbA3; type=application/xml; start="<980119.X53GGT@example.com>"
Content-Length: xxx

--f93dcbA3
Content-Type: application/xml; charset=UTF-8
Content-ID: <980119.X53GGT@example.com>

<?xml version="1.0"?>
<uploadDocument>
  <title>My Proposal</title>
  <author>E. X. Ample</author>
  <summary>A proposal for a new project.</summary>
  <notes image="cid:980119.X17AXM@example.com">(see handwritten region)</notes>
  <keywords>project proposal funding</keywords>
  <readonly>false</readonly>
  <filename>image.png</filename>
  <content>cid:980119.X25MNC@example.com</content>
</uploadDocument>
--f93dcbA3
Content-Type: image/png
Content-Transfer-Encoding: binary
Content-ID: <980119.X25MNC@example.com>

...Binary data here...
--f93dcbA3
Content-Type: image/png
Content-Transfer-Encoding: binary
Content-ID: <980119.X17AXM@example.com>

...Binary data here...
--f93dcbA3--

<submission method="form-data-post" resource="http://example.com/photo" />

POST /photo HTTP/1.0
Host: example.com
Content-Type: multipart/form-data; boundary=AaB03x
Content-Length: xxx

--AaB03x
Content-Disposition: form-data; name="document"; filename="b.txt"
Content-Type: text/plain; charset=iso-8859-1
This is a file.
It has two lines.
--AaB03x
Content-Disposition: form-data; name="title"
A File
--AaB03x
Content-Disposition: form-data; name="summary"
This is my file
file test
--AaB03x--

<PersonName title="Mr">
  <GivenName>René</GivenName>
</PersonName>

11.10 Replacing Data with the Submission Response

The submission element allows an author-optional attribute named targetref. The attribute value is interpreted as a binding expression to which the first node rule is applied to obtain a replacement target node for the submission response. This attribute is ignored unless the value of the replace attribute is "instance" or "text".

For backwards compatibility with documents created for earlier versions of the specification, the processor of the submission element may allow the author-optional attribute named target to be used. The target attribute provides exactly the same behaviors as the targetref attribute except that the target attribute is ignored if the submission element also bears a targetref attribute.

The default replacement target node is the document element node of the instance identified by the instance attribute, which is equal to the default instance of the model if not specified. The evaluation context for this attribute is the in-scope evaluation context for the submission element, except the context node is modified to be the document element of the instance identified by the instance attribute if it is specified.

This attribute is evaluated only once a successful submission response has been received and if the replace attribute value is "instance" or "text". The first node rule is applied to the result.

The processing of the targetref attribute (and its default) is considered to have failed if the result is any of the following:

• an empty nodeset

• a readonly node, if replace="text"

• a non-element, if replace="instance"

• a node whose parent is readonly, if replace="instance"

If the processing of the targetref attribute fails, then submission processing ends after dispatching the event xforms-submit-error with an error-type of target-error.

If the replace attribute contains the value "text" and the submission response conforms to an XML mediatype (as defined by the content type specifiers in [RFC 3023]) or a text media type (as defined by a content type specifier of text/*), then the response data is encoded as text and replaces the content of the replacement target node.

If the replace attribute contains the value "instance" and the submission response conforms to an XML mediatype (as defined by the content type specifiers in [RFC 3023]) and the XML parse of the submission response succeeds, then the XML obtained from the submission response is used to replace the target node. The XML in the response may have comment and processing instruction nodes before and after the document element. These nodes are discarded if the replacement target node is not the document element of an instance. Otherwise, those processing instructions and comments replace any processing instructions and comments that previously appeared outside of the document element of the instance being replaced.

In the case of text replacement of the content of the replacement target node, the replacement is performed by the XForms Action setvalue (10.2 The setvalue Element). In the case of instance node replacement, the replacement is performed by an XForms action that performs some combination of node insertion and deletion operations that are performed by the insert action (10.3 The insert Element) and the delete action (10.4 The delete Element). If the submission has a mode of "asynchronous", then the text replacement action or the instance node replacement action is an outermost action handler, so the deferred update behavior occurs at the end of the action. If the mode is "synchronous", then the text replacement action or the instance node replacement action is not outermost since occurs during the default processing of xforms-submit, so the appropriate deferred update flags are set based on whether the action was a setvalue or whether it performed a series of insert and delete actions.

Examples:

<submission resource="http://example.com/jsp/prefill" method="post" ref="name" replace="instance" targetref="address"/>

<submission resource="http://example.com/postalCodeSearch" method="get" ref="address" replace="text" targetref="address/postalCode"/>

<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()"/>

  <submission id="S1" targetref="my:name" replace="instance" method="post" resource="..."/>  
  <submission id="S2" targetref="my:name/my:first-name" replace="instance" method="post" resource="..."/>

  <submission id="S3" targetref="my:name/my:first-name" replace="text" method="post" resource="..."/>  
  <submission id="S4" targetref="my:address/my:street" replace="text" method="post" resource="..."/>
</model>

11.11 Integration with SOAP

This section describes the integration of XForms submission with [SOAP 1.1] and [SOAP 1.2]

		    
<xforms:model xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://www.webservice.net">
   <xforms:instance id="data">
       <data xmlns="">
           <city>Victoria</city>
           <country>Canada</country>
           <weather>Mostly sunny and cool. High 12C. Low 3C.</weather>
       </data>
   </xforms:instance>

   <xforms:instance id="GetWeatherSoapIn">
	  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
		 <soap:Body>
			<GetWeather xmlns="http://www.webservice.net">
			   <CityName>Victoria</CityName>
			   <CountryName>Canada</CountryName>
			</GetWeather>
		 </soap:Body>
	  </soap:Envelope>
   </xforms:instance>
   <xforms:instance id="GetWeatherSoapOut">
	  <soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
		 <soap:Body>
			<GetWeatherResponse xmlns="http://www.webservice.net">
			   <GetWeatherResult>Mostly sunny and cool. High 12C. Low 3C.</GetWeatherResult>
			</GetWeatherResponse>
		 </soap:Body>
	  </soap:Envelope>
   </xforms:instance>
   
   <xforms:submission id="GetWeather" resource="http://www.webservice.net/getweather.asmx" method="post"
        ref="instance('GetWeatherSoapIn')" mediatype="application/soap+xml; action=http://www.webservice.net/GetWeather" 
        replace="instance" instance="GetWeatherSoapOut">
        <xforms:action ev:event="xforms-submit">
            <xforms:setvalue ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CityName" 
                             value="instance('data')/city"/>
            <xforms:setvalue ref="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeather/tns:CountryName" 
                             value="instance('data')/country"/>
        </xforms:action>
        <xforms:action ev:event="xforms-submit-done">
            <xforms:setvalue ref="instance('data')/weather" 
                             value="instance('GetWeatherSoapOut')/soap:Body/tns:GetWeatherResponse/tns:GetWeatherResult"/>
        </xforms:action>
   </xforms:submission>
</xforms:model>

<xforms:input ref="city">
   <xforms:label>City </xforms:label>
   <xforms:send ev:event="xforms-value-changed" submission="GetWeather"/>
</xforms:input>
<xforms:input ref="country">
   <xforms:label>Country </xforms:label>
   <xforms:send ev:event="xforms-value-changed" submission="GetWeather"/>
</xforms:input>
<xforms:output ref="weather">
   <xforms:label>The weather forecast is </xforms:label>
</xforms:output>

<wsdl:definitions xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
     xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" 
     xmlns:tns="http://www.webservice.net" targetNamespace="http://www.webservice.net">
  <wsdl:types>
    <xs:schema elementFormDefault="qualified" targetNamespace="http://www.webservice.net">
      <xs:element name="GetWeather">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="0" maxOccurs="1" name="CityName" type="xs:string" />
            <xs:element minOccurs="0" maxOccurs="1" name="CountryName" type="xs:string" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      <xs:element name="GetWeatherResponse">
        <xs:complexType>
          <xs:sequence>
            <xs:element minOccurs="0" maxOccurs="1" name="GetWeatherResult" type="xs:string" />
          </xs:sequence>
        </xs:complexType>
      </xs:element>
      ...
  </wsdl:types>
  
  <wsdl:message name="GetWeatherSoapIn">
    <wsdl:part name="parameters" element="tns:GetWeather" />
  </wsdl:message>
  <wsdl:message name="GetWeatherSoapOut">
    <wsdl:part name="parameters" element="tns:GetWeatherResponse" />
  </wsdl:message>
  ...
  <wsdl:portType name="GetWeatherSoap">
    <wsdl:operation name="GetWeather">
      <wsdl:input message="tns:GetWeatherSoapIn" />
      <wsdl:output message="tns:GetWeatherSoapOut" />
    </wsdl:operation>
    ...
  </wsdl:portType>
  ...
  <wsdl:binding name="GetWeatherSoap" type="tns:GetWeatherSoap">
    <soap:binding transport="http://schemas.xmlsoap.org/soap/http" style="document" />
    <wsdl:operation name="GetWeather">
      <soap:operation soapAction="http://www.webservice.net/GetWeather" style="document" />
      <wsdl:input>
        <soap:body use="literal" />
      </wsdl:input>
      <wsdl:output>
        <soap:body use="literal" />
      </wsdl:output>
    </wsdl:operation>
    ...
  </wsdl:binding>

  <wsdl:service name="GetWeatherService">
    <wsdl:port name="GetWeatherSoap" binding="tns:GetWeatherSoap">
      <soap:address location="http://www.webservice.net/getweather.asmx" />
    </wsdl:port>
    ...
  </wsdl:service>
</wsdl:definitions>