2 Introduction to XForms
XForms has been designed on the basis of several years' experience with HTML forms. HTML forms have formed the backbone of the e-commerce revolution, and having shown their worth, have also indicated numerous ways they could be improved.
The primary difference when comparing XForms with HTML forms, apart from XForms being in XML, is the separation of the data being collected from the markup of the controls collecting the individual values. By doing this, it not only makes XForms more tractable by making it clear what is being submitted where, it also eases reuse of forms, since the underlying essential part of a Form is no longer irretrievably bound to the page it is used in.
A second major difference is that XForms, while designed to be integrated into XHTML, is no longer restricted only to be a part of that language, but may be integrated into any suitable markup language.
XForms has striven to improve authoring, reuse, internationalization, accessibility, usability, and device independence. Here is a summary of the primary benefits of using XForms:
- Strong typing
Submitted data is strongly typed and can be checked using off-the-shelf tools. This speeds up form filling since it reduces the need for round trips to the server for validation.
- XML submission
This obviates the need for custom server-side logic to marshal the submitted data to the application back-end. The received XML instance document can be directly validated and processed by the application back-end.
- Existing schema re-use
This obviates duplication, and ensures that updating the validation rules as a result of a change in the underlying business logic does not require re-authoring validation constraints within the XForms application.
- External schema augmentation
This enables the XForms author to go beyond the basic set of constraints available from the back-end. Providing such additional constraints as part of the XForms Model enhances the overall usability of the resulting Web application.
- Internationalization
Using XML 1.0 for instance data ensures that the submitted data is internationalization ready.
- Enhanced accessibility
XForms separates content and presentation. User interface controls encapsulate all relevant metadata such as labels, thereby enhancing accessibility of the application when using different modalities. XForms user interface controls are generic and suited for device-independence.
- Multiple device support
The high-level nature of the user interface controls, and the consequent intent-based authoring of the user interface makes it possible to re-target the user interaction to different devices.
- Less use of scripting
By defining XML-based declarative event handlers that cover common use cases, the majority of XForms documents can be statically analyzed, reducing the need for imperative scripts for event handlers.
2.1 An Example
In the XForms approach, forms are comprised of a section that describes what the form does, called theXForms 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 XFormsmodel element, which in XHTML would typically be contained within thehead section:
<xforms:model> <xforms:instance> <ecommerce xmlns=""> <method/> <number/> <expiry/> </ecommerce> </xforms:instance> <xforms:submission action="http://example.com/submit" method="post" 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 theaction attribute.
XForms defines a device-neutral, platform-independent set ofform controls suitable for general-purpose use. The controls arebound to the XForms Model via the XForms binding mechanism, in this simple case using theref attribute on the controls. In XHTML, this markup would typically appear within thebody 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 enclosingform element, as in HTML. (See2.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 otherhost languages, since any form control markup may be used to bind to the model.
2.2 Providing XML Instance Data
TheXForms Processor can directly submit the data collected as XML. In the example, the submitted data would look like this:
Submitted Data
<ecommerce> <method>cc</method> <number>1235467789012345</number> <expiry>2001-08</expiry></ecommerce>
XForms processing keeps track of the state of the partially filled form through thisinstance data. Initial values for the instance data may be provided or left empty as in the example. Elementinstance essentially holds a skeleton XML document that gets updated as the user fills out the form. It gives the author full control on the structure of the submitted XML data, including namespace information. When the form is submitted, the instance data is serialized as an XML document. Here is an alternative version of the earlier example:
Model
<xforms:model> <xforms:instance> <payment method="cc" xmlns="http://commerce.example.com/payment"> <number/> <expiry/> </payment> </xforms:instance> <xforms:submission action="http://example.com/submit" method="post" includenamespaceprefixes="#default"/></xforms:model>
In this case the submitted data would look like this:
Submitted Data
<payment method="cc" xmlns="http://commerce.example.com/payment"> <number>1235467789012345</number> <expiry>2001-08</expiry></payment>
This design has features worth calling out:
There is complete flexibility in the structure of the XML instance data, including the use of attributes. Notice that XML namespaces are used, and that a wrapper element of the author's choosing contains the instance data.
Empty elementsnumber andexpiry 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 attributemethod. 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, theref attributes on the form controls need to be changed to point to the proper part of the instance data, usingbinding expressions:
Binding Form Controls to Instance Nodes withref
... 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 (heremy: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 andexpiry should accept only valid month/date combinations.
Furthermore, the credit card information form controls fornumber andexpiry are only relevant if the"cc" option is chosen formethod, 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 asrelevant. Such properties appear onbind elements, whileSchema constraints are expressed in an XML Schema fragment, either inline or external. For example:
Declarative Validation with Model Item Properties
... 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>Note:
In the above example, therelevant expression uses absolute XPath notation (beginning with/) because the evaluation context nodes forcomputed expressions are determined by thebinding expression (see7.2 Evaluation Context), and so any relative node path in the firstbindrelevant above would be relative to/my:payment/my:number
2.4 Multiple Forms per Document
XForms processing places no limits on the number of individual forms that can be placed in a singlecontaining document. When a single document contains multiple forms, each form needs a separatemodel element, each with anid attribute so that they can be referenced from elsewhere in the containing document.
In addition, form controls should specify whichmodel element contains the instance data to which they bind. This is accomplished through amodel attribute that is part of the binding attributes. If nomodel attribute is specified on the binding element, the nearest ancestor binding element'smodel 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.
Adding apoll model
<xforms:model> <xforms:instance> ...payment instance data... </xforms:instance> <xforms:submission action="http://example.com/submit" method="post"/></xforms:model> <xforms:model> <xforms:instance> <helpful/> </xforms:instance> <xforms:submission .../></xforms:model>
Additionally, the following markup would appear in the body section of the document:
Form Controls forpoll model
<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 ofmodel="poll", which identifies the instance. Note thatsubmit refers to thesubmission element by ID and does not require binding attributes.
More XForms examples can be found inH Complete XForms Examples.
7 XPath Expressions in XForms
XForms uses XPath to addressinstance data nodes in binding expressions, to express constraints, and to specify calculations.XPath expressions in XForms are based on[XPath 1.0]. A future version of XForms is expected to enable use of[XPath 2.0]. At the time of evaluation, an XPath expression must be syntactically correct. In addition, the namespaces the expression references must be in scope and the functions and variables it references must be defined. If any of these conditions is not satisfied, an exception (4.5.2 The xforms-compute-exception Event) is raised, except for binding expressions, which produce a different exception (4.5.1 The xforms-binding-exception Event).
7.1 XPath Datatypes
XPath datatypes are used only inbinding expressions andcomputed expressions. XForms uses XPath datatypesboolean,string,number, andnode-set. Additionally, the typeobject 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, thedefault model is the firstmodel in document order. Thedefault instance of anymodel is the first childinstance in document order within thatmodel. 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,
No variable bindings are in place.
The available function library is defined below in7.5 The XForms Function Library.
Any namespace declarations in scope for the attribute that defines the expression are applied to the expression.
The context node, position and size are determined according to rules described below.
Abinding element is any element that is explicitly allowed to have a binding expression attribute, and abound 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. Thein-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:
A binding element is "outermost" if the element has no ancestor binding elements. If an outermost binding element is contained by amodel, then the context node for the outermost binding element is the top-level document element node of the default instance of the containingmodel 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.
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:
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.
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.
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. Thedynamic 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.
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.
Once the context node of the in-scope evaluation context has been determined according to the rules above, if the binding element expresses amodel attribute that refers to amodel 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 referencedmodel, and the context position and size are changed to 1.
Thein-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 thesetindex action element is required to provide the context for evaluating theindex 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 thebind element to define computed expressions. If thebind element does not express a Node Set binding, then the in-scope evaluation context for model item property attributes of thebind is equal to the in-scope evaluation context for thebind. Otherwise, thebind 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 thebind element is the nearest ancestor binding element.
XPath expressions also appear in the special attributes of several other XForms elements, such as thevalue attribute onsetvalue andoutput, theat attribute ofinsert anddelete, or theindex attribute ofsetindex. 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, thegroup has a binding expression oflevel2/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. Theselect1 form control then inherits a context node from the parent group.
Sample XML Instance Data
<level1> <level2> <level3 attr="xyz"/> </level2></level1>
Binding Expression Context Nodes
<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 thebind attribute, then the resulting node or nodeset is obtained from the referencedbind element. Thenodeset attribute of abind element is evaluated using the in-scope evaluation of thebind element, not the in-scope evaluation context of an element that references it with abind attribute.
7.3 References, Dependencies, and Dynamic Dependencies
An XPath expressionreferences a node of instance data if the node is selected during the evaluation of the expression. A node is selected by matching an XPathNodeTest 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. Thereference list of an XPath expression is the set of instance nodes that it references.
Example of References and Non-References
Given the following default instance:
<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>
and the following XPath expression:
a[@attr='X']/b[@attr='X']/c
Both nodes nameda are referenced since both are matched by a NameTest. Theattr attribute in each elementa is referenced during the evaluation of the filter expression. The filter expression rejects the second elementa, but that element is still considered to have been referenced because it was selected for further processing during the expression evaluation.
The element namedb in the first elementa is referenced, but elementb in the seconda is not referenced because the expression evaluation did not proceed beyond the filter expression that rejected the seconda element.
While performing the NameTest for elementb, observe that an XPath expression evaluator may visit all the children of the first elementa in order to perform the NodeTest. However, a node is not referenced if it is only visited but fails the NodeTest. In this case, the NodeTest is a NameTest forb, which the elementd fails. Therefore,d is not referenced.
The filter expression test onb rejects the only elementb that has been selected so far because the attribute value ofattr does not match the equality test. Still,b and its attributeattr have been referenced by this expression.
Elementc is not considered to be referenced by this expression given this data. Although a NameTest forc appears in the expression, the evaluation of the expression did not proceed to perform the NameTest due to the rejection ofb by the filter expression.
Finally, note that an XPath expression can reference many nodes even if its final result is an empty nodeset.
Note:
Defining areference in terms of matching a NodeTest was a deliberate design decision that creates more references than necessary in order to make the computation system more responsive to certain types of changes without needing a rebuild operation. When a leaf node is filtered from an expression by a predicate, the leaf node is still considered to be referenced so that if the condition changes such that the leaf node would be included in the result value of the expression, then the expression will be recalculated without needing a rebuild. However, once a node is rejected from an expression, further location steps are not evaluated relative to the rejected node, so references for that location step are only created based on its execution relative to accepted nodes. For example, if the above expression were in acalculate, and if the attribute of eitherb element changes to the valueX, the expression would be recalculated but it still does not record a reference to anyc elements until the references are obtained in the next rebuild operation. Moreover, the excess references created by the definition may cause some recalculation constructs to cease operation due to circular references that would not be created with a stricter definition of a reference. A future version of XForms may use a stricter version of referencing for recalculation and a less strict definition of referencing for the purpose of detecting and performing automatic rebuild operations.
The referencing of a repeat index by theindex() function is handled as a special case. Implementations must behave as if each occurrence of arepeat is associated with an implicitly managed instance data node containing the repeat index. If arepeat identified asR1 contains arepeat identified asR2, then a repeat index instance node is managed for each occurrence ofR2 that is generated byR1. An invocation of the functionindex() 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 isdependent on the instance node. Adependency 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 Section4.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 isdynamically 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 adynamic 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 Section4.3.2 The xforms-recalculate Event essentially stores the dependency lists of instance nodes corresponding to all the references made by computed expressions (see AppendixC 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 therebuild action. Additionally, theinsert anddelete 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 oninsert anddelete, a form author can use many kinds of dynamic dependencies in model binding expressions and computed expressions without ever explicitly invoking therebuild action. This includes the use of functions such asposition(),last(), andcount() on element and attribute nodes because the return values of the functions in these cases is fixed except when aninsert ordelete occurs. By comparison, functions such asid(),instance(), andindex() can establish dynamic dependencies that can necessitate invoking arebuild 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. Abinding expression is an XPath expression used to bind amodel 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, andsubmissions, and their descendant elements. These expressions follow one of the three schedules associated with binding expressions as described below.
7.4.1 Model Binding Expressions and Computed Expressions
Amodel binding expression is a kind of binding expression that can be used to declare model item properties, and is used in the Node-Set binding of thebind element. Acomputed expression is an XPath expression used to determine the value of amodel item property based on instance data. Several of the attributes ofbind are computed expressions, includingcalculate,readonly,relevant, andrequired.
Dynamic dependencies in model binding expressions and computed expressions will require manual rebuilding of dependencies.
Note:
If theindex() function is being invoked from a model binding expression or computed expression, it will be necessary to invokerebuild manually. If the repeat index change occurs due to an implicit behavior such as a change to the focused form control, then the rebuild (along with recalculate, revalidate and refresh) can be invoked from a handler forDOMFocusIn attached to therepeat or each repeat object.
7.4.2 Expressions in Actions and Submissions
Binding expressions on XForms actions and XPath expressions appearing in other attributes of XForms actions are evaluated at the time the XForms action is performed. In some cases, XForms actions have child elements that allow the values of some of their attributes to be determined based on instance data. In these cases, thevalue attribute of the child element is evaluated at the time the corresponding attribute is needed in the processing model of the containing XForms action.
Similarly, XPath expressions used in the attributes ofsubmission and its child elements (other than XForms actions) are evaluated as needed within the submission processing model.
Form authors can use dynamic dependencies in the XPath expressions of XForms Actions and Submissions without invoking any special data structure reconstruction actions because implementations must behave as if these expressions are evaluated as needed.
7.4.3 UI Expressions
AUI Binding Expression is a Single Node Binding or Node Set Binding in a form control. AUI expression is a UI Binding Expression or an XPath expression appearing in a descendant element of a form control, except for XPath expressions in the categories described above (such as XForms action expressions). These include the Single Node Bindings and Node Set Bindings of the additional elements that contribute to the behavior of a form control (includinglabel,help,hint andalert,filename andmediatype) and the selection helper elements (itemset,label,value andcopy). This also includes thevalue attribute onoutput andvalue elements.
Form authors can use dynamic dependencies in UI Expressions without invoking any special data structure reconstruction actions because the state of the user interface at the end of processingxforms-refresh is required to reflect the instance data as if all UI Expressions had been re-evaluated.
Note:
Implementations may record UI Expression dependency lists on instance nodes to help streamline detection of the need to re-evaluate a UI Expression at the beginning of processing forxforms-refresh. Such implementations may determine that a UI Expression is stale (needs re-evaluation) when a node on which it depends has been changed. An implementation may also indicate that all UI Expressions are stale if a node of instance data is inserted, deleted or replaced, or the implementation may streamline detection of which UI Expressions may be affected by the insertion, deletion or replacement of an instance data node.
7.4.4 UI Binding in other XML vocabularies
The XForms binding mechanism allows other XML vocabularies to make single node bindings between custom user interface controls and XForms instance data. As an example, XForms binding attributebind might be used within XHTML 1.x user interface controls as shown below. See3.2.3 Single-Node Binding Attributes.
XForms Binding In XHTML 1.x User Interface Controls
<html:input type="text" name="..." xforms:bind="fn"/>
7.4.5 Binding Examples
Consider the following document with the one-and-only XForms model:
<xforms:model> <xforms:instance xmlns=""> <orderForm> <shipTo> <firstName>John</firstName> </shipTo> </orderForm> </xforms:instance> <xforms:bind nodeset="/orderForm/shipTo/firstName" /></xforms:model>
The following examples show three ways of binding user interface controlxforms:input to instance elementfirstName declared in the model shown above.
UI Binding Using Attributeref
<xforms:input ref="/orderForm/shipTo/firstName">...
UI Binding Using Attributebind
<xforms:input bind="fn">...
Specifies Model Containing The Instance Explicitly
<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 , and7.11 Object Functions.
The function library provided by an XForms processor may also contain other extension functions as described in7.12 Extension Functions.
If an error occurs in an XPath function, then an4.5.2 The xforms-compute-exception Event or4.5.1 The xforms-binding-exception Event occurs..
7.6 Boolean Functions
7.6.1 The boolean-from-string() Function
booleanboolean-from-string(string)
Functionboolean-from-string returnstrue if the required parameterstring is "true" or "1", orfalse if parameterstring is "false", or "0". This is useful when referencing a Schemaxsd:boolean datatype in an XPath expression. If the parameter string matches none of the above strings, according to a case-insensitive comparison, the return value isfalse.
7.6.2 The is-card-number() Function
booleanis-card-number(string?)
If the string parameter conforms to the pattern restriction of thecard-number datatype, then this function applies theLuhn algorithm described in[Luhn Patent] and returns true if the number satisfies the formula. Otherwise, false is returned. If the parameter is omitted, it defaults to the string-value of the current context node.
Examples (see also5.2.7 xforms:card-number):
returnstrue if and only if the context node contains a string that contains of zero or more digits and satisfies the formula.
is-card-number('4111111111111111')returnstrue. Other examples of string constants that will returntrue are :5431111111111111,341111111111111 and6011601160116611.
returnsfalse.
7.7 Number Functions
7.7.1 The avg() Function
numberavg(node-set)
Functionavg returns the arithmetic average of the result of converting the string-values of each node in the argument node-set to a number. The sum is computed withsum(), and divided withdiv by the value computed withcount(). If the parameter is an empty node-set, or if any of the nodes evaluate toNaN, the return value isNaN.
7.7.2 The min() Function
numbermin(node-set)
Functionmin returns the minimum value of the result of converting the string-values of each node in argumentnode-set to a number. "Minimum" is determined with the< operator. If the parameter is an empty node-set, or if any of the nodes evaluate toNaN, the return value isNaN.
7.7.3 The max() Function
numbermax(node-set)
Functionmax returns the maximum value of the result of converting the string-values of each node in argumentnode-set to a number. "Maximum" is determined with the< operator. If the parameter is an empty node-set, or if any of the nodes evaluate toNaN, the return value isNaN.
7.7.4 The count-non-empty() Function
numbercount-non-empty(node-set)
Functioncount-non-empty returns the number of non-empty nodes in argumentnode-set. A node is considered non-empty if it is convertible into a string with a greater-than zero length.
7.7.5 The index() Function
numberindex(string)
Functionindex takes a string argument that is theIDREF of arepeat and returns the current 1-based position of the repeat index for the identifiedrepeat—see9.3.1 The repeat Element for details onrepeat and its associated repeat index. If the specified argument does not identify arepeat, the function returnsNaN.
Note:
The IDREF obtained from the function parameter may not uniquely identifythe desiredrepeat if therepeat element bearing the matching ID resides in a repeating construct such as elementrepeat. The general method described in4.7 Resolving ID References in XForms is used to determine the desired run-time repeat object.
index
<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>7.7.6 The power() Function
numberpower(number,number)
Raises the first argument to the power of the second argument, returning the result. Ifthe calculation does not result in a real number, thenNaN is returned.
Examples:
returns8
returnsNaN.
if (prin>0 and dur>0 and rate>0, prin*rate/(1-power(1+rate, -dur)), 0)
returns a compounded interest payment value given a non-zero principal (prin), duration (dur) and periodic interest rate (rate).
7.7.7 The random() Function
numberrandom(boolean?)
This function generates and returns a uniformly distributed random or pseudorandom number in therange from 0.0 up to but excluding 1.0. This function accepts an author-optional boolean parameter that isfalse by default. Iftrue, the random number generator for this function is first seeded with a source of randomness before generating the return value. A typical implementation may seed the random number generator with the current system time in milliseconds whenrandom(true) is invoked, and it may apply a linear congruential formula to generate return values on successive invocations of the function.
Example:
could return0.14159265358979
7.7.8 The compare() Function
numbercompare(string,string)
This function returns -1, 0, or 1, depending on whether the value of the first argument is respectively less than, equal to, or greater than the value of second argument based on lexicographic comparison using Unicode code point values[Unicode Collation Algorithm].
Example:
compare('apple', 'orange')returns-1
7.8 String Functions
7.8.1 The if() Function
stringif(boolean,string,string)
Functionif evaluates the first parameter as boolean, returning the second parameter whentrue, otherwise the third parameter.
Note:
This function is deprecated because a future version of XForms is expected to be based on[XPath 2.0], which contains anif construct that is incompatible with this function.Form authors and design tools are encouraged to use the functionchoose() from Section7.11.1 The choose() Function instead of this function.
7.8.2 The property() Function
stringproperty(string)
This function accepts a string identifying a property name. If the property name is not recognized, empty string is returned. The property definitions for this function are as follows:
| Property | Return Value |
|---|
version | 1.1 |
conformance-level | full,basic or a string beginning withfull orbasic |
| Any otherNCName | Reserved. Their use results in an exception (see7.5 The XForms Function Library for the exception type) |
| QNameButNotNCName | An implementation-specific property value, such as a locale or timezone for the user agent. If the implementation does not support the property, then empty string is returned. |
Examples:
returns1.1
property('conformance-level')may returnfull
7.8.3 The digest() Function
stringdigest(string,string,string?)
This function accepts a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The data string is serialized as UTF-8, the hash value is then computed using the indicated hash algorithm, and the hash value is then encoded by the indicated method, and the result is returned by the function. The following table presents the keywords for the second string parameter and the corresponding hash algorithms:
This recommendation defines the valueshex andbase64 for the third string parameter that indicates the encoding method. If the parameter is missing, then the default isbase64. Thehex andbase64 encoding methods of this function correspond to the encodings defined in[XML Schema part 2] for the datatypeshexBinary andbase64Binary, respectively. For the hexadecimal encoding, the digits 'a' through 'f'are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see7.5 The XForms Function Library for the exception type).
digest('abc', 'SHA-1', 'hex')returnsa9993e364706816aba3e25717850c26c9cd0d89d.
digest('abc', 'MD5', 'hex')returns900150983cd24fb0d6963f7d28e17f72.
digest('abc', 'SHA-256', 'hex')returnsba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
7.8.4 The hmac() Function
stringhmac(string,string,string,string?)
This function accepts a string for a key or shared secret, a string of data, a string indicating a cryptographic hashing algorithm, and an author-optional string indicating an encoding method. The key and data strings are serialized as UTF-8, and they are subjected to the HMAC algorithm defined in[HMAC] and parameterized by the the hash algorithm indicated by the third parameter. The result is encoded with the method indicated by the fourth parameter, and the result is returned by the function.
The following table presents the keywords for the third string parameter and the corresponding hash algorithms:
This recommendation defines the valueshex andbase64 for the fourth string parameter that indicates the encoding method. If the parameter is missing, then the default isbase64. Thehex andbase64 encoding methods of this function correspond to the encodings defined in[XML Schema part 2] for the datatypeshexBinary andbase64Binary, respectively. For the hexadecimal encoding, the digits 'a' through 'f'are encoded with lower case letters. Any other string value given for the encoding method results in an exception (see7.5 The XForms Function Library for the exception type).
hmac('Jefe', 'what do ya want for nothing?', 'SHA-1', 'hex')returnseffcdf6ae5eb2fa2d27416d5f184df9c259a7c79
hmac('Jefe', 'what do ya want for nothing?', 'MD5', 'hex')returns750c783e6ab0b503eaa86e310a5db738
hmac('Jefe', 'what do ya want for nothing?', 'SHA-256', 'hex')returns5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843
7.9 Date and Time Functions
Note:
The following XML Schema datatypes do not have specific functions for manipulation within XForms expressions:xsd:time,xsd:gYearMonth,xsd:gYear,xsd:gMonthDay,xsd:gDay,xsd:gMonth. Extension functions (7.12 Extension Functions) may be used to perform needed operations on these datatypes.
7.9.1 The local-date() Function
stringlocal-date()
This function returns a lexicalxsd:date obtained as if by the following rules: the result ofnow() is converted to a local date based on the user agent time zone information. If no time zone information is available, then the date portion of the result ofnow() is returned.
Example:
could return2006-10-13-07:00
substring(local-date(), 1, 10)
could return2006-10-13
days-to-date(days-from-date(local-date()) + 31)
returns a date that is 31 days from today. For example, iflocal-date() returns2006-10-13-07:00, then the result is2006-11-13.
7.9.2 The local-dateTime() Function
stringlocal-dateTime()
This function returns a lexicalxsd:dateTime obtained as if by the following rules: the result ofnow() is converted to a local dateTime based on the user agent time zone information. If no time zone information is available, then the result ofnow() is returned.
Example:
could return2006-10-13T16:04:17-07:00
adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(local-dateTime()) + 7200))
Adds two hours (7200 seconds) to the local date and time, returning the result in the local time zone. For example, iflocal-dateTime() returns2007-10-02T14:26:43-07:00, then the above expression returns2007-10-02T16:26:43-07:00
7.9.3 The now() Function
stringnow()
Thenow function returns the current UTC date and time as a string value in the canonical XML Schemaxsd:dateTime format. If time zone information is available, it is used to convert the date and time to UTC. If no time zone information is available, then the date and time are assumed to be in UTC.
Note:
Attaching a calculation of "now()" to an instance data node would not result in a stream of continuous recalculations of the XForms Model.
returns2006-10-14T01:04:17Z iflocal-dateTime() returns2006-10-13T18:04:17-07:00
seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)
Computes two hours from now, returning the result in UTC time. For example, ifnow() returns2007-10-02T21:26:43Z, then the above expression returns2007-10-02T23:26:43Z
7.9.4 The days-from-date() Function
numberdays-from-date(string)
This function returns a whole number of days, according to the following rules:
If the string parameter represents a legal lexicalxsd:date orxsd:dateTime, the return value is equal to the number of days difference between the specified date or dateTime (normalized to UTC) and1970-01-01. Hour, minute, and second components are ignored after normalization. Any other input parameter causes a return value ofNaN.
Note:
If anxsd:date is given as the parameter, the timezone is ignored if provided because there is no way to normalize to the date in the UTC timezone without both the time and timezone.
Examples:
days-from-date("2002-01-01")returns11688
days-from-date("2002-01-01-07:00")returns11688
days-from-date("1969-12-31")returns-1
7.9.5 The days-to-date() Function
stringdays-to-date(number)
This function returns a string containing a lexicalxsd:date that corresponds to the number of days passed as the parameter according to the following rules:
The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired date and1970-01-01. An input parameter value ofNaN results in output of the empty string.
Examples:
returns2002-01-01
returns1969-12-31
7.9.6 The seconds-from-dateTime() Function
numberseconds-from-dateTime(string)
This function returns a possibly fractional number of seconds, according to the following rules:
If the string parameter represents a legal lexicalxsd:dateTime, the return value is equal to the number of seconds difference between the specified dateTime (normalized to UTC) and1970-01-01T00:00:00Z. If no time zone is specified, UTC is used. Any other input string parameter causes a return value ofNaN. This function does not support leap seconds.
Example:
seconds-from-dateTime('1970-01-01T00:00:00Z')returns0
seconds-from-dateTime('1970-01-01T00:00:00-08:00')returns28800
7.9.7 The seconds-to-dateTime() Function
stringseconds-to-dateTime(number)
This function returns a string containing a lexicalxsd:dateTime that corresponds to the number of seconds passed as the parameter according to the following rules:
The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired UTC dateTime and1970-01-01T00:00:00Z. An input parameter value ofNaN results in output of the empty string. This function does not support leap seconds.
Examples:
returns1970-01-01T00:00:00Z
seconds-from-dateTime(28800)
returns1970-01-01T08:00:00Z
seconds-to-dateTime(seconds-from-dateTime(now()) + 7200)
Computes two hours from now, returning the result in UTC time. For example, ifnow() returns2007-10-02T21:26:43Z, then the above expression returns2007-10-02T23:26:43Z
adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))
Computes two hours from now, returning the result in the local time zone. For example, ifnow() returns2007-10-02T21:26:43Z and the local date and time is2007-10-02T14:26:43-07:00, then the above expression returns2007-10-02T16:26:43-07:00
7.9.8 The adjust-dateTime-to-timezone() Function
stringadjust-dateTime-to-timezone(string)
This function adjusts a legal lexicalxsd:dateTime received as the string parameter to the local time zone of the implementation, and returns the result. If the string argument contains no time zone, then the result is the string argument with the local time zone as the time zone component. If the implementation does not have access to time zone information, UTC is used. The result is empty string if the string argument is the empty sequence or not a legal lexicalxsd:dateTime.
Examples:
adjust-dateTime-to-timezone('2007-10-07T02:22:00')returns2007-10-07T02:22:00-07:00 in the Pacific time zone since daylight savings time applies.
adjust-dateTime-to-timezone('2007-10-02T21:26:43Z')returns2007-10-02T14:26:43-07:00 in the Pacific time zone since daylight savings time applies.
adjust-dateTime-to-timezone(seconds-to-dateTime(seconds-from-dateTime(now()) + 7200))
Computes two hours from now, returning the result in the local time zone. For example, ifnow() returns2007-10-02T21:26:43Z and the local date and time is2007-10-02T14:26:43-07:00, then the above expression returns2007-10-02T16:26:43-07:00
7.9.9 The seconds() Function
numberseconds(string)
This function returns a possibly fractional number of seconds, according to the following rules:
If the string parameter represents a legal lexicalxsd:duration, the return value is equal to the number specified in the seconds component plus 60 * the number specified in the minutes component, plus 60 * 60 * the number specified in the hours component, plus 60 * 60 * 24 * the number specified in the days component. The sign of the result will match the sign of the duration. Year and month components, if present, are ignored. Any other input parameter causes a return value ofNaN.
Note:
Even though this function is defined based on a lexicalxsd:duration, it is intended for use only with derived-from-xsd:duration datatypes, specificallyxforms:dayTimeDuration.
Examples:
seconds("P3DT10H30M1.5S")returns297001.5 (3 days, 10 hours, 30 minutes, and 1.5 seconds)
returns0 because the year and month parts of the duration are ignored and the remaining portions are unspecified and default to 0
returnsNaN because the parameter is not a lexically valid duration
7.9.10 The months() Function
numbermonths(string)
This function returns a whole number of months, according to the following rules:
If the string parameter represents a legal lexicalxsd:duration, the return value is equal to the number specified in the months component plus 12 * the number specified in the years component. The sign of the result will match the sign of the duration. Day, hour, minute, and second components, if present, are ignored. Any other input parameter causes a return value ofNaN.
Note:
Even though this function is defined based on a lexicalxsd:duration, it is intended for use only with derived-from-xsd:duration datatypes, specificallyxforms:yearMonthDuration.
Examples:
Examples:
returns14 (1 year and 2 months)
returns-19 because the duration is negative and expresses 0 years and 19 months
7.10 Node-set Functions
7.10.1 The instance() Function
node-setinstance(string?)
An XForms Model can contain more than one instance. This function allows access to instance data, within the same XForms Model, but outside the instance data containing the context node.
If the argument is omitted or is equal to the empty string, then the root element node (also called the document element node) is returned for the default instance in the model that contains the current context node.
Otherwise, the argument is converted to a string as if by a call to thestring function. This string is treated as an IDREF, which is matched againstinstance elements in the containing document. If a match is located, and the matching instance data is associated with the same XForms Model as the current context node, this function returns a node-set containing just the root element node (also called the document element node) of the referenced instance data. In all other cases, an empty node-set is returned.
Example:
For instance data corresponding to this XML:
<xforms:instance xmlns=""> <orderForm> <shipTo> <firstName>John</firstName> </shipTo> </orderForm></xforms:instance>
The following expression selects thefirstName node. Note that theinstance function returns an element node, effectively replacing the leftmost location step from the path:
ref="instance('orderform')/shipTo/firstName"7.10.2 The current() Function
node-setcurrent()
Returns thecontext node used to initialize the evaluation of the containing XPath expression.
Examples:
For the following instance data:
<xforms:instance xmlns=""> <converter> <amount>100</amount> <currency>jpy</currency> <convertedAmount></convertedAmount> </converter></xforms:instance><xforms:instance xmlns=""> <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>
and the following value calculation bind:
<bind nodeset="convertedAmount" calculate="../amount * instance('convTable')/rate[@currency=current()/../currency]"/>the content value of/converter/convertedAmount is the product of/converter/amount and the conversion table rate given by therate element whosecurrency attribute valuematches the content of/converter/currency.
For the following instance data:
<xforms:instance xmlns=""> <months> <mon>01</mon> <mon>02</mon> <mon>03</mon> </months></xforms:instance><xforms:instance xmlns=""> <months> <month code="01">Jan</month> <month code="02">Feb</month> <month code="03">Mar</month> </months></xforms:instance>
and the following repeat structure:
<repeat nodeset="mon"> <output value="instance('i2')/month[@code = current()]/></repeat>the output should containJan Feb Mar.
7.10.3 The id() Function
node-setid(object,node-set?)
Theobject parameter provides one or more IDREFs. This may be in the form of a string containing a space-separated list of IDREFs or a node-set, each node of which contains an IDREF. Thenode-set parameter provides nodes in one or more instance data documents to be searched. If the node-set parameter is not given or is empty, then the instance data document to be searched is the one containing the context node of the function call. For each node in the node-set parameter (or its default), the set of element nodes are collected with IDs that match the IDREFs from theobject parameter. The result of this function is a node-set containing the union of the collected element nodes from each string. An element node can be assigned an ID by means of anxml:id attribute or an attribute that is assigned the type ID by a DTD or xsd:ID or any type derived from xsd:ID by an XML schema, or thetype model item property.
Example:
Returns nodes identified by X or Y from the instance data document associated with the root element of theinstance identified by Z.
7.10.4 The context() Function
node-setcontext()
This function returns the in-scope evaluation context node of the nearest ancestor element of the node containing the XPath expression that invokes this function. The nearest ancestor element may have been created dynamically as part of the run-time expansion of repeated content as described in Section4.7 Resolving ID References in XForms.
Example:
<setvalue ref="x" value="context()/y"/>
This action sets nodex to the value of nodey, where both nodes are children of the in-scope evaluation context node for thesetvalue element.
Note:
An intended use of this function is in conjunction with therepeat element (Section9.3.1 The repeat Element and thesetvalue action element (Section10.2 The setvalue Element). The intent is to provide form authors with a means of expressing avalue attribute that is relative to the repeat context node when the Single Node Binding result is not.
7.11 Object Functions
7.11.1 The choose() Function
objectchoose(boolean,object,object)
This function provides a conditional test that chooses an object to return based on the boolean parameter. If the boolean parameter is true, then the first object is returned, otherwise the second object is returned. Each of the object parameters can be of any XPath datatype as described in Section7.1 XPath Datatypes, and this function does no type conversion of the parameter it chooses to return.
Note:
All parameters of an XPath function are evaluated, so the parameter that is not returned by this function is still evaluated, and its result is discarded by this function.
Note:
Form authors and design tools are encouraged to use this function instead of the functionif() described in Section7.8.1 The if() Function, which has been deprecated. Because this function returns an object instead of a string, migrating fromif() tochoose() may occasionally require conversion of the return result using thestring() function.
Example:
choose(count(x) > 0, x, y)
Returns the node-set of matchingx if it is non-empty and the node-set matchingy otherwise.
If the context node of the function contains attributex, then the nodeset containing that attribute is returned. Otherwise, the number0 is returned.
7.11.2 The event() Function
objectevent(string)
Functionevent returns context specific information determined by thestring argument. The returned context information is an XPath object whose type and contentdepends upon the requested property. Each event describes what properties can be accessed by this function and the type and value that will be returned as the result.
The event context properties available for each event are provided in the sections that describe the events.
This function is intended for use in the XPath expressions of XForms actions. If invoked for any otherXPath expression, such as a binding expression or model item property expression, this function returnsthe empty string. If this function is invoked from an XPath expression for an XForms action, then event context information is used from the most recently dispatched event whose action handler contains the XForms action.
Some properties defined for an event may be unavailable if certain prerequisite conditions were not met prior to the event being dispatched. Implementations may also add custom properties. If the event context information does not contain the property indicated by thestring argument, then an empty node-set is returned.
Examples:
If called from anxforms-insert event handler, a nodeset is returned containing the instance data node or nodes inserted.
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 attributefunctions on elementmodel. 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:
Explicitly declaring extension functions enables XForms Processors to detect the use of unimplemented extension functions at document load-time, rather than throwing a fatal exception (4.5.1 The xforms-binding-exception Event or4.5.2 The xforms-compute-exception Event) during user interaction. Failure by authors to declare extension functions will result in an XForms Processor potentially halting processing during user interaction with a fatal error.
10 XForms Actions
This chapter defines the controller layer of XForms, an XML Events-based[XML Events] common set of actions that can be invoked in response to events.
Note:
XForms itself defines no method for script-based event handling. The definition of such facilities is a responsibility of the hosting language.
All form controls as well as other elements defined in this specification have a set of commonbehaviors that encourage consistent authoring and look and feel for XForms-based applications. This consistency comes from attaching a common set of behaviors to the various form controls. In conjunction with the event binding mechanism provided by XML Events, these handlers provide a flexible means for forms authors to specify event processing at appropriate points within the XForms user interface. XForms Actions are declarative XML event handlers that capture high-level semantics. As a consequence, they significantly enhance the accessibility of XForms-based applications in comparison to previous Web technologies that relied exclusively on scripting.
The elements and attributes included in this module are:
| Element | Attributes | Minimal Content Model |
|---|
| action | Common,Events,Action Common | (Action)* |
| setvalue | Common,Events,Action Common,Single Node Binding, value (string XPath Expression) | PCDATA |
| insert | Common,Events,Action Common,Node Set Binding, context (node XPath Expresson), at (number XPath Expression), position ("before"|"after"), origin (nodeset XPath Expresson) | EMPTY |
| delete | Common,Events,Action Common,Node Set Binding, context (node XPath Expresson), at (number XPath Expression) | EMPTY |
| setindex | Common,Events,Action Common, repeat (xsd:IDREF), index (number XPath Expression) | EMPTY |
| toggle | Common,Events,Action Common, case (xsd:IDREF) | case? |
| setfocus | Common,Events,Action Common, control (xsd:IDREF) | control? |
| dispatch | Common,Events,Action Common, name (xsd:NMTOKEN), targetid (xsd:IDREF), delay (xsd:nonNegativeInteger), bubbles (xsd:boolean), cancelable (xsd:boolean) | name?, targetid?, delay? [in any order] |
| rebuild | Common,Events,Action Common, model (xsd:IDREF) | EMPTY |
| recalculate | Common,Events,Action Common, model (xsd:IDREF) | EMPTY |
| revalidate | Common,Events,Action Common, model (xsd:IDREF) | EMPTY |
| refresh | Common,Events,Action Common, model (xsd:IDREF) | EMPTY |
| reset | Common,Events,Action Common, model (xsd:IDREF) | EMPTY |
| load | Common,Events,Action Common,Single Node Binding (author-optional), resource (xsd:anyURI), show ("new" | "replace") | resource? |
| send | Common,Events,Action Common, submission (xsd:IDREF) | EMPTY |
| message | Common,Events,Action Common,Single Node Binding (author-optional), level ("ephemeral" | "modeless" | "modal"|QNameButNotNCName) | (PCDATA|UI Inline)* |
This module also defines the content set"Action", which includes the following elements:
(action|setvalue|insert|delete|setindex|toggle|setfocus|dispatch|rebuild|recalculate|revalidate|refresh|reset|load||send|message)*
The following group of attributes, here calledAction Common, are available to allAction elements:
| Element | Attributes |
|---|
| Action | if (boolean XPath Expression), while (boolean XPath Expression) |
- if
Author-optional attribute defined in Section10.17 Conditional Execution of XForms Actions.
- while
Author-optional attribute defined in Section10.18 Iteration of XForms Actions.
Additionally, this module defines the attribute group"XML Events", which includes all of the "global" attributes defined in the[XML Events] specification.
The following example shows how events can be used:
Action Syntax
<xforms:trigger> <xforms:label>Reset</xforms:label> <xforms:reset ev:event="DOMActivate" model="thismodel"/></xforms:trigger>
This example recreates the behavior of the HTMLreset control, which this specification does not define as an independent form control.
For each built-in XForms Action, this chapter lists the following:
Name
Common Attributes
Special Attributes
Description of behavior
All elements defined in this chapter explicitly allow global attributes from the XML Events namespace, and apply the processing defined in that specification in section 2.3[XML Events].
Anoutermost action handler is an action that is activated when the XForms processor is not executing any other action handlers.
Aninner action handler is an action that is activated when the XForms processor is executing the declared actions of anoutermost action handler. An inner action handler may be within the content of the outermost action handler, or it may be executed as the response to an event dispatched while performing all of the actions initiated by theoutermost action handler.
Deferred Updates: Sequences of one or more XForms Actions have a deferred effect on XForms model and user interface processing. Implementations are free to use any strategy to accomplish deferred updates, but the end result must be as follows: Instance data changes performed by a set of actions do not result in immediate computation dependency rebuilding, recalculation, revalidate and form control refreshing until the termination of theoutermost action handler, as described here. Each XForms model can be thought of as having a set of deferred update Boolean flags, initiallyfalse at the start of anoutermost action handler, to indicate whether each of the actionsrebuild,recalculate,revalidate, andrefresh are required for that model upon termination of theoutermost action handler.
By default, the behavior of an action handler is performed one time when the action is encountered in the execution sequence. However, execution of an action handler may be conditional or iterated, as described in10.17 Conditional Execution of XForms Actions and10.18 Iteration of XForms Actions.
Execution of anoutermost action handler begins by setting the XForms processor into the state of executing anoutermost action handler. Theoutermost action handler is then performed, which may include the execution ofinner action handlers. Finally, the XForms processor is set into the state of not executing anoutermost action handler and then the deferred update is performed for each model.
Thedeferred update behavior for a model consists of examining each deferred update Boolean flag in the order ofrebuild,recalculate,revalidate, andrefresh, and for eachtrue flag, set the flag tofalse and then dispatch the proper event to the model for that deferred update flag (i.e. dispatchxforms-rebuild for a truerebuild flag,xforms-recalculate for a truerecalculate flag,xforms-revalidate for a truerevalidate flag, andxforms-refresh for a truerefresh flag).
Note:
The XForms processor is not considered to be executing anoutermost 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 newoutermost action handler.
Actions that manipulate properties of the XForms view layer begin by invoking thedeferred update behavior so that the model and all data are up to date prior to performing the action. The XForms Actions in this category are:
setfocus
toggle
setindex
Actions that directly invoke rebuild, recalculate, revalidate, or refresh always have an immediate effect, and clear the corresponding deferred update flag. The XForms Actions in this category are:
rebuild
recalculate
revalidate
refresh
Similarly, if the default processing of any of the eventsxforms-rebuild,xforms-recalculate,xforms-revalidate, orxforms-refresh are performed, then the corresponding deferred update flag is cleared. The XForms Actions that can dispatch these events are:
reset
dispatch
XForms Actions that change the tree structure of instance data result in setting all four deferred update flags totrue for the model over which they operate. The XForms Actions in this category are:
insert
delete
XForms Actions that change only the value of an instance node results in setting the deferred update flags forrecalculate,revalidate, andrefresh totrue and making no change to the deferred update flag forrebuild for the model over which they operate. The XForms Actions in this category are:
setvalue
setindex
Finally, the XFormssubmission process can affect deferred update behavior. See Section11.2 The xforms-submit Event for details. XForms actions that are capable of initiating an XForms submission are:
send
dispatch
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
Grouping Actions
<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. Anxforms-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 XPathstring function. An empty string is used if the XPath evaluation fails.
The element content ofsetvalue specifies the literal value to set; this is an alternative to specifying a computed value via attributevalue. If neither avalue 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, thevalue attribute is used. The following examples contrast these approaches:
setvalue with Expression
<setvalue bind="put-here" value="a/b/c"/>
This causes the string value ata/b/c in the instance data to be placed on the single node selected by the bind element withid="put-here".
setvalue with Literal
<setvalue bind="put-here">literal string</setvalue>
This causes the value "literal string" to be placed on the single node selected by the bind element withid="put-here".
Note:
See Section7.10.4 The context() Function for an example in which thecontext() function is used to provide the same initial evaluation context node to both theref andvalue attributes. See AppendixB Patterns for Data Mutations for numerous further usage patterns forsevalue,insert anddelete.
All strings are inserted into the instance data as follows:
Element nodes: If element child nodes are present, then anxforms-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: anxforms-binding-exception occurs.
Note:
This action affectsdeferred updates by setting the deferred update flags for recalculate, revalidate and refresh.
10.3 Theinsert Element
Theinsert action is used to create one or more nodes of instance data by cloning one or more existing instance nodes. Attributes of theinsert 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 typexsd: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 themodel attribute is present, then it is processed as described in7.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 oninsert, includingif,while,nodeset andorigin.
- origin
Author-optional attribute containing an XPath expression evaluated using the in-scope evaluation context , which may have been amended by thecontext attribute. Theorigin node-set is the set of one or more nodes to be cloned by theinsert action. If this attribute is present and resolves to a non-empty nodeset, then the result overrides the default setting of theorigin node-set as described below in the processing of theinsert action.
- at
Author-optional attribute containing an XPath expression evaluated using the Node Set Binding node-set to help determine theinsert location node. This attribute is ignored if the Node Set Binding is not specified or specifies an empty node-set. Theinsert 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 theinsert. If this attribute is present, then its result is used to override the default setting of theinsert location node as described below in the processing of theinsert action.
- position
Author-optional selector that indicates where to put the cloned node or nodes relative to theinsert location node. Valid values arebefore andafter, 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 theinsert location node within the Node Set Binding node-set is the document element of an instance, then this attribute is ignored.
Processing for theinsert action is as follows:
Theinsert context is determined. If thecontext attribute is not given, theinsert context is the in-scope evaluation context. Otherwise, the XPath expression provided by thecontext attribute is evaluated using the in-scope evaluation context, and the first node rule is applied to obtain theinsert context. Theinsert action is terminated with no effect if theinsert context is the empty node-set.
The Node Set Binding node-set is determined. If abind attribute is present, it directly determines the Node Set Binding node-set. If anodeset attribute is present, it is evaluated within theinsert 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. Theinsert action is terminated with no effect if any of the following conditions is true:
Thecontext attribute is not given and the Node Set Binding node-set is the empty node-set.
Thecontext attribute is given, theinsert context does not evaluate to an element node and the Node Set Binding node-set is the empty node-set.
Theorigin node-set is determined. If theorigin attribute is not given and the Node Set Binding node-set is empty, then theorigin node-set is the empty node-set. Otherwise, if theorigin attribute is not given, then theorigin node-set consists of the last node of the Node Set Binding node-set. If theorigin attribute is given, theorigin node-set is the result of the evaluation of theorigin attribute in theinsert context. Namespace nodes and root nodes (parents of document elements) are removed from theorigin node-set. Theinsert action is terminated with no effect if theorigin node-set is the empty node-set.
Theinsert location node is determined. If the Node Set Binding node-set is not specified or empty, theinsert location node is theinsert context node. Otherwise, if theat attribute is not given, then theinsert location node is the last node of the Node Set Binding node-set. Otherwise, aninsert location node is determined from theat attribute as follows:
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 is1.
The return value is processed according to the rules of the XPath functionround(). For example, the literal1.5 becomes2, and the literal'string' becomesNaN.
If the result is in the range 1 to the Node Set Binding node-set size, then theinsert location is equal to the result. If the result is non-positive, then theinsert location is1. Otherwise, the result isNaN or exceeds the Node Set Binding node-set size, so theinsert location is the Node Set Binding node-set size.
Theinsert location node is the node in the Node Set Binding node-set at the position given by theinsert location.
Theinsert action is terminated with no effect if the insertion will create nodes whose parent is readonly. This occurs if theinsert location node is readonly and the Node Set Binding node-set is not specified or empty, or otherwise if the parent of theinsert location node is readonly.
Each node in theorigin node-set is cloned in the order it appears in theorigin node-set.
Thetarget location of each of the cloned nodes is determined as follows:
If the Node Set Binding node-set is not specified or empty, then theinsert location node provided by thecontext attribute is intended to be the parent of the cloned node. Thetarget location is dependent on the types of the cloned node and theinsert location node as follows:
If theinsert location node is not an element node or root node, then it cannot be the parent of the cloned node, so thetarget location is undefined.
If theinsert 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 thetarget location is the root element of the instance.
If theinsert 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 thetarget location is before the first child of theinsert location node.
If theinsert location node is an element, and the cloned node is an attribute, then thetarget location is the attribute list of theinsert location node.
If theinsert location node is an element, and the cloned node is not an attribute, then thetarget location is before the first child of theinsert location node, or the child list of theinsert location node if it is empty.
Otherwise, the Node Set Binding node-set is specified and non-empty, so theinsert location node provided by the Node Set Binding and author-optionalat attribute is intended to be the sibling of the cloned node. If theinsert location node is an attribute or root node, then thetarget location is undefined. If theinsert location node is not an attribute or root node, then thetarget location is immediately before or after theinsert location node, based on theposition attribute setting or its default.
The cloned node or nodes are inserted in the order they were cloned into theirtarget 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 thetarget location due to a node type conflict or because thetarget location is undefined, then the insertion for that particular cloned node is ignored. Each cloned node that is inserted is added to theinserted-nodes list that will be provided in thexforms-insert event context information. For each cloned node used to update an existing attribute node, the existing attribute node is added to the list ofinserted-nodes.
Note:
A node type conflict is a mismatch between the XPath node type and thetarget location. For example, an attribute cannot be inserted as a sibling before or after an element.
If the list ofinserted-nodes is empty, then theinsert action is terminated with no effect.
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
Theinsert action is successfully completed by dispatching thexforms-insert event with appropriate context information.
Note:
Arepeat updates its index in response to this event if its repeat collection changes size as a result of the insertion. See Section9.3.3 Repeat Processing for details.
Note:
This action affectsdeferred updates by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.
Examples:
Inserting into arepeat, whether or not it is empty
When therepeat is empty, theat index is zero so a newitem is prepended to the child elements ofpurchaseOrder. When therepeat is non-empty, the newitem is added after the node currently indexed by repeatR.
...<xforms:instance> <purchaseOrder xmlns=""> <subtotal/> <tax/> <total/> </purchaseOrder></xforms:instance><xforms:instance> <prototypes xmlns=""> ... <item> <product/> <quantity/> <unitcost/> <price/> </item> ... </prototypes></xforms:instance>...<repeat nodeset="/purchaseOrder/item"> ...</repeat>...<xforms:trigger> <xforms:label>Add to purchase order</xforms:label> <xforms:action ev:event="DOMActivate> <xforms:insert context="/purchaseOrder" nodeset="item" at="index('R')" origin="instance('prototypes')/item"/> <xforms:setfocus control="R"/> </xforms:action></xforms:trigger>Insert and Read-Only Content
<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 nodeset="my:name/*" ... /> <insert nodeset="my:address/my:street" at="1" > </action></model>
Insert I1 fails because it attempts to insert into the content of a readonly node (my:name). Insert I2 succeeds even though the insert location is a readonly node because the new node is placed as a sibling into the content of the parent, which is not readonly.
See10.4 The delete Element for an example that usesinsert anddelete to make arepeat that always shows at least one repeat item. See AppendixB Patterns for Data Mutations for numerous further usage patterns forsevalue,insert anddelete.
10.4 Thedelete 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 themodel attribute is present, then it is processed as described in7.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 thedelete 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 ondelete, includingif,while, andnodeset.
- at
Author-optional attribute containing an XPath expression evaluated using the Node Set Binding node-set to determine thedelete location. If the Node Set Binding node-set is empty, then this attribute is ignored.
Processing for thedelete action is as follows:
Thedelete context is determined. It is set to the in-scope evaluation context, possibly overridden by thecontext attribute if that attribute is present. Thedelete action is terminated with no effect if thedelete context is the empty node-set.
The Node Set Binding node-set is determined. If abind attribute is present, it directly determines the Node Set Binding node-set. If anodeset attribute is present, it is evaluated within thedelete context to determine the Node Set Binding node-set. The behavior of thedelete action is undefined if the Node Set Binding node-set contains nodes from more than oneinstance. Thedelete 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.
Thedelete location is determined. If theat attribute is not specified, there is nodelete location. Otherwise, thedelete location is determined by evaluating the XPath expression specified by theat attribute as follows:
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 is1.
The return value is processed according to the rules of the XPath functionround(). For example, the literal1.5 becomes2, and the literal'string' becomesNaN.
If the result is in the range 1 to the Node Set Binding node-set size, then thedelete location is equal to the result. If the result is non-positive, then thedelete location is1. Otherwise, if the result isNaN or exceeds the Node Set Binding node-set size, thedelete location is the Node Set Binding node-set size.
If there is nodelete 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 adelete location, the node at thedelete 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.
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
Thedelete action is successfully completed by dispatching thexforms-delete event with appropriate context information.
Note:
This action affectsdeferred updates by setting the deferred update flags for rebuild, recalculate, revalidate and refresh.
Examples:
Usingdelete andinsert to Maintain a Non-empty repeatrepeat
In this example, thetrigger is not in therepeat. When it is activated, the indexeditem in the repeat is first deleted. Next, if that was the lastitem, then a new prototypicalitem is inserted so that therepeat does not become empty. The focus is then sent back to therepeat from thetrigger.
...<xforms:trigger> <xforms:label>Delete from purchase order</xforms:label> <xforms:action ev:event="DOMActivate"> <xforms:delete context="/purchaseOrder" nodeset="item" at="index('R')"/> <xforms:insert context="/purchaseOrder" if="not(item)" nodeset="item" origin="instance('prototypes')/item"/> <xforms:setfocus control="R"/> </xforms:action></xforms:trigger>Note:
The form author could have writtennodeset="/purchaseOrder/item" in thedelete action, but thecontext attribute was added for consistency with theinsert action.
Delete and Read-Only Content
<model xmlns:my="http://example.org"> <instance> <my:data> <my:name> <my:first-name>John</my:first-name> <my:last-name>Doe</my:last-name> </my:name> <my:address> <my:street>123 Main St.</my:street> <my:city>Smallville</my:city> </my:address> </my:data> </instance> <bind nodeset="/my:data/my:name/" readonly="true()"/> <bind nodeset="/my:data/my:address/my:street" readonly="true()"/> <action ev:event="xforms-model-construct-done"> <delete nodeset="my:name/*" ... /> <delete nodeset="my:address/my:street" at="1" > <delete nodeset="my:address" at="1" > </action></model>
Delete D1 fails because it attempts to delete from the content of a readonly node (my:name). Delete D2 succeeds even though the node to delete is readonly because the node is not being changed, but rather removed from the content of the parent, which is not readonly. Delete D3 succeeds even though it contains a readonly node because a node can be deleted if its parent is not readonly, and node deletion includes deletion of its attributes and content, regardless of whether or not the attributes or content nodes are readonly.
See AppendixB Patterns for Data Mutations for numerous further usage patterns forsevalue,insert anddelete.
10.5 The setindex Element
This XForms Action begins by invoking thedeferred update behavior. This action then marks a specific item as current in a repeating sequence (within9.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 (see7.2 Evaluation Context).
If the selected index is 0 or less, anxforms-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, anxforms-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.
Note:
The IDREF from therepeat attribute may not uniquely identify the desiredrepeat if therepeat element bearing the matching ID resides within the content of anotherrepeat. The general method described in4.7 Resolving ID References in XForms is used to determine the desired run-time repeat object.
Note:
This action affectsdeferred updates by performing deferred update in its initialization and by setting the deferred update flags for recalculate, revalidate and refresh.
10.6 The toggle Element
This XForms Action begins by invoking thedeferred update behavior. This action then selects one possible case from an exclusive list of alternatives in aswitch.
This action performs the following:
Dispatches anxforms-deselect event to the currently selectedcase in theswitch containing the identifiedcase.
Adjusts theselected states (not the attribute values) on the affected cases to reflect the new state of theswitch containing the identifiedcase.
Dispatches anxform-select event to thecase just selected.
Common Attributes:Common,Events,Action Common
Special Attributes:
- case
Author-optional reference to acase element. Thecase to select is specified by this attribute or by the child elementcase.
Thecase to be selected by theswitch is identified by IDREF either by the attributecase or by a childcase element. If nocase element contains the given identifier, then this action has no effect.
Note:
Whether the IDREF is obtained from thecase attribute or element, the IDREF may not uniquely identify the desiredcase if thecase element bearing the matching ID resides in a repeating construct such as elementrepeat. The general method described in4.7 Resolving ID References in XForms is used to determine the desired run-time case object.
Note:
This action affectsdeferred updates by performing deferred update in its initialization.
10.6.1 The case Element Child of the toggle Element
This section defines a child element oftoggle namedcase that is an alternate means of providing the identity of acase element to select with aswitch.
Element:case
Common attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain thecase identity, the result of the expression is processed as if by call to the XPathstring function. An empty string is used if the XPath evaluation fails.
Content: PCDATA
Thecase to be selected by thetoggle action is given by thecase attribute or thecase element. If both are given, the element takes precedence. Due to the addition of the element, thecase attribute is no longer required, but either thecase attribute or thecase element must appear. Thecase element can provide the identity of acase with either its string content or thevalue attribute. If both are given, then thevalue attribute takes precedence.
<toggle><case value="concat('case_', ../addressBlockType)"/></toggle>10.7 The setfocus Element
This XForms Action begins by invoking thedeferred update behavior. This action then dispatches anxforms-focus event (4.3.7 The xforms-focus Event) to the element identified by attributecontrol or child elementcontrol.
Common Attributes:Common,Events,Action Common
Special Attributes:
- control
Author-optional reference to aform control. The form control is specified by this attribute or by the child elementcontrol.
The identity of the element to which thesetfocus action dispatchesxforms-focus is given by thecontrol attribute or thecontrol element. If no such element contains the given identifier, then this action has no effect.
Note:
Whether the IDREF is obtained from thecontrol attribute or element, the IDREF may not uniquely identifythe desired form control if the element bearing the matching ID resides in a repeating construct such as elementrepeat. The general method described in4.7 Resolving ID References in XForms is used to determine the desired form control.
Note:
Changing the focus to a form control within a repeat object may cause one or more repeat index values to be changed as described in Section9.3.4 User Interface Interaction.
10.7.1 The control Element Child of the setfocus Element
This section defines a child element ofsetfocus namedcontrol that is an alternate means of providing the element that receives thexforms-focus event.
Element:control
Common attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain thedesired element identifier, the result of the expression is processed as if by call to the XPathstring function.An empty string is used if the XPath evaluation fails.
Content: PCDATA
The identity of the element to which thesetfocus action dispatchesxforms-focus is given by thecontrol attribute or thecontrol element. If both are given, the element takes precedence. Due to the addition of the element, thecontrol attribute is no longer required, but either thecontrol attribute or thecontrol element must appear. Thecontrol element can provide the desired element identifier with either its string content or thevalue attribute. If both are given, then thevalue attribute takes precedence.
<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:
Predefined XForms events (i.e., xforms-event-name), in which case thebubbles andcancelable attributes are ignored and the standard semantics as defined in4 Processing Model apply.
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 istrue 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 istrue for a custom event. For predefined events, this attribute has no effect.
The event to be dispatched is given by thename attribute or thename child element.Due to the addition of thename element, thename attribute is not required, but either thename attribute or thename 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 thetargetid attribute or thetargetid chlid element. Due to the addition of thetargetid element, thetargetid 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 thedispatch elementmay allow the attribute namedtarget and the child elementtarget to be used. The attribute and element namedtarget provide exactly the same behaviors as thetargetid attribute and element, except that thetarget attribute and element are ignored if thedispatch element also bears atargetid attribute or contains atargetid child element.
Note:
Whether the IDREF is obtained from thetargetid attribute ortargetid element, the IDREF may not uniquely identify the desired target object if the element bearing the matching ID resides in a repeating construct such as elementrepeat. The general method described in4.7 Resolving ID References in XForms is used to determine the desired target object.
The event may be dispatched immediately or after a specified non-negative number of milliseconds of delay. The event delay is specified thedelay attribute or by the child elementdelay. If the delay is not specified or if the given value does not conform toxsd:nonNegativeInteger, then the event is dispatched immediately as the result of thedispatch 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. Thedispatch action has no effect if the event delay is a non-negative integer and the specified event is already in the delayed event queue.
Note:
Since an element bearing a particular ID may be repeated, the delayed event queue may contain more than oneevent with the same name and target IDREF. It is the name and the targetrun-time element that must be unique.
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 arepeat 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.
Note:
Because the delayed event is first removed from the delayed event queue and then dispatched, a handler for a givenevent may dispatch the event again with a delay. This can be used to perform simple polling and asynchronous looping operations. Moreover, theif attribute can be applied to thedispatch action to decide when to discontinue the polling or looping based on a setting in instance data.
10.8.1 The name Child Element
This section defines a new child element ofdispatch that provides an alternate means of specifying thename of the event to dispatch.
Element:name
Common attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain theevent name, the result of the expression is processed as if by call to the XPathstring function.An empty string is used if the XPath evaluation fails.
Content: PCDATA
The event name of thedispatch action is given by thename attribute or thename element. If both are given, the element takes precedence. Thename element can provide the event name with either its string content or thevalue attribute. If both are given, then thevalue attribute takes precedence.
10.8.2 The targetid Child Element
This section defines a new child element ofdispatch that provides an alternate means of specifying thetarget of the event to be dispatched.
Element:targetid
Common attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain theevent target, the result of the expression is processed as if by call to the XPathstring function.An empty string is used if the XPath evaluation fails.
Content: PCDATA
The event target of thedispatch action is given by thetargetid attribute or thetargetid element. If both are given, the element takes precedence. Thetargetid element can provide an IDREF for the event target with either its string content or thevalue attribute. If both are given, then thevalue attribute takes precedence.
10.8.3 The delay Child Element
This section defines a new child element ofdispatch that provides an alternate means of specifying thedelay imposed on the event to be dispatched.
Element:delay
Common attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain theevent delay, the result of the expression is processed as if by call to the XPathstring function. Ifthe result does not conform lexically toxsd:nonNegativeInteger, then the result of empty string is used.An empty string is used if the XPath evaluation fails.
Content: PCDATA
The event delay of thedispatch action is given by thedelay attribute or thedelay element. If both are given, the element takes precedence. Thedelay element can provide the delay with either its string content or thevalue attribute. If both are given, then thevalue attribute takes precedence.
10.9 The rebuild Element
This action causes the default processing ofxforms-rebuild to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching thexforms-rebuild event). This action results in the XForms Processor rebuilding any internal data structures used to track computational dependencies among instance data nodes —see4.3.1 The xforms-rebuild Event.
Common Attributes:Common,Events,Action Common
Special Attributes:
- model
Author-optional XForms Model selector, as defined in3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is themodel associated with the in-scope evaluation context node.
10.10 The recalculate Element
This action causes the default processing ofxforms-recalculate to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching thexforms-recalculate event). As a result, instance data nodes whose values need to be recalculated are updated as specified in the processing model—see4.3.2 The xforms-recalculate Event.
Common Attributes:Common,Events,Action Common
Special Attributes:
- model
Author-optional XForms Model selector, as defined in3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is themodel associated with the in-scope evaluation context node.
10.11 The revalidate Element
This action causes the default processing ofxforms-revalidate to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching thexforms-revalidate event). This results in the instance data being revalidated as specified by the processing model—see4.3.3 The xforms-revalidate Event.
Common Attributes:Common,Events,Action Common
Special Attributes:
- model
Author-optional XForms Model selector, as defined in3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is themodel associated with the in-scope evaluation context node.
10.12 The refresh Element
This action causes the default processing ofxforms-refresh to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching thexforms-refresh event). This action results in the XForms user interface beingrefreshed, and the presentation of user interface controls being updated to reflect the state of the underlying instance data—see4.3.4 The xforms-refresh Event.
Common Attributes:Common,Events,Action Common
Special Attributes:
- model
Author-optional XForms Model selector, as defined in3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is themodel associated with the in-scope evaluation context node.
10.13 The reset Element
This action initiates reset processing by dispatching anxforms-reset event to the specifiedmodel. Processing of eventxforms-reset is defined in the processing model—see4.3.5 The xforms-reset Event.
Common Attributes:Common,Events,Action Common
Special Attributes:
- model
Author-optional XForms Model selector, as defined in3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is themodel 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 theresource attribute or thename child element. Individually, the Single Node Binding,resource element andresource 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 theresource attribute orresource 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 theload element and the remote resource indicated. No XLinkactuate value is defined, since control of actuation is defined by XML Events. The XLinkshow value depends on theshow 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 theshow attribute. The following are the possible values for theshow 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.14.1 The resource Element child of load
When it appears as the first child element ofload, theresource element provides the URI of the link, overriding theresource attribute. As stated above, theload action has no effect if both aresource and a Single Node Binding are given. This element allows the URI used by theload to be dynamically calculated based on instance data.
Common Attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain theURI, the result of the expression is processed as if by call to the XPathstring function.An empty string is used if the XPath evaluation fails.
Content: PCDATA
The URI to be used by theload can be specified with either thevalue attribute or the string content of theresource element. If both are specified, then thevalue attribute takes precedence. If theload does not have aresource element as its first child, then the URI is obtained from theresource attribute or the Single Node Binding, if given.
10.15 The send Element
This action initiates submit processing by dispatching anxforms-submit event. Processing of eventxforms-submit is defined in the processing model—see4.3.9 The xforms-submit Event.
Common Attributes:Common,Events,Action Common
Special Attributes:
- submission
Author-optional attribute containing a reference to asubmission element. If this attribute is given but does not identify asubmission element, then thesend action has no effect. If this attribute is omitted, then the firstsubmission in document order from themodel 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 forQNameButNotNCName 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 themessage action is considered to be created at the time the action occurs. If the message is obtained from the inline content of themessage action, then the output of anyoutput controls in themessage content is determined based on the instance data available when themessage action occurs. For example, the following example displays the messageHello, 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 themessage action are not guaranteed to be updated until the end of thexforms-refresh event processing:
<input ref="birthday"> <label>Enter birthday:</label> <message ev:event="xforms-invalid"><output ref="."/> isn't a valid birthday</message></input>
Note:
Due to deferred update behavior, if amessage action is preceded in an action sequence by other actions that change instance nodes, and the message references nodes that are computationally dependent on the changed nodes, then the form author should invoke therecalculate action before themessage action. Moreover, if the computational dependencies involved nodes that were inserted or deleted, then the form author should invokerebuild prior to therecalculate.
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 ahelp 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 ahint 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
Theif 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 aboolean as if converted with theboolean() function defined by the[XPath 1.0] specification. If the converted result of the expression evaluates tofalse, then the action is not performed. If the converted result istrue, then the action is performed.
If this attribute is applied to an XFormsaction element and the converted result of evaluation isfalse, then all of the actions within theaction element are omitted from the executionof the XForms action sequence that invoked theaction element. If the result istrue,then the contained actions are performed according to the normal processing rules such as deferred update behaviorand applicability of conditional and iterative attributes.
Note:
In actionsinsert anddelete, the attributecontext is evaluated before theif attribute.
Automatic Focus Advancement
Thesetfocus action in each input control is executed only if the node bound to the controlis a number of a particular length. The exacting form author could perform further validity tests.
...<input ref="areaCode" incremental="true"><label>Area Code</label><setfocus ev:event="xforms-value-changed" control="ExchangeControl" if="string-length(.)=3 and . > 0"/></input><input ref="exchange" incremental="true"><label>Exchange</label><setfocus ev:event="xforms-value-changed" control="LocalControl" if="string-length(.)=3 and . > 0"/></input><input ref="local" incremental="true"><label>Local</label><setfocus ev:event="xforms-value-changed" control="ExtensionControl" if="string-length(.)=4 and . > 0"/></input>...
Handling Focus for Empty Repeats
The trigger that performs a delete conditionally sets the focus to a control outside of the repeat ifthe repeat becomes empty due to the deletion. Thesetfocus is called first because thedelete removes the context node.
...<trigger><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">...<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
Thewhile 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 aboolean as if converted with theboolean() function defined by the[XPath 1.0] specification. If the converted result of the expression istrue, 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 tofalse.
If this attribute is applied to an XFormsaction 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 oftrue.
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 theif attribute, then the expressions of both attributes must evaluate totrue before each iterative execution of the action.
Note:
In actionsinsert anddelete, the attributecontext is evaluated before thewhile attribute. Therefore,context is re-evaluated before each iteration of the actions controlled by thewhile attribute.
Summing Selected Results
Counter and accumlator variables are created in instance data to sum a selection of values chosen by the user
<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 The XForms Submission Module
XForms is designed to gatherinstance data, serialize it into an external representation, and submit it with a protocol. XForms defines a set of options for serialization and submission. The following sections define the processing of instance data for submission, and the behavior for the serialization and submission options.
11.1 The submission Element
Thesubmission element represents declarative instructions on what to submit, and how.
| Element | Overview of Attributes | Overview of Content Model |
|---|
| submission | Common
ref (binding-expression)
bind (xsd:IDREF)
resource (xsd:anyURI)
action (xsd:anyURI) [deprecated]
mode ("asynchronous"|"synchronous")
method ("post"|"get"|"put"|"delete"|"multipart-post"|"form-data-post"|"urlencoded-post"|Any otherNCName|QNameButNotNCName)
validate (xsd:boolean)
relevant (xsd:boolean)
serialization ("application/xml"|"application/x-www-form-urlencoded"|"multipart/related"|"multipart/form-data"|"none")
version (xsd:NMTOKEN)
indent (xsd:boolean)
mediatype (xsd:string)
encoding (xsd:string)
omit-xml-declaration (xsd:boolean)
standalone (xsd:boolean)
cdata-section-elements (QNameList)
replace ("all"|"instance"|"text"|"none" |QNameButNotNCName)
instance (xsd:IDREF)
targetref (nodeset XPath Expression)
separator (';' | '&')
includenamespaceprefixes (xsd:NMTOKENS)
| (resource |method |header)*,Action* |
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 theresource element, which can dynamically specify the URI based on instance data, or theaction attribute. This attribute should be used in place of theaction 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 theresource attribute, this attribute is deprecated and optional. However, the destination URI must be specified by this attribute or by either theresource attribute or theresource element.
- ref
Author-optional selectorbinding 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 abind element. When present, the binding reference on this attribute is used in preference to any binding reference from theref 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 eventxforms-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 eventxforms-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 attributemethod or the elementmethod must be specified. See Section11.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 ofserialization 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 ofserialization 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 submissionmethod as described in Section11.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:
Settingserialization to "none" will also have the default effect of preventing relevance pruning and validation. However, the author is free to override this by settingrelevant and/orvalidate attributes to "true".
- version
Author-optional attribute specifying theversion 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 asapplication/xml for posted XML data. The default is "application/xml".
Note:
This attribute does not affect serialization and cannot be used to override theserialization attribute. It is only used to provide additional information about the submission data serialization when the serialization isapplication/xml. For example, this attribute could be used to indicate that the content type of the XML serialization istext/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 theomit-xml-declaration attribute has the valuetrue, 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 thereplace 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 thesubmission element is used to evaluate the expression. Ifreplace is "instance", then the target node is replaced by the submission result. Ifreplace is "text", then the content of the target node is replaced by the submission result. For other values of thereplace attribute, this attribute is ignored. By default, the target node is the document element of the instance indicated by theinstance 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 elementsubmission can affect serialization asapplication/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 theincludenamespaceprefixes 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 neededmy 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 theoutput element of[XSLT 1.0], with the exception of usingxsd:boolean to replace"yes"|"no":
version
indent
encoding
omit-xml-declaration
cdata-section-elements
Note:
The following XSLT attributes have no counterpart in XForms:
doctype-system
doctype-public
The table below provides an overview of the child elements of the XFormssubmission element, including their attributes and content models. Elements defined in the XForms Actions module are also allowed in the content model ofsubmission.
| Element | Overview of Attributes | Overview of Content Model |
|---|
| resource | value (string XPath Expression) | PCDATA |
| method | value (string XPath Expression) | PCDATA |
| header | nodeset (nodeset XPath Expression) | name, value+ |
| Action | various | various |
11.2 The xforms-submit Event
Target:submission
Bubbles: Yes
Cancelable: Yes
Context Info: None
Under no circumstancescan more than a single concurrent submit process be under way for a particular XForms submission. From the start of the default action ofxforms-submit for asubmission, until immediately beforexforms-submit-done orxforms-submit-error is dispatched to thatsubmission, the default action for subsequentxforms-submit events dispatched to thatsubmission is to dispatchxforms-submit-error to that submission with context information containing anerror-type ofsubmission-in-progress.
Otherwise, the default action for this event results in the following steps:
The data model is updated based on some of the flags defined fordeferred updates.. Specifically, if the deferred updaterebuild flag is set for themodel containing thissubmission, then the rebuild operation is performed without dispatching an event to invoke the operation. Then, if the deferred updaterecalculate flag is set for themodel containing thissubmission, then the recalculate operation is performed without dispatching an event to invoke the operation. This sequence of operations affects thedeferred update behavior by clearing the deferred update flags associated with the operations performed.
If the binding attributes ofsubmission indicate an empty nodeset or anode other than an element or an instance document root node, then submission processing is stopped after dispatching eventxforms-submit-error with context information containing anerror-type ofno-data. Otherwise, the binding attributes ofsubmission indicate a node of instance data.
The indicated node and all nodes for which it is an ancestor are selected. If the attributerelevant istrue, whether by default or declaration, then any selected node which is not relevant as defined in6.1.4 The relevant Property is deselected (pruned). If all instance nodes are deselected, then submission processing is stopped after dispatching eventxforms-submit-error with context information containing anerror-type ofno-data.
If the attributevalidate istrue,whether by default or declaration, then all selected instance data nodes are checked for validity according to the definition in4.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 eventxforms-submit-error with context information containing anerror-type ofvalidation-error.
Thesubmission method is determined.
Thesubmission resource is determined. If the resource is not specified, then submission processing stops after dispatching evenxforms-submit-error with context information containing anerror-type ofresource-error.
If theserialization attribute value is"none", then the submission data serialization is the empty string. Otherwise, the submission data serialization is determined as follows. The eventxforms-submit-serialize is dispatched. If thesubmission-body property of the event is changed from the initial value of empty string, then the content of thesubmission-body property string is used as thesubmission data serialization. Otherwise, thesubmission data serialization consists of a serialization of the selected instance data according to the rules stated in11.9 Submission Options.
Thesubmission headers are determined using the header entries produced by theheader element(s) in the submission and themediatype attribute or its default.
The submission is performed based on thesubmission headers,submission method,submission resource, andsubmission data serialization. The exact rules of submission are based on the URI scheme and thesubmission method, as defined in11.9 Submission Options.
Note:
Asubmission with no resource specification can be used to test validity of data. If the selected data is invalid, then thexforms-submit-error has anerror-type ofvalidation-error. If the selected data is valid, then thexforms-submit-error has anerror-type ofresource-error.
If themode of thesubmission isasynchronous, 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 themode of thesubmission issynchronous, 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 thereplace attribute on elementsubmission is "all", the eventxforms-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 thereplace attribute on elementsubmission is "instance", the response is parsed as XML. If the parse fails, then submission processing concludes after dispatchingxforms-submit-error with appropriate context information, including anerror-type ofparse-error. However, if the XML parse succeeds, then instance data replacement is performed according to the rules specified in11.10 Replacing Data with the Submission Response. This operation may fail for a number of reasons, including if processing of thetargetref attribute yields a readonly node (ifreplace="text") or a node that either has a readonly parent or is not an element (ifreplace="instance"). In this case, submission ends after dispatching eventxforms-submit-error with appropriate context information, including anerror-type oftarget-error. Otherwise, the instance data replacement succeeds. Submission processing then concludes after dispatchingxforms-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 thereplace attribute on elementsubmission is "instance", nothing in the document is replaced and submission processing concludes after dispatchingxforms-submit-error with appropriate context information, including anerror-type ofresource-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 oftext/*), when the value of thereplace attribute on elementsubmission is "text", the response is encoded as text. Then, the content replacement is performed according to the rules specified in11.10 Replacing Data with the Submission Response. If the processing of thetargetref attribute (including its default) fails, then the submission processing concludes after dispatchingxforms-submit-error with appropriate context information, including anerror-type oftarget-error. Otherwise, submission processing then concludes after dispatchingxforms-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 matchingtext/*), when the value of thereplace attribute on elementsubmission is "text", nothing in the document is replaced and submission processing concludes after dispatchingxforms-submit-error with appropriate context information, including anerror-type ofresource-error.
For a success response including a body, when the value of thereplace attribute on elementsubmission is "none", submission processing concludes after dispatchingxforms-submit-done with appropriate context information.
For a success response not including a body, submission processing concludes after dispatchingxforms-submit-done with appropriate context information.
Behaviors of other possible values for attributereplace are not defined in this specification.
For an error response, when the value of thereplace attribute on elementsubmission is "all", either the document is replaced with an implementation-specific indication of an error or submission processing concludes after dispatchingxforms-submit-error with appropriate context information, including anerror-type ofresource-error.
For an error response, when the value of thereplace attribute on elementsubmission is not "all", nothing in the document is replaced, and submission processing concludes after dispatchingxforms-submit-error with appropriate context information, including anerror-type ofresource-error.
In addition to initiating a submission with its default processing, XForms actions can also provide handlers for thexforms-submit event to peform tasks such as data preparation.
Example:
Preparing data for submission
<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>The schema for the doctor search service requires certain portions of the patient record in order to provide a list of specialists who could treat the patient. The server-side module may perform database searches for doctors with the required specialties as well as implement business rules such as providing doctors that are within an acceptable distance of the given city. The resulting list is provided to a separate instance so it can be presented to the user for selection or used in subsequent availability searches.
11.3 The xforms-submit-serialize Event
Dispatched at the beginning ofsubmission serialization (see11.2 The xforms-submit Event).
Target:submission
Bubbles: Yes
Cancelable: No
Context Info:
| Property | Type | Value |
|---|
| submission-body | node-set | A document element node with a QName ofsubmission-body. The node initially contains an empty string. Event handlers can write data into the node. If the string value of this node is non-empty, then the string value is used in the submission in lieu of the default instance data serialization. |
Note:
Thesubmission-body property is a string, but theevent() function encapsulates the string in a text node so that the string can be modified by thesetvalue action, which sets a value into a node determined by its Single Node Binding.
Note:
Since thesubmission-body is a string, this feature may be used to submit non-XML data.
Default Action: If the event contextsubmission-body property string is empty, then no operation is performed so that thesubmission will use the normal serialization data(see11.2 The xforms-submit Event). Otherwise, if the event contextsubmission-body property string is non-empty, then the serialization data for thesubmission is set to be the content of thesubmission-body string.
Example:
Submitting plain text
<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>The string value of the elementmy/text is placed into the node representing the submission body, so that is the text posted by the submission. In this example, the result returned by the submission replaces the document. This feature could be used to submit plain text, but it could also be used to allow a document to submit its serialization rather than just submitting instance data.
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:
| Property | Type | Value |
|---|
| resource-uri | string | The submission resource URI that succeeded (xsd:anyURI) |
| response-status-code | number | The protocol return code of the success response, orNaN if the submission did not receive a success response. |
| response-headers | node-set | Zero or more elements, each one representing a content header in the success response received by the submission. The returned node-set is empty if the submission did not receive a response or if there were no headers. Each element has a local name ofheader with no namespace URI and two child elements,name andvalue, whose string contents are the name and value of the header, respectively. |
| response-reason-phrase | string | The protocol response reason phrase of the success response. The string is empty if the submission did not receive a response or if the response did not contain a reason phrase. |
Default Action: None; notification event only.
Example:
Submission Sequencing
<submission resource="https://example.com/getRecord" method="post" replace="instance" instance="record"> <send ev:event="xforms-submit-done" submission="chargeForRecord"/> </submission><submission resource="https://example.com/chargeForRecord" method="get" serialization="none" replace="none"/>
The default instance data is submitted as the search criteria for a desired record. Only upon successful completion of the submission is a second submission performed to charge the user's account for the record.
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:
| Property | Type | Value |
|---|
| error-type | string | One of the following:submission-in-progress,no-data,validation-error,parse-error,resource-error,target-error. |
| resource-uri | string | The submission resource URI that failed (xsd:anyURI) |
| response-status-code | number | The protocol return code of the error response, orNaN if the failed submission did not receive an error response. |
| response-headers | node-set | Zero or more elements, each one representing a content header in the error response received by a failed submission. The returned node-set is empty if the failed submission did not receive an error response or if there were no headers. Each element has a local name ofheader with no namespace URI and two child elements,name andvalue, whose string contents are the name and value of the header, respectively. |
| response-reason-phrase | string | The protocol response reason phrase of the error response. The string is empty if the failed submission did not receive an error response or if the error response did not contain a reason phrase. |
| response-body | object (string or node-set) | When the error response specifies an XML media type as defined by[RFC 3023], the response body is parsed into an XML document and the root element of the document is returned. If the parse fails, or if the error response specifies a text media type (starting withtext/), then the response body is returned as a string. Otherwise, an empty string is returned. |
Default Action: None; notification event only.
Example:
Reporting a Submission Error
<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>The default instance data is submitted as the search criteria for a desired record. Only upon successful completion of the submission is a second submission performed to charge the user's account for the record.
11.6 The Submission Resource
Thesubmission resource is the URI for the submission. It is of typexsd:anyURI.
In XForms 1.0, the URI for submission was provided by theaction attribute. For consistency, form authors should now use the attributeresource of typexsd:anyURI, which deprecates theaction attribute. If bothaction andresource are present, then theresource attribute takes precedence.
Theresource element provides the submission URI, overriding theresource attribute and theaction attribute. If asubmission has more than oneresource child element, the firstresource element child must be selected for use. Individually, theresource element, theresource attribute and theaction attribute are not required. However, one of the three is mandatory as there is no default submission resource.
11.6.1 The resource Element
Theresource element allows the URI used for a submission to be dynamically calculated based on instance data.
Common Attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the URI, the result of the expression is processed as if by call to the XPathstring function. An empty string is used if the XPath evaluation fails.
Content: PCDATA
The URI to be used by thesubmission can be specified with either thevalue attribute or the string content of theresource element. If both are specified, then thevalue attribute takes precedence. If thesubmission does not have aresource child element, then the submission URI is obtained from theresource attribute or theaction attribute.
Example:
Submitting the default instance to a location determined dynamically from an instance
<submission method="post"> <resource value="instance('params')/anyURI"/> </submission>11.7 The Submission Method
Thesubmission method indicates the submission protocol operation to be performed.
The submission method may be specified by themethod attribute. Thesubmission element can have a child element namedmethod, which overrides the submission method setting obtained from themethod attribute if both are specified. If more than onemethod element is given, the first occurrence in document order must be selected for use. Individually, themethod element and themethod attribute are not required. However, one of the two is mandatory as there is no default submission method.
11.7.1 The method Element
Themethod element allows the submission method to be dynamically calculated based on instance data.
Common Attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the method, the result of the expression is processed as if by call to the XPathstring function. An empty string is used if the XPath evaluation fails.
Content: PCDATA
The method to be used by thesubmission can be specified with either thevalue attribute or the string content of themethod element. If both are specified, then thevalue attribute takes precedence. If thesubmission does not have amethod child element, then the submission method is obtained from themethod attribute.
11.8 The header Element
Theheader element can be used to contribute information to the preamble of a submission in a manner appropriate to the protocol. Thesubmission element can contain zero or moreheader 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 elementheader with other entries produced by otherheader 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 theheader element does not contain anodeset attribute, then one header entry is created for eachvalue element. If theheader element contains anodeset attribute, then for each selected node, one header entry is created for eachvalue element. The name and value of the header entry are obtained from the required child elementsname (11.8.1 The name Element) andvalue (11.8.2 The value Element). If the name obtained from thename element is the empty string, then the header entry is omitted.
The header entry order is determined as follows:
document order ofheader elements
node order of nodes innodeset attribute
document order ofvalue elements
The application of this order information to header serialization is determined by the submission protocol.
If aheader element defines theContent-type header, then this setting overrides aContent-type set by themediatype attribute.
In the case of a multipart submission, the header entries are combined with those for the first part of the submission.
Example:
Setting the Accept header
In the example below, the submission request uses theheader element to replace the user agent's existing value of the HTTP Accept header withapplication/sparql-results+xml.
<submission 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.8.1 The name Element
When thename element appears as a child of elementheader, it is used to specify the name of a header entry to be provided to the submission protocol.
Common Attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the header name, the result of the expression is processed as if by call to the XPathstring function. An empty string is used if the XPath evaluation fails.
The header entry name may be given by the string content of thename element, or by the result of thevalue attribute. If both are given, the result from thevalue attribute takes precedence. If the resulting name is the empty string, then the entry is considered to be void, and it is not supplied to the submission protocol.
11.8.2 The value Element
When thevalue element appears as a child of elementheader, it is used to specify the value component of a header entry to be supplied to the submission protocol to be added to the preamble of a submission. Thevalue element may be used more than once in a given elementheader, in which case each value produces a new header entry.
Common Attributes: None
Special Attributes:
- value
Author-optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the header entry value, the result of the expression is processed as if by call to the XPathstring function. An empty string is used if the XPath evaluation fails.
The header entry value may be given by the string content of thevalue element, or by the result of thevalue attribute. If both are given, the result from thevalue attribute takes precedence.
Note:
The XPathstring function combines multiple nodes by concatenating them into a string separated with spaces. As a result, a header value specified by avalue element nodeset containing multiple nodes may not be properly serialized in a submission protocol preamble. To assure proper delivery of individual header items to the submission protocol, restrict use of XPath expressions producing nodesets for elementheader with attributenodeset, where each node will produce its own separate header entry, and use expressions resulting in only a single node in elementvalue.
11.9 Submission Options
The XForms Model specifies asubmission 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 thesubmission resource, XForms normatively defines a binding to HTTP/1.1[RFC 2616].
Note:
Other bindings, in particular to the URI scheme "mailto:" may, and the schemes "https:" and "file:" should, be supported. Bindings to these schemes are not normatively defined in XForms. Implementations that choose to provide a binding to these schemes should pay particular attention to privacy and security concerns. Within the "http:" and "https:" schemes, form creators are encouraged to follow the finding of the W3C Technical Architecture Group on when to use the GET method:[TAG Finding 7]
Thesubmission method determines the default data serialization format, and both thesubmission method and the URI scheme in thesubmission resource determine the submission protocol operation, according to the following table:
| URI scheme | Submission Method | Default Serialization | Submission Protocol Operation |
|---|
| http https mailto | "post" | application/xml | HTTP POST or equivalent |
| http https file | "get" | application/x-www-form-urlencoded | HTTP GET or equivalent |
| http https file | "delete" | application/x-www-form-urlencoded | HTTP DELETE or equivalent |
| http https file | "put" | application/xml | HTTP PUT or equivalent |
| http https mailto | "multipart-post" | multipart/related | HTTP POST or equivalent |
| http https mailto | "form-data-post" | multipart/form-data | HTTP POST or equivalent |
| http https mailto | "urlencoded-post" | application/x-www-form-urlencoded | HTTP POST or equivalent |
| (any) | Any otherNCName | application/xml | As given by theSubmission Method |
| (any) | QNameButNotNCName | implementation-defined | implementation-defined |
Note:
Foreign-namespaced attribute values are allowed in theSubmission Method, but no behavior is defined by XForms.
11.9.1 The get Submission Method
This submit method represents HTTP GET or the equivalent concept. The serialized form data is delivered as part of the URI that is requested during the submit process.
This method is not suitable for submission of forms that are intended to change state or cause other actions to take place at the server. See[RFC 2616] for recommended uses of HTTP GET.
The URI is constructed as follows:
The submit URI is examined. If it does not already contain a? (question mark) character, one is appended. If it does already contain a question mark character and the serialized form data is non-empty, then a separator character from the attributeseparator is appended.
The serialized form data, if any, is appended to the URI.
No message body is sent with the request.
Examples:
Simple search submission
<submission resource="http://example.com/search" method="get"/>
After doing relevance and validity checking on the data, the leaf nodes of the default instance are submitted asynchronously, encoded as a URL (application/x-www-form-urlencoded), tohttp://example.com/search. The result replaces the whole page.
Reading from a local file
<submission resource="file:data.xml" method="get" serialization="none" replace="instance" instance="data" />
Replaces the instance 'data' with the content of the file data.xml. Serialization, and its associated validity and relevance processing, is not needed. See the corresponding example for saving a file in Section11.9.3 The put Submission Method. The user agent may restrict file access to a user-specific and domain-specific security zone in local storage.
11.9.2 The post, multipart-post, form-data-post, and urlencoded-post Submission Methods
These submit methods represent HTTP POST or the equivalent concept (such as a mail message). The serialized form data is delivered as the message body.
Examples:
Posting instance data
<submission resource="https://example.com/jsp/orders" method="post" ref="/purchaseOrder" />
Submits the XML for a purchase order to a secure server order processing system.
Simple posted login
<submission resource="http://example.com/login" method="urlencoded-post"/>
After doing relevance pruning and validity checking on the login data, the leaf nodes of the default instance are submitted asynchronously in the posted data, encoded based on theapplication/x-www-form-urlencoded serialization, tohttp://example.com/login. The result replaces the whole page.
11.9.3 The put Submission Method
This submit method represents HTTP PUT or the equivalent concept (such as writing to a local file). The serialized form data is delivered as the message body.
Example:
Saving to a local file
<submission resource="file:data.xml" ref="instance('data')" method="put" validate="false" relevant="false" replace="none" />Saves the instance 'data' to the file data.xml without validation checking and relevance pruning. See the corresponding example for reading from a local file in Section11.9.1 The get Submission Method. The user agent may restrict file access to a user-specific and domain-specific security zone in local storage.
11.9.4 The delete Submission Method
This submit method represents HTTP DELETE or the equivalent concept (such as deleting a local file). The serialized form data is delivered in the same manner as theget submission method (see11.9.1 The get Submission Method).
11.9.5 Serialization as application/xml
This format permits the expression of the instance data as XML that is straightforward to process with off-the-shelf XML processing tools. In addition, this format is capable of submission of binary content.
The steps for serialization are as follows:
An XML document is produced following the rules of the XML output method defined in[XSLT 1.0] section 16 and 16.1, using the values supplied as attributes of thesubmission element.
Handling of namespace nodes: The default behavior is that every namespace node is serialized according to the rules of the XML output method, so that at least one namespace declaration appears in the serialized XML for each in-scope namespace. Additional inherited namespaces are declared on the root element of the serialized XML. If, however, attributeincludenamespaceprefixes on elementsubmission is present, then all namespace declarations not visibly utilized in the instance data (as defined in[Exc-C14N]) and the default namespace if it is empty are excluded from the root element serialization, unless the corresponding namespace prefix is listed in theincludenamespaceprefixes attribute. The special value#default represents the default namespace.
Mediatype: By default, the mediatype of the serialized XML instance isapplication/xml, but can be changed to a compatible type using elementsubmission attributemediatype. Authors should ensure that the type specified is compatible withapplication/xml.
11.9.6 Serialization as multipart/related
This format is intended for integration of XForms into environments that involve large amounts of binary data where the inclusion of the data asxsd:base64Binary orxsd:hexBinary is undesirable.
In this format, XML instance data is serialized as one part of the[RFC 2387]multipart/related message, using the rules as described in11.9.5 Serialization as application/xml. Binary content fromxsd:anyURI instance nodes populated by theupload (see8.1.6 The upload Element) control is serialized in separate parts of the[RFC 2387]multipart/related message.
This format follows the rules ofmultipart/related MIME data streams for in[RFC 2387], with specific requirements of this serialization listed below:
multipart/related message header requirements:
First body part (root) requirements:
Subsequent part requirements:
multipart/related
<submission method="multipart-post" resource="http://example.com/photo" />
Submits the instance data inmultipart/related, along with the selected file as an attachment.
POST /photo HTTP/1.0Host: example.comContent-Type: multipart/related; boundary=f93dcbA3; type=application/xml; start="<980119.X53GGT@example.com>"Content-Length: xxx--f93dcbA3Content-Type: application/xml; charset=UTF-8Content-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>--f93dcbA3Content-Type: image/pngContent-Transfer-Encoding: binaryContent-ID: <980119.X25MNC@example.com>...Binary data here...--f93dcbA3Content-Type: image/pngContent-Transfer-Encoding: binaryContent-ID: <980119.X17AXM@example.com>...Binary data here...--f93dcbA3--
11.9.7 Serialization as multipart/form-data
This format is for legacy compatibility to permit the use of XForms clients with[RFC 2388] servers. This method is suitable for the persistence of binary content. Contextual path information, attribute values, namespaces and namespace prefixes are not preserved. As a result, different elements might serialize to the same name.
Note:
Existing HTML user agents fail to encode special characters (such as double quotes) and non-ASCII characters in theContent-Disposition: form-dataname andfilename parameters. Since this serialization method is supported for legacy applications only, new applications should useapplication/xml ormultipart/related.
This format follows the rules formultipart/form-data MIME data streams in[RFC 2388], with specific requirements of this serialization listed below:
Each element node is visited in document order, except non-relevant elements are skipped if therelevant setting of thesubmission istrue.
Each visited element that has no child element nodes (i.e., each leaf element node) is selected for inclusion, including those that have no value (no text node).
Element nodes selected for inclusion are encoded asContent-Disposition: form-data MIME parts as defined in[RFC 2388], with thename parameter being the element local name.
Element nodes of any datatype populated byupload also have aContent-Dispositionfilename parameter, if the filename is available.
Element nodes of any datatype populated byupload are serialized as the specified binary content. In the case ofxsd:anyURIand derived types, the serialization content is obtained from the URI. Forxsd:base64Binary,xsd:hexBinary, and derived types, the serialization content is obtained by decoding the element string value.
Element nodes of any datatype not populated byupload are serialized as the string value of the element (the concatenation of all text node children, or empty string if the element has no text node children).
TheContent-Type must betext/plain except forxsd:anyURI,xsd:base64Binary,xsd:hexBinary, and derived types, in which case the header represents the media type of the attachment if known, otherwiseapplication/octet-stream. If a character set is applicable, theContent-Type may have acharset parameter.
Example:
multipart/form-data
<submission method="form-data-post" resource="http://example.com/photo" />
Submits the instance data inmultipart/form-data, along with the selected file as a part.
POST /photo HTTP/1.0Host: example.comContent-Type: multipart/form-data; boundary=AaB03xContent-Length: xxx--AaB03xContent-Disposition: form-data; name="document"; filename="b.txt"Content-Type: text/plain; charset=iso-8859-1This is a file.It has two lines.--AaB03xContent-Disposition: form-data; name="title"A File--AaB03xContent-Disposition: form-data; name="summary"This is my filefile test--AaB03x--
11.9.8 Serialization as application/x-www-form-urlencoded
This format represents an extension of the[XHTML 1.0] form content typeapplication/x-www-form-urlencoded with specific rules for encoding non-ASCII and reserved characters.
This format is not suitable for the persistence of binary content. Therefore, it is recommended that forms capable of containing binary content use another serialization method.
The steps for serialization are as follows:
Each element node is visited in document order, except non-relevant elements are skipped if therelevant setting of thesubmission istrue. Each visited element that has no child element nodes (i.e., each leaf element node) is selected for inclusion, including those that have no value (no text node).Note that attribute information is not preserved.
Element nodes selected for inclusion are encoded asEltName=value, where= is a literal character,EltName represents the element local name, andvalue represents the string value of the element (the concatenation of all text node children, or empty string if the element has no text node children). The separator character {sep} from theseparator attribute onsubmission is used between pairs of encoded name/value pairs, e.g.EltName1=value1{sep}EltName2=value2{sep}EltName3=value3. Note that contextual path information is not preserved, nor are namespaces or namespace prefixes. As a result, different elements might serialize to the same name.
The encoding ofEltName andvalue are as follows: space characters are replaced by+, and then non-ASCII and reserved characters (as defined by[RFC 2396] as amended by subsequent documents in the IETF track) are escaped by replacing the character with one or more octets of the UTF-8 representation of the character, with each octet in turn replaced by%HH, whereHH represents the uppercase hexadecimal notation for the octet value and% is a literal character. Line breaks are represented as "CR LF" pairs (i.e.,%0D%0A).
All such encodings are concatenated, maintaining document order.
Example:
application/x-www-form-urlencoded
This format consists of simple name-value pairs.
<PersonName title="Mr"> <GivenName>René</GivenName></PersonName>
Here is the instance data for the above example. Note that very little of the data is preserved. Authors desiring greater data integrity should select a different serialization format.
11.10 Replacing Data with the Submission Response
Thesubmission element allows an author-optional attribute namedtargetref. The attribute value is interpreted asabinding expression to which the first node rule is applied to obtain areplacement target node for the submission response. This attribute is ignored unless the value of thereplace attribute is "instance" or "text".
For backwards compatibility with documents created for earlier versions of the specification, the processor of thesubmission elementmay allow the author-optional attribute namedtarget to be used. Thetarget attribute provides exactly the same behaviors as thetargetref attribute except that thetarget attribute is ignored if thesubmission element also bears atargetref attribute.
The default replacement target node is the document element node of the instance identified by theinstance attribute, whichis equal to the default instance of the model if not specified. The evaluation context for this attribute is the in-scope evaluation contextfor thesubmission element, except the context node is modified to be the document element of the instance identified by theinstance attribute if it is specified.
This attribute is evaluated only once a successful submission response has been received and if thereplace attributevalue is "instance" or "text". The first node rule is applied to the result.
The processing of thetargetref attribute (and its default) is considered to have failed if the result is any of the following:
an empty nodeset
a readonly node, ifreplace="text"
a non-element, ifreplace="instance"
a node whose parent is readonly, ifreplace="instance"
If the processing of thetargetref attribute fails, then submission processing ends after dispatching the eventxforms-submit-error with anerror-type oftarget-error.
If thereplace attribute contains the value "text" and the submission response conforms to an XML mediatype (as defined by the content type specifiers in[RFC 3023]) ora text media type (as defined by a content type specifier oftext/*), then the response data is encoded as text and replaces thecontent of the replacement target node.
If thereplace 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 commentand processing instruction nodes before and after the document element. These nodes are discarded if the replacement target nodeis not the document element of an instance. Otherwise, those processing instructions and comments replace any processing instructionsand 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 Actionsetvalue (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 thatare performed by theinsert action (10.3 The insert Element) and thedelete action (10.4 The delete Element).If thesubmission has amode of "asynchronous", then the text replacement action or the instance node replacement action is an outermost action handler, so thedeferred update behavior occurs at the end of the action. If themode is "synchronous", then the text replacement action or the instance node replacement action is not outermost since occurs during the default processing ofxforms-submit, so the appropriatedeferred update flags are set based on whether the action was asetvalue or whether it performeda series ofinsert anddelete actions.
Note:
In an asynchronous submission, the deferred update behavior ensures that the user interface is up to date with the latest calculated values before thexforms-submit-done event is dispatched. In a synchronous submission, the calculated values dependent on replaced text or data nodes can be made available to actions in thexforms-submit-done handler by first invoking therecalculate action. A sequence of synchronous submissions performed with successivesend actions can avoid refreshing the user interface until after the completion of the lastsend action.
Examples:
Replacing a subtree of instance data
<submission resource="http://example.com/jsp/prefill" method="post" ref="name" replace="instance" targetref="address"/>
This submission would be invoked after the user enters a value forname. Based on the name given, a simple server-side database lookup is performed to get a last known address. Theaddress element is replaced with the result, prefilling part of the form for the user.
Replacing text in an instance
<submission resource="http://example.com/postalCodeSearch" method="get" ref="address" replace="text" targetref="address/postalCode"/>
The address information is past to a postal code search service that returns a textual result, which is placed into thepostalCode element.
Submission and Read-Only Content
<model xmlns:my="http://example.org"> <instance> <my:data> <my:name> <my:first-name>John</my:first-name> <my:last-name>Doe</my:last-name> </my:name> <my:address> <my:street>123 Main St.</my:street> <my:city>Smallville</my:city> </my:address> </my:data> </instance> <bind nodeset="/my:data/my:name/" readonly="true()"/> <bind nodeset="/my:data/my:address/my:street" readonly="true()"/> <submission targetref="my:name" replace="instance" method="post" resource="..."/> <submission targetref="my:name/my:first-name" replace="instance" method="post" resource="..."/> <submission targetref="my:name/my:first-name" replace="text" method="post" resource="..."/> <submission targetref="my:address/my:street" replace="text" method="post" resource="..."/></model>
Submission S1 succeeds because a readonly node (my:name) can be replaced if its parent is not readonly.Submission S2 fails because a node (my:first-name) cannot be replaced if its parent is readonly.Submission S3 fails because the content of a readonly node cannot be replaced, even if it is readonly due to inheritance.Submission S4 failse because the content of a readonly node cannot be replaced, even if the node's parent is not readonly.
11.11 Integration with SOAP
This section describes the integration of XForms submission with[SOAP 1.1] and[SOAP 1.2]
11.11.1 Representation of SOAP Envelope
The single-node binding of thesubmission element refers to the XML data to be submitted. In the case of a SOAP submission, the instance data includes the SOAP envelope and related SOAP tags.
Note:
The form author may choose to store the data payload in one instance and copy the data to the submission instance containing the SOAP envelope as part of anxforms-submit event handler. The form author is responsible for declaring the appropriate model item properties on both instances (e.g. therelevant declarations).
11.11.2 Indicating a SOAP submission
For a SOAP submission, themediatype attribute of thesubmissionmust be set to the MIME type ofapplication/soap+xml. The form author may appendcharset andaction MIME parameters.
Note:
Theaction MIME parameter has no effect unless the submissionmethod is "post" because the GET method implies no SOAP processing by the receiving SOAP node.
Note:
SOAP 1.1 does not support the HTTP GET operation.
11.11.3 SOAP HTTP Binding
Themethod attribute of thesubmissionmust be set toget orpost in order to access the SOAP HTTP binding.
Ifmethod="get", then the SOAP response message exchange pattern is used. The HTTP headersmust contain the Accept parameter with a value conforming to the following properties:
must begin withapplication/soap+xml
If the submissionmediatype contains acharset MIME parameter, then it is appended to theapplication/soap+xml MIME type. Otherwise, acharset MIME parameter with same value as theencoding attribute (or its default) is appended to theapplication/soap+xml MIME type.
No other MIME parameters from themediatype are copied to theapplication/soap+xml MIME type
Theq MIME parametermust not be specified in theapplication/soap+xml MIME type so that the default quality of 1 is used.
Ifmethod="post", then the SOAP request-response message exchange pattern is used. For SOAP 1.2, the current submission behavior of using themediatype attribute value as the value of theContent-type parameter in the HTTP headers is sufficient. If the instance data being submitted has as its root element node a SOAP envelope in the SOAP 1.1 namespace (http://schemas.xmlsoap.org/soap/envelope/), then:
theContent-type HTTP header is changed totext/xml
thecharset MIME parameter is appended . The charset parameter value from themediatype attribute is used if it is specified. Otherwise, the value of theencoding attribute (or its default) is used.
if theaction MIME parameter appears in themediatype then a SOAPAction HTTP header is added and given a value equal to the content of theaction MIME parameter
Note:
XForms 1.1 does not support the SOAP email binding, so method="post" with amailto: scheme results in anxforms-submit-error event before any submit processing message is dispatched.
Note:
XForms 1.1 does not support the SOAP 1.1 binding to the HTTP Extension Framework.
Example:
Consuming a SOAP 1.1 Request-Response Web Service
<xforms:model xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:tns="http://www.webservice.net"> <xforms:instance> <data xmlns=""> <city>Victoria</city> <country>Canada</country> <weather>Mostly sunny and cool. High 12C. Low 3C.</weather> </data> </xforms:instance> <xforms:instance> <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> <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 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>This form accepts input of a city name and country name from the user. When the user changes either value, the 'GetWeather' web service is initiated. Onxforms-submit, the user input is copied into the request envelope. When the web service submission result is received, thexforms-submit-done handler copies the weather forecast from the response envelope to the data instance.
The submission and the request and response instances correspond to the web service definition below:
<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" /> <wsdl:operation name="GetWeather"> <soap:operation soapAction="http://www.webservice.net/GetWeather" /> <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>
11.11.4 Handling the SOAP Response
The XForms processormust handle client authorization and redirection.
SOAP faults (400 and 500 level errors) are handled in the same manner as underlying HTTP errors, which is to say that anxforms-submit-error event is dispatched.
On successful completion, the results are consumed according to the XForms submission process, culminating in anxforms-submit-done event. The form author may capture this event and copy data from the target instance that receives the returned SOAP envelope to other instances that are designed to carry only data.
