This document is also available in these non-normative formats: diff-marked HTML .
The English version of this specification is the only normative version. Non-normative translations may also be available.
Copyright © 2007 W3C® (MIT, ERCIM, Keio), All Rights Reserved. W3C liability, trademark and document use rules apply.
XForms is an XML application that represents the next generation of forms for the Web. XForms is not a free-standing document type, but is intended to be integrated into other markup languages, such as XHTML or SVG. An XForms-based web form gathers and processes XML data using an architecture that separates presentation, purpose and content. The underlying data of a form is organized into instances of data schema (though formal schema definitions are not required). An XForm allows processing of data to occur using three mechanisms:
a declarative model composed of formulae for data calculations and constraints, data type and other property declarations, and data submission parameters
a view layer composed of intent-based user interface controls
an imperative controller for orchestrating data manipulations, interactions between the model and view layers, and data submissions.
Thus, XForms accommodates form component reuse, fosters strong data type validation, eliminates unnecessary round-trips to the server, offers device independence and reduces the need for scripting.
XForms 1.1 refines the XML processing platform introduced by [XForms 1.0] by adding several new submission capabilities, action handlers, utility functions, user interface improvements, and helpful datatypes as well as a more powerful action processing facility, including conditional, iterated and background execution, the ability to manipulate data arbitrarily and to access event context information.
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.
This document is a Last Call Working Draft of the W3C. Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.
The Last Call review period ends on 05 April 2007, 2359Z. Comments received after that date will be considered if time allows, but no guarantees can be offered. Please send comments on this working draft to the public mailing list www-forms-editor@w3.org. (archive). It is inappropriate to send discussion email to this address.
This document has been produced by the W3C XForms Working Group as part of the XForms Activity within the W3C Interaction Domain. The authors of this document are the W3C XForms Working Group participants.
Relative to the previous working draft, this version differs only by the removal of chameleon schemas and by changes
needed to make the insert
and delete
actions insert or delete sets of nodes. Therefore, the
diff-marked HTML
shows the changes made in XForms 1.1 relative to XForms 1.0 Second Edition.
This document is governed by the 24 January 2002 CPP as amended by the W3C Patent Policy Transition Procedure. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.
1 About the XForms Specification
1.1 Background
1.2 Reading the Specification
1.3 How the Specification is Organized
1.4 Documentation Conventions
2 Introduction to XForms
2.1 An Example
2.2 Providing XML Instance Data
2.3 Constraining Values
2.4 Multiple Forms per Document
3 Document Structure
3.1 Namespace for XForms
3.2 XForms Core Attribute Collections
3.2.1 Common Attributes
3.2.2 Linking Attributes
3.2.3 Single-Node Binding Attributes
3.2.4 Node-Set Binding Attributes
3.2.5 Model Item Property Attributes
3.3 The XForms Core Module
3.3.1 The model Element
3.3.2 The instance Element
3.3.3 The submission Element
3.3.4 The bind Element
3.4 The XForms MustUnderstand Module
3.5 The XForms Extension Module
3.5.1 The extension Element
4 Processing Model
4.1 Events Overview
4.2 Initialization Events
4.2.1 The xforms-model-construct Event
4.2.2 The xforms-model-construct-done Event
4.2.3 The xforms-ready Event
4.2.4 The xforms-model-destruct Event
4.3 Interaction Events
4.3.1 The xforms-next and xforms-previous Events
4.3.2 The xforms-focus Event
4.3.3 The xforms-help and xforms-hint Events
4.3.4 The xforms-refresh Event
4.3.5 The xforms-revalidate Event
4.3.6 The xforms-recalculate Event
4.3.7 The xforms-rebuild Event
4.3.8 The xforms-reset Event
4.3.9 The xforms-submit Event
4.3.10 The xforms-submit-serialize Event
4.4 Notification Events
4.4.1 The DOMActivate Event
4.4.2 The xforms-value-changed Event
4.4.3 The xforms-select and xforms-deselect Events
4.4.4 The xforms-scroll-first and xforms-scroll-last Events
4.4.5 The xforms-insert Event
4.4.6 The xforms-delete Event
4.4.7 The xforms-valid Event
4.4.8 The xforms-invalid Event
4.4.9 The DOMFocusIn Event
4.4.10 The DOMFocusOut Event
4.4.11 The xforms-readonly Event
4.4.12 The xforms-readwrite Event
4.4.13 The xforms-required Event
4.4.14 The xforms-optional Event
4.4.15 The xforms-enabled Event
4.4.16 The xforms-disabled Event
4.4.17 The xforms-in-range Event
4.4.18 The xforms-out-of-range Event
4.4.19 The xforms-submit-done Event
4.4.20 The xforms-submit-error Event
4.4.21 The xforms-output-error Event
4.5 Error Indications
4.5.1 The xforms-binding-exception Event
4.5.2 The xforms-link-exception Event
4.5.3 The xforms-link-error Event
4.5.4 The xforms-compute-exception Event
4.5.5 The xforms-version-exception Event
4.6 Event Sequencing
4.6.1 For input, secret, textarea, range, or upload Controls
4.6.2 For output Controls
4.6.3 For select or select1 Controls
4.6.4 For trigger Controls
4.6.5 For submit Controls
4.6.6 Sequence: Selection Without Value Change
4.6.7 Sequence: Value Change
4.6.8 Sequence: Activating a Trigger
4.6.9 Sequence: Submission
4.7 Resolving ID References in XForms
4.7.1 References to Elements within a repeat Element
4.7.2 References to Elements within a bind Element
5 Datatypes
5.1 XML Schema Built-in Datatypes
5.2 XForms Datatypes
5.2.1 xforms:listItem
5.2.2 xforms:listItems
5.2.3 xforms:dayTimeDuration
5.2.4 xforms:yearMonthDuration
5.2.5 xforms:email
5.2.6 xforms:ID-card-number
5.2.7 XForms Datatypes to Allow Empty Content
6 Model Item Properties
6.1 Model Item Property Definitions
6.1.1 The type Property
6.1.2 The readonly Property
6.1.3 The required Property
6.1.4 The relevant Property
6.1.5 The calculate Property
6.1.6 The constraint Property
6.1.7 The p3ptype Property
6.2 Schema Constraints
6.2.1 Atomic Datatype
7 XPath Expressions in XForms
7.1 XPath Datatypes
7.2 Feature string for the hasFeature method call
7.3 Instance Data
7.3.1 The getInstanceDocument() Method
7.3.2 The rebuild() Method
7.3.3 The recalculate() Method
7.3.4 The revalidate() Method
7.3.5 The refresh() Method
7.4 Evaluation Context
7.5 Binding Expressions
7.5.1 Dynamic Dependencies
7.5.2 Model Binding Expressions
7.5.3 UI Binding Expressions
7.5.4 UI Binding in other XML vocabularies
7.5.5 Binding Examples
7.6 The XForms Function Library
7.7 Boolean Functions
7.7.1 The boolean-from-string() Function
7.7.2 The if() Function
7.8 Number Functions
7.8.1 The avg() Function
7.8.2 The min() Function
7.8.3 The max() Function
7.8.4 The count-non-empty() Function
7.8.5 The index() Function
7.8.6 The power() Function
7.8.7 The luhn() Function
7.8.8 The random() Function
7.9 String Functions
7.9.1 The property() Function
7.9.2 The encode() Function
7.9.3 The decode() Function
7.9.4 The digest() Function
7.9.5 The hmac() Function
7.10 Date and Time Functions
7.10.1 The now() Function
7.10.2 The days-from-date() Function
7.10.3 The days-to-date() Function
7.10.4 The seconds-from-dateTime() Function
7.10.5 The seconds-to-dateTime() Function
7.10.6 The local-date() Function
7.10.7 The local-dateTime() Function
7.10.8 The seconds() Function
7.10.9 The months() Function
7.11 Node-set Functions
7.11.1 The instance() Function
7.11.2 The current() Function
7.11.3 The choose() Function
7.11.4 The id() Function
7.11.5 The event() Function
7.12 Extension Functions
8 Form Controls
8.1 The XForms Form Controls Module
8.1.1 Implementation Requirements Common to All Form Controls
8.1.2 The input Element
8.1.3 The secret Element
8.1.4 The textarea Element
8.1.5 The output Element
8.1.6 The upload Element
8.1.7 The range Element
8.1.8 The trigger Element
8.1.9 The submit Element
8.1.10 The select Element
8.1.11 The select1 Element
8.2 Common Markup for Selection Controls
8.2.1 The choices Element
8.2.2 The item Element
8.2.3 The value Element
8.3 Additional Elements
8.3.1 The filename Element
8.3.2 The mediatype Element
8.3.3 The label Element
8.3.4 The help Element
8.3.5 The hint Element
8.3.6 The alert Element
9 XForms User Interface
9.1 The XForms Group Module
9.1.1 The group Element
9.2 The XForms Switch Module
9.2.1 The switch Element
9.2.2 The case Element
9.2.3 The toggle Element
9.2.3.1 The case Element Child of the toggle Element
9.3 The XForms Repeat Module
9.3.1 The repeat Element
9.3.2 Creating Repeating Structures Via Attributes
9.3.3 The itemset Element
9.3.4 The copy Element
9.3.5 The insert Action
9.3.6 The delete Action
9.3.7 The setindex Element
9.3.8 Repeat Processing
9.3.9 Nested Repeats
9.3.10 User Interface Interaction
10 XForms Actions
10.1 The action Element
10.2 The dispatch Element
10.2.1 The name Child Element
10.2.2 The target Child Element
10.2.3 The delay Child Element
10.3 The rebuild Element
10.4 The recalculate Element
10.5 The revalidate Element
10.6 The refresh Element
10.7 The reset Element
10.8 The setvalue Element
10.9 The setfocus Element
10.9.1 The control Element Child of the setfocus Element
10.10 The load Element
10.10.1 The resource Element child of load
10.10.2 Processing of the load Action
10.11 The send Element
10.12 The message Element
10.13 The prompt Action Element
10.14 Conditional Execution of XForms Actions
10.15 Iteration of XForms Actions
10.16 Actions from Other Modules
11 The XForms Submission Module
11.1 The submission Element
11.2 The xforms-submit Event
11.3 The xforms-submit-serialize Event
11.4 The xforms-submit-done Event
11.5 The xforms-submit-error Event
11.6 The resource Element and Attribute
11.7 Submission verb Attribute and Element
11.7.1 The verb Attribute
11.7.2 The verb Element
11.8 The header Element
11.8.1 The name Element
11.8.2 The value Element
11.9 Submission Options
11.10 Serialization as application/xml
11.11 Serialization as multipart/related
11.12 Serialization as multipart/form-data
11.13 Serialization as application/x-www-form-urlencoded
11.14 The get Submit Method
11.15 The post, multipart-post, form-data-post, and urlencoded-post Submit Methods
11.16 The put Submit Method
11.17 The delete Submit Method
11.18 Replacing Data with the Submission Response
11.19 Integration with SOAP
11.19.1 Representation of SOAP Envelope
11.19.2 Indicating a SOAP submission
11.19.3 SOAP HTTP Binding
11.19.4 Handling the SOAP Response
12 Conformance
12.1 Conforming XForms Documents
12.2 Conforming XForms Generators
12.3 Base Technologies for XForms Processors
12.4 Conformance Levels
12.4.1 XForms Model
12.4.2 XForms Full
13 Glossary Of Terms
A Schema for XForms
A.1 Schema for XML Events
B References
B.1 Normative References
B.2 Informative References
C Privacy Considerations
C.1 Using P3P with XForms
D Recalculation Sequence Algorithm
D.1 Details on Creating the Master Dependency Directed Graph
D.2 Details on Creating the Pertinent Dependency Subgraph
D.3 Details on Computing Individual Vertices
D.4 Example of Calculation Processing
E Input Modes
E.1 inputmode Attribute Value Syntax
E.2 User Agent Behavior
E.3 List of Tokens
E.3.1 Script Tokens
E.3.2 Modifier Tokens
E.4 Relationship to XML Schema pattern facets
E.5 Examples
F XForms and Styling (Non-Normative)
F.1 Pseudo-classes
F.2 Pseudo-elements
F.3 Examples
G Complete XForms Examples (Non-Normative)
G.1 XForms in XHTML
G.2 Editing Hierarchical Bookmarks Using XForms
G.3 Survey Using XForms and SVG
H Changelog (Non-Normative)
I Acknowledgements (Non-Normative)
J Production Notes (Non-Normative)
Forms are an important part of the Web, and they continue to be the primary means for enabling interactive Web applications. Web applications and electronic commerce solutions have sparked the demand for better Web forms with richer interactions. XForms is the response to this demand, and provides a new platform-independent markup language for online interaction between a person (through an XForms Processor) and another, usually remote, agent. XForms are the successor to HTML forms, and benefit from the lessons learned from HTML forms.
Further background information on XForms can be found at http://www.w3.org/MarkUp/Forms.
This specification has been written with various types of readers in mind—in particular XForms authors and XForms implementors. We hope the specification will provide authors with the tools they need to write efficient, attractive and accessible documents without overexposing them to the XForms implementation details. Implementors, however, should find all they need to build conforming XForms Processors. The specification begins with a general presentation of XForms before specifying the technical details of the various XForms components.
The specification has been written with various modes of presentation in mind. In case of a discrepancy, the online electronic version is considered the authoritative version of the document.
This document uses the terms must, must not, required, shall, shall not, recommended, should, should not, may, and optional in accord with [RFC 2119].
The specification is organized into the following chapters:
An introduction to XForms. The introduction outlines the design principles and includes a brief tutorial on XForms.
XForms reference manual. The bulk of the reference manual consists of the specification of XForms. This reference defines XForms and how XForms Processors must interpret the various components in order to claim conformance.
Appendixes contain an XML Schema description of XForms, references, examples, and other useful information.
Throughout this document, the following namespace prefixes and corresponding namespace identifiers are used:
xforms: The XForms namespace, e.g.
http://www.w3.org/2002/xforms
(see 3.1 Namespace for XForms)
html: An XHTML namespace, e.g.http://www.w3.org/1999/xhtml
(see [XHTML 1.0])
xsd: The XML Schema namespacehttp://www.w3.org/2001/XMLSchema
(see [XML Schema part 1])
xsi: The XML Schema for instances namespacehttp://www.w3.org/2001/XMLSchema-instance
(see [XML Schema part 1])
ev: The XML Events namespacehttp://www.w3.org/2001/xml-events
(see [XML Events])
my: Any user defined namespace
This is only a convention; any namespace prefix may be used in practice.
The following typographical conventions are used to present technical material in this document.
Official terms are defined in the following manner: [Definition: You can find most terms in chapter 13 Glossary Of Terms]. Links to terms may be specially highlighted where necessary.
The XML representations of various elements within XForms are presented using the syntax for Abstract Modules in XHTML Modularization [XHTML Modularization].
Examples are set off typographically:
Example Item
References to external documents appear as follows: [Sample Reference] with links to the references section of this document.
The following typesetting convention is used for additional commentary:
Note:
A gentle explanation to readers.
Editorial note: Editorial Note Name | |
Editorial commentary, not intended for final publication. |
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:
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.
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.
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.
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.
Using XML 1.0 for instance data ensures that the submitted data is internationalization ready.
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.
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.
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.
In the XForms approach, forms are comprised of a section that describes what the form does, called the XForms Model, and another section that describes how the form is to be presented.
Consider a simple electronic commerce form that might be rendered as follows:
It is clear that we are collecting a value that represents whether cash or credit card is being used, and if a credit card, its number and expiration date.
This can be represented in the XForms model
element, which in XHTML would typically be contained within the head
section:
<xforms:model> <xforms:instance> <ecommerce xmlns=""> <method/> <number/> <expiry/> </ecommerce> </xforms:instance> <xforms:submission action="http://example.com/submit" method="post" id="submit" includenamespaceprefixes=""/> </xforms:model>
This simply says that we are collecting three pieces of information (note that we have as yet not said anything about their types), and that they will be submitted using the URL in the action
attribute.
XForms defines a device-neutral, platform-independent set of form controls suitable for general-purpose use. The controls are bound to the XForms Model via the XForms binding mechanism, in this simple case using the ref
attribute on the controls. In XHTML, this markup would typically appear within the body
section (note that we have intentionally defaulted the XForms namespace prefix here):
<select1 ref="method"> <label>Select Payment Method:</label> <item> <label>Cash</label> <value>cash</value> </item> <item> <label>Credit</label> <value>cc</value> </item> </select1> <input ref="number"> <label>Credit Card Number:</label> </input> <input ref="expiry"> <label>Expiration Date:</label> </input> <submit submission="submit"> <label>Submit</label> </submit>
Notice the following features of this design:
The user interface is not hard-coded to use radio buttons. Different devices (such as voice browsers) can render the concept of "select one" as appropriate.
Form controls always have labels directly associated with them as child elements—this is a key feature designed to enhance accessibility.
There is no need for an enclosing form
element, as in HTML. (See 2.4 Multiple Forms per Document for details on how to author multiple forms per document)
Markup for specifying form controls has been simplified in comparison with HTML forms.
The fact that you can bind form controls to the model like this simplifies integrating XForms into other host languages, since any form control markup may be used to bind to the model.
The XForms Processor can directly submit the data collected as XML. In the example, the submitted data would look like this:
<ecommerce> <method>cc</method> <number>1235467789012345</number> <expiry>2001-08</expiry> </ecommerce>
XForms processing keeps track of the state of the partially filled form through this instance data. Initial values for the instance data may be provided or left empty as in the example. Element instance
essentially holds a skeleton XML document that gets updated as the user fills out the form. It gives the author full control on the structure of the submitted XML data, including namespace information. When the form is submitted, the instance data is serialized as an XML document. Here is an alternative version of the earlier example:
<xforms:model> <xforms:instance> <payment method="cc" xmlns="http://commerce.example.com/payment"> <number/> <expiry/> </payment> </xforms:instance> <xforms:submission action="http://example.com/submit" method="post" includenamespaceprefixes="#default"/> </xforms:model>
In this case the submitted data would look like this:
<payment method="cc" xmlns="http://commerce.example.com/payment"> <number>1235467789012345</number> <expiry>2001-08</expiry> </payment>
This design has features worth calling out:
There is complete flexibility in the structure of the XML instance data, including the use of attributes. Notice that XML namespaces are used, and that a wrapper element of the author's choosing contains the instance data.
Empty elements number
and expiry
serve as place-holders in the XML structure, and will be filled in with form data provided by the user.
An initial value ("cc"
) for the form control is provided through the instance data, in this case an attribute method
. In the submitted XML, this initial value will be replaced by the user input, if the user changes the form control displaying that data.
To connect this instance data with form controls, the ref
attributes on the form controls need to be changed to point to the proper part of the instance data, using binding expressions:
ref
... xmlns:my="http://commerce.example.com/payment" ... <xforms:select1 ref="@method">...</xforms:select1> ... <xforms:input ref="my:number">...</xforms:input> ... <xforms:input ref="/my:payment/my:expiry">...</xforms:input>
Binding expressions are based on XPath [XPath 1.0], including the use of the @
character to refer to attributes, as seen here. Note that for illustrative purposes, the first two expressions make use of the XPath context node, which defaults to the top-level element (here my:payment
). The third expression shows an absolute path.
XForms allows data to be checked for validity as the form is being filled. In the absence of specific information about the types of values being collected, all values are returned as strings, but it is possible to assign types to values in the instance data. In this example, number
should accept digits only, and should have between 14 and 18 digits and expiry
should accept only valid month/date combinations.
Furthermore, the credit card information form controls for number
and expiry
are only relevant if the "cc"
option is chosen for method
, but are required in that case.
By specifying an additional component, model item properties, authors can include rich declarative validation information in forms. Such information can be taken from XML Schemas as well as XForms-specific additions, such as relevant
. Such properties appear on bind
elements, while Schema constraints are expressed in an XML Schema fragment, either inline or external. For example:
... xmlns:my="http://commerce.example.com/payment"... <xforms:model> ... <xforms:bind nodeset="/my:payment/my:number" relevant="/my:payment/@method = 'cc'" required="true()" type="my:ccnumber"/> <xforms:bind nodeset="/my:payment/my:expiry" relevant="/my:payment/@method = 'cc'" required="true()" type="xsd:gYearMonth"/> <xsd:schema ...> ... <xsd:simpleType name="ccnumber"> <xsd:restriction base="xsd:string"> <xsd:pattern value="\d{14,18}"/> </xsd:restriction> </xsd:simpleType> ... </xsd:schema> </xforms:model>
Note:
In the above example, the relevant
expression uses absolute XPath notation (beginning with /
) because the evaluation context nodes for computed expressions are determined by the bind
ref
binding expression (see 7.4 Evaluation Context), and so any relative node path in the first bind
relevant
above would be relative to /my:payment/my:number
XForms processing places no limits on the number of individual forms that can be placed in a single containing document. When a single document contains multiple forms, each form needs a separate model
element, each with an id
attribute so that they can be referenced from elsewhere in the containing document.
In addition, form controls should specify which model
element contains the instance data to which they bind. This is accomplished through a model
attribute that is part of the binding attributes. If no model
attribute is specified on the binding element, the nearest ancestor binding element's model
attribute is used, and failing that, the first XForms Model in document order is used. This technique is called 'scoped resolution', and is used frequently in XForms.
The next example adds an opinion poll to our electronic commerce form.
poll
model<xforms:model> <xforms:instance> ...payment instance data... </xforms:instance> <xforms:submission action="http://example.com/submit" method="post"/> </xforms:model> <xforms:model id="poll"> <xforms:instance> <helpful/> </xforms:instance> <xforms:submission id="pollsubmit" .../> </xforms:model>
Additionally, the following markup would appear in the body section of the document:
poll
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 of model="poll"
, which identifies the instance. Note that submit
refers to the submission
element by ID and does not require binding attributes.
More XForms examples can be found in G Complete XForms Examples.
XForms is an application of XML [XML 1.0] and has been designed for use within other XML vocabularies—in particular within a future version of XHTML [XHTML 1.0]. XForms always requires such a host language. This chapter discusses the structure of XForms that allow XForms to be used with other document types.
The namespace URI for XForms is http://www.w3.org/2002/xforms
. The XForms schema has the target namespace specified and as such is compatible with the XForms 1.0 definition.
<switch xmlns="http://www.w3.org/2002/xforms"> <case id="in" selected="true"> <input ref="yourname"> <label>Please tell me your name</label> <toggle ev:event="DOMActivate" case="out"/> </input> </case> <case id="out" selected="false"> <html:p>Hello <output ref="yourname" /> <trigger id="editButton"> <label>Edit</label> <toggle ev:event="DOMActivate" case="in"/> </trigger> </html:p> </case> </switch>
The above example is unchanged from the specification in XForms 1.0 (in the example, the prefixes html and ev are defined by an ancestor of the switch
element).
The Common Attribute Collection applies to every element in the XForms namespace.
The optional id
attribute of type xsd:ID
assigns an identity to the containing element.
Foreign attributes are allowed on all XForms elements.
The host language may permit a Linking Attributes Collection
to be applied to XForms elements as an alternate means of obtaining content related to the element.
An example is the src
attribute from [XHTML 1.0]. The schedule by which link traversal
occurs is defined by the host language. If the link traversal fails, the host language may dispatch
xforms-link-exception or xforms-link-error to the
model
associated with the in-scope evaluation context node of the element that bears the Linking
Attributes Collection for the failed link.
The following attributes define a binding between an XForms element such as a form control or an action and an instance data node defined by an XPath expression.
Binding expression interpreted as XPath. This attribute has no meaning when a bind
attribute is present.
Optional XForms Model selector. Specifies the ID
of an XForms Model to be associated with this binding element. This attribute has no meaning for the current binding element when a bind
attribute is present. Rules for determining the context XForms Model are located at 7.4 Evaluation Context.
Reference to a bind
element.
In this specification, when an XForms element is declared to have a Single-Node Binding, then the Single-Node Binding is required unless the element explicitly states that it is optional.
When the Single-Node Binding is required, one of ref
or bind
is required.
When bind
is used, the node is determined by the referenced bind
.
See 4.7.2 References to Elements within a bind Element for details on selecting an identified bind
that is iterated by one or more containing bind
elements.
It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model
IDREF
value that refers to an
ID
not on a model
element, or a bind
IDREF
value that refers to an ID
not on a bind
element.
First-node rule: When a Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set, based on document order, is used.
The following attributes define a binding between an XForms element such as a form control or an action and a node-set defined by the XPath expression.
Binding expression interpreted as XPath. This attribute has no meaning when a bind
attribute is present.
Optional XForms Model selector. Specifies the ID
of an XForms Model to be associated with this binding element.
This attribute has no meaning for the current binding element when a bind
attribute is present. Rules for determining the context XForms Model are located at 7.4 Evaluation Context.
Reference to a bind
element.
In this specification, when an XForms element is declared to have a Node-Set Binding, then the Node-Set Binding is required unless the element explicitly states that it is optional.
When the Node-Set Binding is required, one of nodeset
or bind
is required.
When bind
is used, the node-set is determined by the referenced bind
.
See 4.7.2 References to Elements within a bind Element for details on selecting an identified bind
that is iterated by one or more containing bind
elements.
It is an exception (4.5.1 The xforms-binding-exception Event) if the XForms Processor encounters a model
IDREF value that refers to an id not on a model
element,
or a bind
IDREF value that refers to an id
not on a bind
element.
This collection contains one attribute for each model item property, with an attribute name exactly matching the name of the model item property, as defined in 6.1 Model Item Property Definitions.
The XForms Core Module defines the major structural elements of XForms, intended for inclusion in a containing document. The elements and attributes included in this module are:
Element | Attributes | Minimal Content Model |
---|---|---|
model | Common, Events, functions (QNameList), schema (list of xsd:anyURI), version (xsd:string) | (instance|xsd:schema| submission|bind|Action)* |
instance | Common, resource | (ANY) |
submission | Common, ref (binding-expression), bind (xsd:IDREF), resource (xsd:anyURI), action (xsd:anyURI), mode ("asynchronous"|"synchronous"), method ("post"|"get"|"put"|delete|"form-data-post"|"urlencoded-post"|qname-but-not-ncname), verb (xsd:string), validate (xsd:boolean), relevant (xsd:boolean), serialize (xsd:boolean), 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"|qname-but-not-ncname), instance (xsd:IDREF), target (binding-expression), separator (';' | '&'), includenamespaceprefixes (xsd:NMTOKENS) | resource?, verb?, header*, Action* |
bind | Common, Model Item Properties, nodeset (model-binding-expression) | (bind)* |
Elements defined in the XForms Actions module, when that module is included, are also allowed in the content model of model
and submission
, as shown above.
Within the containing document, these structural elements are typically not rendered.
The XForms Processor must ignore any foreign-namespaced attributes that are unrecognized, and must process unrecognized foreign-namespaced elements according to the 3.4 The XForms MustUnderstand Module rules.
Note that the presence of foreign namespaced elements is subject to the definition of the containing document profile.
This element represents a form definition and is used as a container for elements that define the XForms Model.
No restriction is placed on how many model
elements may exist within a containing document.
Common Attributes: Common, Events
Attributes from XML Events are allowed on this element to facilitate creating observers. This element is not an XForms Action, and has no predefined behavior event-based behavior.
Special Attributes:
Optional space-separated list of XPath extension functions (represented by QNames) required by this XForms Model. Guidance on the use of this attribute is at 7.12 Extension Functions.
Optional list of xsd:anyURI
links to XML Schema documents outside this model
element. The XForms Processor must process all Schemas listed in this attribute.
Within each XForms Model, there is a limit of one Schema per namespace declaration, including inline and linked Schemas.
Note:
The schema
list may include URI fragments referring to elements located elsewhere in the containing document; e.g. "#myschema"
.
Optional attribute with a default value of "1.0". The legal values are the strings consisting of a positive integer, a period, then a non-negative integer.
The XForms Processor selects the version setting from the default model
, which is the first
model
in document order. The version setting for the XForms Processor corresponds to its behaving according to the desired version of
the XForms language, e.g. a version setting of "1.1" corresponds to a processor for XForms 1.1. If the XForms Processor does not support
the behaviors of the language version indicated by the version setting, then the XForms Processor must terminate processing after dispatching the
event xforms-version-exception to the default model
. If any non-default model
has a
versoin setting that conflicts with the default model
, then the XForms Processor must terminate processing after dispatching the event
xforms-version-exception to the default model
.
Note:
Since documents that conform to [XForms 1.0] are required to be XForms schema valid, and XForms 1.1 features including the version
attribute would violate the XForms 1.0 schema, an XForms 1.0 Processor may not correctly process an XForms 1.1 document. Implementers of XForms 1.0
processors are encouraged to check for the version
in order to more gracefully report potential compatibility issues with XForms 1.1 documents.
Examples:
model
, with the XForms namespace defaulted:<model id="Person" schema="MySchema.xsd"> <instance resource="http://example.com/cgi-bin/get-instance" /> ... </model>
<model> <message level="modal" ev:event="xforms-version-exception" ref="event('errorinformation')"/> ... </model> ... <model id="m2" version="1.1"> ... </model>
Since the version
attribute is not specified on the model
, the default of 1.0 is used, so
the message
action is performed if the XForms Processor does not support 1.0-specific behaviors
in its processing of the XForms vocabulary. Otherwise, the message action occurs during initialization of the
second model
due to its version conflict with the default model
.
This optional element contains or references initial instance data.
Common Attributes: Common
Special Attributes:
Optional link to externally defined initial instance data. If the link is traversed and the traversal fails, it is treated as an exception (4.5.2 The xforms-link-exception Event).
If both the resource
attribute and inline content are provided, the inline content takes precedence as described at 4.2.1 The xforms-model-construct Event. The host language may also specify an external link for the instance data using a linking attribute. The content obtained from a linking attribute may override the inline content, just the resource
attribute or neither. If the host language may treat failure to traverse the link as an exception (4.5.2 The xforms-link-exception Event).
If the initial instance data is given by a link, then the instance data is formed by creating an XPath data model of the linked resource.
If the initial instance data is given by inline content, then instance data is obtained by first creating a detached copy of the inline content (including namespaces inherited from the enveloping ancestors), then creating an XPath data model over the detached copy. The detached copy must consist of content that would be well-formed XML if it existed in a separate document. Note that this restricts the element content of instance
to a single child element.
If creation of the XML data model for the instance data fails due to an XML error,
then processing halts after dispatching an xforms-link-exception
with a resource-uri
indicating either the URI for an external instance, a barename URI reference to an identified internal instance, or empty string for
an with an unidentified internal instance. .
This exception could happen, for example, if the content had
more than one top-level element, which is not permitted since an XML document cannot have more than one document element.
Note:
All data relevant to the XPath data model must be preserved during processing and submission, including processing instructions, comment nodes and all whitespace.
Note:
XForms authors who need additional control over the serialization of namespace nodes can use the includenamespaceprefixes
attribute on the submission
element.
Details about the submission
element and its processing are described in 11 The XForms Submission Module.
Element bind
selects a node-set selected from the
instance data with a
model binding expression in the nodeset
attribute. Other attributes on element bind
encode
model item properties to be applied to each node in the
node-set. When bind
has an attribute of type xsd:ID
, the bind
then associates
that identifier with the selected node-set.
Common Attributes: Common, Model Item Properties (Optional)
Special Attributes:
An optional attribute containing a model binding expression that selects the set of nodes on which this bind
operates.
See 7.4 Evaluation Context for details on how the evaluation context is determined for each attribute of the bind
element..
Certain elements, such as extension
or foreign namespaced elements defined in a host language might be critical to the operation of a particular form. To indicate this, the MustUnderstand module defines a single attribute that can be used on any element.
Element | Attributes | Minimal Content Model |
---|---|---|
ANY | xforms:mustUnderstand (xsd:boolean) | n/a |
It is a terminating error that must be reported to the user if an element is marked mustUnderstand="true"
, and the XForms Processor does not have an implementation available for processing the element.
There are many different ways a host language might include XForms. One approach uses only well-formed processing, disregarding validation. Another case uses strict validation, for example XHTML 1.0, in which only predefined elements are allowed. Another common approach is to allow unregulated content in a few selected places. A host language that chooses this option can use the Extension module.
Element | Attributes | Minimal Content Model |
---|---|---|
extension | Common | ANY |
Optional element extension
is a container for application-specific extension elements from any namespace other than the XForms namespace. This specification does not define the processing of this element.
Common Attributes: Common
For example, RDF metadata could be attached to an individual form control as follows:
<input ref="dataset/user/email" id="email-input"> <label>Enter your email address</label> <extension> <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"> <rdf:Description rdf:about="#email-input"> <my:addressBook>personal</my:addressBook> </rdf:Description> </rdf:RDF> </extension> </input>
This chapter defines the XForms Processing Model declaratively by enumerating the various states attained by an XForms Processor and the possible state transitions that exist in each of these states. The chapter enumerates the pre-conditions and post-conditions that must be satisfied in each of these states. XForms Processors may be implemented in any manner, so long as the end results are identical to that described in this chapter.
State transitions are in general initiated by sending events to parts of the XForms tree. The XForms Processing Model consists of events in the following categories:
Initialization
Interaction
Notification
Error Conditions
XForms processing is defined in terms of events, event handlers, and event responses. XForms uses the events system defined in [DOM2 Events][XML Events], with an event capture phase, arrival of the event at its Target, and finally the event bubbling phase.
Throughout this chapter, each reference to "form control" as a target element is a shorthand for any of the following elements: input
, secret
, textarea
, output
, upload
, trigger
, range
, submit
, select
, select1
, or group
.
Event name | Cancelable? | Bubbles? | Target element |
---|---|---|---|
4.2 Initialization Events | |||
xforms-model-construct | No | Yes | model |
xforms-model-construct-done | No | Yes | model |
xforms-ready | No | Yes | model |
xforms-model-destruct | No | Yes | model |
4.3 Interaction Events | |||
xforms-previous | Yes | No | form control |
xforms-next | Yes | No | form control |
xforms-focus | Yes | No | form control |
xforms-help | Yes | Yes | form control |
xforms-hint | Yes | Yes | form control |
xforms-rebuild | Yes | Yes | model |
xforms-refresh | Yes | Yes | model |
xforms-revalidate | Yes | Yes | model |
xforms-recalculate | Yes | Yes | model |
xforms-reset | Yes | Yes | model |
xforms-submit | Yes | Yes | submission |
xforms-submit-serialize | No | Yes | submission |
4.4 Notification Events | |||
DOMActivate | Yes | Yes | form control |
xforms-value-changed | No | Yes | form control |
xforms-select | No | Yes | item or case |
xforms-deselect | No | Yes | item or case |
xforms-scroll-first | No | Yes | repeat |
xforms-scroll-last | No | Yes | repeat |
xforms-insert | No | Yes | instance |
xforms-delete | No | Yes | instance |
xforms-valid | No | Yes | form control |
xforms-invalid | No | Yes | form control |
DOMFocusIn | No | Yes | form control |
DOMFocusOut | No | Yes | form control |
xforms-readonly | No | Yes | form control |
xforms-readwrite | No | Yes | form control |
xforms-required | No | Yes | form control |
xforms-optional | No | Yes | form control |
xforms-enabled | No | Yes | form control |
xforms-disabled | No | Yes | form control |
xforms-in-range | No | Yes | form control |
xforms-out-of-range | No | Yes | form control |
xforms-submit-done | No | Yes | submission |
xforms-submit-error | No | Yes | submission |
4.5 Error Indications | |||
xforms-binding-exception | No | Yes | any element that can contain a binding expression |
xforms-link-exception | No | Yes | model |
xforms-link-error | No | Yes | model |
xforms-compute-exception | No | Yes | model |
xforms-version-exception | No | Yes | The default model |
This section defines the various stages of the initialization phase. The processor begins initialization by dispatching an event xforms-model-construct
to each XForms Model in the containing document. How the XForms Processor itself is requested to initialize is implementation dependent.
Dispatched to each XForms model by the XForms processor.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following:
All XML Schemas are loaded. If an error occurs while attempting to access or process a remote document, processing halts with an exception (4.5.2 The xforms-link-exception Event).
For each instance
element, if inline initial instance data is given,
then an XPath data model [7 XPath Expressions in XForms] is constructed from it; otherwise, if the resource
attribute provides
an external source for the initial instance, that is used instead to obtain the XPath data model. If the external initial
instance data is not well-formed XML or cannot be retrieved, processing halts with an exception (4.5.2 The xforms-link-exception Event).
If neither are given, the data model is not constructed in this phase, but during user interface construction
(4.2.2 The xforms-model-construct-done Event).
If applicable, P3P initialization occurs. [P3P 1.0]
Perform the behaviors of xforms-rebuild
,
xforms-recalculate
, and xforms-revalidate
in sequence
on this model
element
without dispatching events to invoke the behaviors.
The notification event markings for these operations are discarded, and the
xforms-refresh
behavior is not
performed since the user interface has not yet been initialized.
After all XForms Models have been initialized, an xforms-model-construct-done
event is dispatched to each model
element.
Dispatched after the completion of xforms-model-construct
processing.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event happens once, no matter how many XForms Models are present in the containing document, and results in the following, for each form control:
Processing can proceed in one of two different ways depending on whether an instance
in a model
exists when the first form control is processed.
If the instance
referenced on the form control existed when the first form control was processed:
The binding expression is evaluated to ensure that it points to a node that exists. If this is not the case then the form control should behave in the same manner as if it had bound to a model item with the relevant
model item property resolved to false
.
If the instance
referenced on the form control did not exist when the first form control for the same instance
was processed:
For the first reference to an instance
a default instance
is created by following the rules described below.
A root instanceData
element is created.
An instance data element node will be created using the binding expression from the user interface control as the name
. If the name
is not a valid QName, processing halts with an exception (4.5.1 The xforms-binding-exception Event).
For the second and subsequent references to an instance
which was automatically created the following processing is performed:
If a matching instance data node is found, the user interface control will be connected to that element.
If a matching instance data node is not found, an instance data node will be created using the binding expression from the user interface control as the name
. If the name
is not a valid QName, processing halts with an exception (4.5.1 The xforms-binding-exception Event).
The above steps comprise the default processing of xforms-model-construct-done
.
After all form controls have been initialized and all xforms-model-construct-done
events have been processed, an xforms-ready
event is dispatched to each model
element.
Dispatched as part of xforms-model-construct-done
processing.
Target: model
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
Dispatched by the processor to advise of imminent shutdown of the XForms Processor, which can occur from user action, or from the load
XForms Action, or as a result of form submission.
Target: model
Bubbles: No
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
Dispatched in response to: user request to navigate to the next or previous form control.
Target: form control
Bubbles: No
Cancelable: Yes
Context Info: None
The default action for these events results in the following: Navigation according to the default navigation order. For example, on a keyboard interface, "tab" might generate an xforms-next
event, while "shift+tab" might generate an xforms-previous
event.
Navigation is determined on a containing document-wide basis. The host language is responsible for defining overall navigation order. The following describes a possible technique based on a navindex
attribute, using individual form controls as a navigation unit: The <group
>, <repeat
>, and <switch
> structures also serve as navigation units, but instead of providing a single navigation point, they create a local navigation context for child form controls (and possibly other substructures). The navigation sequence is determined as follows:
Form controls that have a navindex
specified and assign a positive value to it are navigated first.
Outermost form controls are navigated in increasing order of the navindex
value. Values need not be sequential nor must they begin with any particular value. Form controls that have identical navindex
values are to be navigated in document order.
Ancestor form controls (<group
>, <repeat
>, and <switch
>) establish a local navigation sequence. All form controls within a local sequence are navigated, in increasing order of the navindex
value, before any outside the local sequence are navigated. Form controls that have identical navindex
values are navigated in document order.
Those form controls that do not specify navindex
or supply a value of "0" are navigated next. These form controls are navigated in document order.
Those form controls that are disabled, hidden, or not relevant
are assigned a relative order in the overall sequence but do not participate as navigable controls.
The navigation sequence past the last form control (or before the first) is undefined. XForms Processors may cycle back to the first/last control, remove focus from the form, or other possibilities.
Dispatched in response to: set focus to a form control.
Target: form control
Bubbles: No
Cancelable: Yes
Context Info: None
The default action for these events results in the following:
Focus is given to the target form control if the form control is able to accept focus. Setting focus to a repeating structure sets the focus to the repeat item represented by the repeat index.
Dispatched in response to: a user request for help or hint information.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for these events results in the following: If the form control has help/hint elements supplied, these are used to construct a message that is displayed to the user. Otherwise, user agents may provide default help or hint messages, but are not required to.
Dispatched in response to: a request to update all form controls associated with a particular XForms Model.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
All UI bindings should be reevaluated as necessary.
A node can be changed by confirmed user input to a form control, by xforms-recalculate (section 4.3.6) or by the setvalue (section 10.1.9) action. If the value of an instance data node was changed, then the node must be marked for dispatching the xforms-value-changed event.
If the xforms-value-changed event is marked for dispatching, then all of the appropriate model item property notification events must also be marked for dispatching (xforms-optional or xforms-required, xforms-readwrite or xforms-readonly, and xforms-enabled or xforms-disabled).
For each form control, each notification event that is marked for dispatching on the bound node must be dispatched (xforms-value-changed, xforms-valid, xforms-invalid, xforms-optional, xforms-required, xforms-readwrite, xforms-readonly, and xforms-enabled, xforms-disabled). The notification events xforms-out-of-range or xforms-in-range must also be dispatched as appropriate. This specification does not specify an ordering for the events.
The user interface reflects the state of the model, which means that all forms controls reflect for their corresponding bound instance data:
its current value
its validity
whether it is required
, readonly
or relevant
.
Dispatched in response to: a request to revalidate a particular XForms Model.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
An instance node is valid if and only if the following conditions hold:
the constraint model item property is true
the node satisfies all applicable XML schema definitions
(including those associated by the type model item property, by an external or an inline schema, or by xsi:type
)
Note:
A node that satifies the above conditions is valid even if it is required but empty.
The default action for this event results in the following:
All instance data nodes in all instance
elements in the model
are checked
for validity according to the above
definition. If the validity of a node changes, then
either the xforms-valid event must be marked for
dispatch if the node changes from valid to invalid
or the xforms-invalid event must be marked for
dispatch if the node changes from valid to invalid.
Marking one of these events for dispatch unmarks the other.
Dispatched in response to: a request to recalculate all calculations associated with a particular XForms Model.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
The values of all instance data items match their associated 'calculate' constraints, if any. All model item properties that can contain computed expressions are resolved. In addition to contributing further node value changes that will cause xforms-value-changed notifications in xforms-refresh, the model item properties that change are marked to help xforms-refresh to determine the notification events to dispatch.
If the required model item property changes, then either the xforms-required event must be marked for dispatch if required is true or the xforms-optional event must be marked for dispatch if required is false. Marking one of these events for dispatch unmarks the other.
If the readonly model item property changes, then either the xforms-readonly event must be marked for dispatch if readonly is true or the xforms-readwrite event must be marked for dispatch if readonly is false. Marking one of these events for dispatch unmarks the other.
If the relevant model item property changes, then either the xforms-enabled event must be marked for dispatch if relevant is true or the xforms-disabled event must be marked for dispatch if relevant is false. Marking one of these events for dispatch unmarks the other.
An XPath expression is bound either to the value or to a model item property
(e.g., required
, relevant
) of one or more instance nodes.
The combination of an XPath expression with a single instance node's value or model item property
is considered as a single computational unit, a compute, for the
purposes of recalculation.
When it is time to recalculate a model item property, the
XPath expression is evaluated.
The evaluation context is determined from the model binding expression
that applied the model item property, as defined for computed expressions in
7.4 Evaluation Context. The XPath expression may reference or
refer to another instance node, in which case the value of the instance node is
referenced. Each referenced instance node has as dependents those
computes which directly refer to the instance node. References to the current node's value in
calculate
expressions are explicitly ignored, i.e., if an expression associated
with a compute refers to the instance node associated with the compute, then the instance node
does not take itself as a dependent. A compute is computationally dependent on an
instance node (whose value may or may not be computed) if there is a path of dependents leading
from the instance node through zero or more other instance nodes to the compute. A compute is
part of a circular dependency if it is computationally dependent on itself.
Note:
Authors should not refer to the current node's value in calculate
expressions
because the effect is not well-defined. Other model item properties, such as required
or
readonly
, however, are well-defined in the presence of self-references.
When a recalculation event begins, there will be a list L of one or more instance nodes whose values may have been changed, e.g., by user input being propagated to the instance.
An XForms Processor must recalculate computes for nodes in L and nodes that are computationally dependent on nodes in L.
An XForms Processor must perform only a single recalculation of each compute that is computationally dependent on one or more of the elements in L.
An XForms Processor must recalculate a compute C after recalculating all computes of instance nodes on which C is computationally dependent. (Equivalently, an XForms Processor must recalculate a compute C before recalculating any compute that is computationally dependent on the instance node associated with C.)
Finally, if a compute is part of a circular dependency and also computationally dependent on an element in L, then an XForms processor must report an exception (4.5.4 The xforms-compute-exception Event).
D Recalculation Sequence Algorithm describes one possible method for achieving the desired recalculation behavior.
Dispatched in response to: a request to rebuild the internal data structures that track computational dependencies within a particular XForms Model.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
All model item properties are initialized by processing all bind
elements in document order. For each bind
:
If the attribute nodeset
is attached to the bind, it is evaluated to select an XPath node-set. Otherwise, if the bind
does not have a nodeset
attribute, then the selected XPath node-set consists of the in-scope evaluation context.
For each node in the selected XPath node-set, model item properties are applied according to the remaining attributes on the bind
element
(for details on the model item properties, see 6 Model Item Properties).
If a node already contains a model item property of the same name due to the processing of prior bind
elements, then XForms processing for the
containing document halts with an exception (4.5.1 The xforms-binding-exception Event).
For each node in the selected XPath node-set, any child bind
elements are recursively processed as described in the three points of this list.
After initial processing of the bind
elements, the computational dependency data structures
are rebuilt, and then the change list L is set to contain references to all instance nodes that have an associated computational expression
so that a full recalculation is performed the next time the behavior of
xforms-recalculate
is invoked.
Dispatched in response to: a user request to reset the model.
Target: model
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following:
The instance data is reset to the tree structure and values it had immediately after having processed the xforms-ready
event. Then, the events xforms-rebuild
, xforms-recalculate
, xforms-revalidate
and xforms-refresh
are dispatched to the model
element in sequence.
See chapter 11.2 The xforms-submit Event.
See chapter 11.3 The xforms-submit-serialize Event.
Dispatched in response to: the "default action request" for a form control, for instance pressing a button or hitting enter.
Target: form control
Bubbles: Yes
Cancelable: Yes
Context Info: None
The default action for this event results in the following: None; notification event only.
Dispatched in response to: a change to an instance data node bound to a form control.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event due to a change.
Note:
For incremental processing, this specification does not define how often XForms Processors fire these events. Implementations are expected to optimize processing (for instance not flashing the entire screen for each character entered, etc.).
Note:
The change to the instance data associated with this event happens before the event is dispatched.
Dispatched in response to: an item in a select
, select1
, or switch
becoming selected or deselected.
Target: item
or case
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
Dispatched in response to: a setindex action attempting to set an index outside the range of a repeat
.
Target: repeat
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
Dispatched in response to: Successful insertion of one or more nodes by an XForms insert
action.
Target: instance
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
binding | string | The attribute value of the insert action's nodeset or bind attribute. |
inserted-nodes | node-set | The instance data nodes inserted. |
origin-nodes | node-set | The instance data nodes referenced by the insert action's origin attribute if present, or the empty nodeset if not present. |
insert-location-node | node-set | The insert location node as defined by the insert action. |
position | string | The insert position, before or after . |
Default Action: None; notification event only.
Dispatched in response to: Successful deletion of one or more nodes by an XForms delete
action.
Target: instance
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
binding | string | The attribute value of the delete action's nodeset or bind attribute. |
deleted-nodes | node-set | The instance data node deleted. Note that these nodes are no longer referenced by their parents. |
delete-location | number | The delete location as defined by the delete action, or NaN if there is no delete location. |
Default Action: None; notification event only.
Dispatched in response to: an instance data node either changing and being or becoming valid.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.5 The xforms-revalidate Event.
Dispatched in response to: an instance data node either changing and being or becoming invalid.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.5 The xforms-revalidate Event.
Dispatched in response to: a form control receiving focus.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
Dispatched in response to: a form control losing focus.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
Dispatched in response to: an instance data node either changing and being or becoming readonly.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.
Dispatched in response to: an instance data node either changing and being or becoming read-write.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.
Dispatched in response to: an instance data node either changing and being or becoming required.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.
Dispatched in response to: an instance data node either changing and being or becoming optional.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.
Dispatched in response to: an instance data node either changing and being or becoming enabled.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.
Dispatched in response to: an instance data node either changing and being or becoming disabled.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched during 4.3.4 The xforms-refresh Event if the bound instance data node has been marked for dispatching this event in 4.3.6 The xforms-recalculate Event or 4.3.4 The xforms-refresh Event.
Dispatched in response to: the value of an instance data node has changed such that the value can now be represented by the form control.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched whenever the value of an instance data node that was not possible to represent given the constraints specified on a form control has changed such that the value can now be represented by the form control.
Dispatched in response to: the value of an instance data node has changed such that the value can not be represented by the form control.
Target: form control
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: None; notification event only.
This event is dispatched whenever the value of an instance data node can not be represented given the constraints specified on a form control.
See chapter 11.4 The xforms-submit-done Event.
See chapter 11.5 The xforms-submit-error Event.
Dispatched by the processor immediately after the first failure of an output
to render or update the rendition of content.
Target: output
Bubbles: Yes
Cancelable: No
Context Info: None.
Default Action: None; notification event only.
Note:
The output
element content can include XForms actions, so an output
element can contain
an event handler for the xforms-output-error
event.
Error indications happen as a result of unusual conditions in the XForms Processor. Some of these are "fatal" errors, which halt processing, and bear the suffix "exception". Others are simply for notification, and bear the suffix "error". For all events in this section, it is permissible for the XForms Processor to perform some kind of default handling, for example logging error messages to a file.
Dispatched as an indication of: an illegal binding expression, or a model
attribute that fails to point to the ID of a model
element, or a bind
attribute that fails to point to the ID of a bind
element, or a submission
attribute that fails to point to the ID of a submission
element, or an instance
attribute on the submission
element that fails to point to an instance
element in the same model
element as the submission
.
Target: any element that can contain a binding expression
Bubbles: Yes
Cancelable: No
Context Info: None
The default action for this event results in the following: Fatal error.
Dispatched as an indication of: a failure to traverse or process the result of a link in a situation critical to form processing, such as schema or instance initialization.
Target: model
associated with the in-scope evaluation context node of the element performing the link
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
resource-uri | string | The URI associated with the failed link (xsd:anyURI) |
Default Action: Fatal error.
Dispatched as an indication of: a failure to traverse a link in a situation not critical to form processing,
such as executing a load
action.
Target: model
associated with the in-scope evaluation context node of the element performing the link
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
resource-uri | string | The URI associated with the failed link (xsd:anyURI) |
Default Action: None; notification event only.
Dispatched as an indication of: an error occurring during XPath evaluation for a model item property (see 6 Model Item Properties).
Target: model
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
error-message | string | An implementation-specific string that should contain the expression being processed when the exception was detected. |
Default Action: Fatal error.
The previous sections describe processing associated with individual events. This section gives the overall sequence of related events that must occur in several common situations. In the following lists, events that may be fired more than once are prefixed with [n].
input
, secret
, textarea
, range
, or upload
ControlsWhen the form control is interactively changed, and has the "incremental="true" setting, the event sequence described at 4.6.7 Sequence: Value Change may be initiated at implementation dependent intervals.
When the form control is interactively changed and does not have the "incremental=true" setting, no events are required to be dispatched, and thus no order is defined.
When focus changes from the form control and the value has changed, the event sequence is as described at 4.6.7 Sequence: Value Change.
select
or select1
ControlsWhen a selection is interactively changed, and the form control has the "incremental="true" setting, the event sequence is described at 4.6.6 Sequence: Selection Without Value Change, which may be followed immediately by the sequence described at 4.6.7 Sequence: Value Change.
When a selection is interactively changed, and the form control does not have the "incremental="true" setting, the event sequence is described at 4.6.6 Sequence: Selection Without Value Change.
When focus changes from the form control and the value has changed, the event sequence is as described at 4.6.7 Sequence: Value Change.
trigger
ControlsActivating the form control causes the event sequence defined at 4.6.8 Sequence: Activating a Trigger.
submit
ControlsActivating the form control causes the event sequence defined at 4.6.8 Sequence: Activating a Trigger, followed immediately by the event sequence defined at 4.6.9 Sequence: Submission.
xforms-recalculate
xforms-revalidate
xforms-refresh performs reevaluation of UI binding expressions then dispatches these events according to value changes, model item property changes and validity changes:
[n] xforms-value-changed
[n] xforms-valid or xforms-invalid
[n] xforms-enabled or xforms-disabled
[n] xforms-optional or xforms-required
[n] xforms-readonly or xforms-readwrite
[n] xforms-out-of-range or xforms-in-range
(The order in which these events are dispatched is not defined).
Perform further deferred updates as necessary
The element of a document for which an IDREF must be resolved is called the source element, and the element bearing the matching ID, if there is one, is called the target element. Due to the run-time expansion of repeated content in XForms, it is possible that there will be more than one occurrence of both the source and target elements. This section describes how XForms IDREF resolution works to accommodate such repetition of the originating document's content.
Each run-time occurrence of the source element is called a source object, and each run-time occurrence of the target element is called a target object. It is the source object that performs the IDREF resolution, and the result of the search is either null or a target object.
Whether or not repeated content is involved, a null search result for an IDREF resolution is handled differently depending on
the source object. If there is a null search result for the target object and the source object is an XForms action such as dispatch
,
send
, setfocus
, setindex
or toggle
, then the action is terminated with no effect. Similarly, a
submit
form control does not dispatch xforms-submit
if its submission
attribute does not indicate
an existing submission
element. Likewise, when an XPath function associated with the source object performs the
IDREF search and a null result is obtained, the function returns an empty result such as NaN
for the
index()
function or empty nodeset for the instance()
function.
However, an xforms-binding-exception
occurs if there is a null search result for the target object indicated
by attributes bind
, model
and instance
.
If the target element is not repeated, then the search for the target object is trivial since there is only one associated with the target element that bears the matching ID. This is true regardless of whether or not the source object is repeated. However, if the target element is repeated, then additional information must be used to help select a target object from among those associated with the identified target element.
When the target element that is identified by the IDREF of a source object has one or more repeat
elements as ancestors,
then the set of ancestor repeats are partitioned into two subsets, those in common with the source element and those that are
not in common. Any ancestor repeat
elements of the target element not in common with the source element are descendants
of the repeat
elements that the source and target element have in common, if any.
For the repeat
elements that are in common, the desired target object exists in the same set of run-time objects that
contains the source object. Then, for each ancestor repeat
of the target element that is not in common with the source element,
the current index of the repeat
determines the set of run-time objects that contains the desired target object.
When a source object expresses a Single Node Binding or Node Set Binding with a bind
attribute, the IDREF of the bind
attribute is resolved to a target bind object whose associated nodeset is used by the Single Node Binding or Node Set Binding.
However, if the target bind
element has one or more bind
element ancestors, then the identified bind
may be a target element that is associated with more than one target bind object.
If a target bind
element is outermost, or if all of its ancestor bind
elements have nodeset
attributes
that select only one node, then the target bind
only has one associated bind object, so this is the desired
target bind object whose nodeset is used in the Single Node Binding or Node Set Binding. Otherwise, the in-scope evaluation
context node of the source object containing the bind
attribute is used to help select the appropriate target bind object
from among those associated with the target bind
element.
From among the bind objects associated with the target bind
element, if there exists a bind object created with the
same in-scope evaluation context node as the source object, then that bind object is the desired target bind object. Otherwise,
the IDREF resolution produced a null search result.
This chapter defines the datatypes used in defining an XForms Model.
XForms supports all XML Schema datatypes except for xsd:duration
, xsd:ENTITY
, xsd:ENTITIES
, and xsd:NOTATION
. Concepts value space, lexical space and constraining facets are as specified in [XML Schema part 2]. Certain XML Schema datatypes have been identified as part of a smaller XForms conformance profile that is being developed separately, and are marked with an asterisk *. XForms includes datatypes derived by restriction and derived by list from these base types. XForms Processors must treat the datatypes listed in the chapter as in-scope without requiring the inclusion of an XML Schema.
Built-in primitive types:
xsd:dateTime *
xsd:time *
xsd:date *
xsd:gYearMonth *
xsd:gYear *
xsd:gMonthDay *
xsd:gDay *
xsd:gMonth *
xsd:string *
xsd:boolean *
xsd:base64Binary *
xsd:hexBinary
xsd:float
xsd:decimal *
xsd:double
xsd:anyURI *
xsd:QName
Note:
The built-in datatype xsd:duration
is not supported, except as an abstract datatype. Instead, either xforms:dayTimeDuration
or xforms:yearMonthDuration
should be used.
Built-in derived types:
xsd:normalizedString
xsd:token
xsd:language
xsd:Name
xsd:NCName
xsd:ID
xsd:IDREF
xsd:IDREFS
xsd:NMTOKEN
xsd:NMTOKENS
xsd:integer *
xsd:nonPositiveInteger *
xsd:negativeInteger *
xsd:long *
xsd:int *
xsd:short *
xsd:byte *
xsd:nonNegativeInteger *
xsd:unsignedLong *
xsd:unsignedInt *
xsd:unsignedShort *
xsd:unsignedByte *
xsd:positiveInteger *
The Schema for XForms derives the following types to facilitate datatype assignments in the model
element.
This datatype serves as a base for the xforms:listItems
datatype. The value space for listItem permits one or more characters valid for xsd:string, except white space characters.
XForms includes form controls that produce simpleType list content. This is facilitated by defining a derived-by-list
datatype.
The value space for listItems is defined by list-derivation from listItem.
Note:
In most cases, it is better to use markup to distinguish items in a list. See 9.3.3 The itemset Element.
XForms includes a totally ordered duration datatype that can represent a duration of days, hours, minutes, and fractional seconds.
The value space for this datatype is the set of fractional second values. This datatype is derived from xsd:duration
.
XForms includes a totally ordered duration datatype that can represent a duration of a whole number of months and years.
The value space for this datatype is the set of integer month values. This datatype is derived from xsd:duration
.
XForms provides support for several built-in datatypes, includes datatypes derived by restriction,
derived by list, and derived by union from these base types. XForms also defines new derived
datatypes that are commonly used in forms. The following text describes a new derived datatype,
xforms:email
, introduced for XForms 1.1. This datatype represents an email address,
as defined by [RFC 2822]. Internationalized email addresses are not restricted by
XForms beyond the definition in the RFC. For simplicity, some extremely uncommon features of the
RFC syntax are not allowed, such as "Obsolete Addressing" from section 4.4, square-bracketed
"domain-literal"s, and insignificant whitespace and comments.
Examples of valid xforms:email addresses
editors@example.com
~my_mail+{nospam}$?@sub-domain.example.info
Examples of invalid xforms:email addresses
editors@(this is a comment)example.info
editors{at}example{dot}info
Note:
It is outside the scope of XForms to determine whether a given email address actually corresponds to an active mailbox.
Note:
The xforms:email data type is made available by the XForms processor based on the following definition:
<xsd:simpleType name="email"> <xsd:restriction base="xsd:string"> <xsd:pattern value="[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~ ]+)*@[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+(\.[A-Za-z0-9!#-'\*\+\-/=\?\^_`\{-~]+)*"/> </xsd:restriction> </xsd:simpleType>
This type defines the basic structure of an ID number that conforms to [ISO 7812-1:2000].
Various ID cards use this standard as the format for their numbers including those issued by financial institutions for debit and credit cards.
The ID number is a pattern restriction on xsd:string
: it must be between 12 and 19 digits (0 - 9).
<xsd:simpleType name="ID-card-number"> <xsd:annotation> <xsd:documentation> This type defines an ID number that conforms to ISO/IEC 7812-1:2000 Identification cards -- Identification of issuers -- Part 1: Numbering system. This type does not apply the Luhn checksum algorithm. </xsd:documentation> </xsd:annotation> <xsd:restriction base="xsd:string"> <xsd:minLength value="12"/> <xsd:maxLength value="19"/> <xsd:pattern value="[0-9]+"/> </xsd:restriction> </xsd:simpleType>
The standard defines the structure of the number as well as how to apply the Luhn formula to ensure a correct check digit. This type only specifies the format of the number. The complementary XPath function luhn()
should be used to validate that the ID number conforms to the specification.
<xforms:model> <xforms:instance> <payment method="cc" xmlns="http://commerce.example.com/payment"> <number>4111111111111111</number> <expiry/> </payment> </xforms:instance> <xforms:bind nodeset="number" type="xforms:ID-card-number" constraint="luhn(.)"/> </xforms:model>
This example specifies that the element number
is of the type ID-card-number
and that to be valid the luhn function must evaluate to true indicating that check digit is valid.
Many default XML schema types report empty content as invalid. The following XForms datatypes are defined to allow either empty content or the content allowed by the corresponding XML schema datatype. XForms Processors must treat the datatypes listed in the section as in-scope without requiring the inclusion of an XML Schema.
The indicated XForms datatypes do not allow empty string content and some others already accepted
empty string data. In both cases, they have been added to the available XForms datatypes for form authoring
consistency. They also ease form authoring since these datatypes can be used in the type
model item property without the addition of the XForms namespace qualifier if the namespace context has the XForms namespace as the default namespace.
Built-in primitive types:
xforms:dateTime
xforms:time
xforms:date
xforms:gYearMonth
xforms:gYear
xforms:gMonthDay
xforms:gDay
xforms:gMonth
xforms:string
xforms:boolean
xforms:base64Binary
xforms:hexBinary
xforms:float
xforms:decimal
xforms:double
xforms:anyURI
xforms:QName
Built-in derived types:
xforms:normalizedString
xforms:token
xforms:language
xforms:Name
xforms:NCName
xforms:ID
xforms:IDREF
xforms:IDREFS
xforms:NMTOKEN
xforms:NMTOKENS
xforms:integer
xforms:nonPositiveInteger
xforms:negativeInteger
xforms:long
xforms:int
xforms:short
xforms:byte
xforms:nonNegativeInteger
xforms:unsignedLong
xforms:unsignedInt
xforms:unsignedShort
xforms:unsignedByte
xforms:positiveInteger
This chapter defines infoset contributions that can be bound to instance data nodes with element bind
(see 3.3.4 The bind Element). The combination of these contributions to an instance data node is called a model item. Taken together, these contributions are called model item properties, and are defined in the following section. In contrast, the term Schema constraint refers only to XML Schema constraints from the facets of a given datatype.
Model item properties can be distinguished along various axes.
Computed expressions vs. fixed properties:
Fixed properties are static values that the XForms Processor evaluates only once. Such properties consist of literals, and are not subject to XPath evaluation.
Computed expressions are XPath expressions that provide a value to the XForms Processor. Such values are recalculated at certain times as specified by the XForms Processing Model (see 4 Processing Model). These expressions encode dynamic properties, often constraints, such as the dependency among various data items. Computed expressions are not restricted to examining the value of the instance data node to which they apply. XPath expressions provide the means to traverse the instance data; more complex computations may be encoded as call-outs to external scripts.
Inheritance rules:
Some model item properties define inheritance rules, in which case the XForms Processor needs to keep track of two separate values: 1) the local value, which is applied from an attribute of element bind
, and 2) the inherited value, which is determined by combining the evaluated local value with the evaluated values from ancestor nodes in the instance data.
Note:
The sample recalculation algorithm defined in D Recalculation Sequence Algorithm is defined to operate only on the local values of a model item property. It assumes that an implementation propagates the combined values to a node's descendants.
Assigning local values:
Local values are assigned by processing all bind elements in an XForms Model in document order. It is an error to attempt to set a model item property twice on the same node. The details of this process are given at 4.2.1 The xforms-model-construct Event.
The following sections list the model item properties available as part of all model items. For each, the following information is provided:
Description
Computed Expression (yes or no)
Legal Values
Default Value
Inheritance Rules
Description:
The type model item property can be applied to both elements and attributes.
The type model item property is not applied to instance nodes that contain
child elements.
The type model item property associates a datatype
(as defined in [XML Schema part 2])
with the string-value
(as defined in [XPath 1.0])
of an instance node.
The datatype being associated can be obtained from a simpleType definition
or a simpleContent definition from a complexType. If the datatype cannot
be obtained as just described, then the Default Value of xsd:string
is used.
Computed Expression: No.
Legal Values: Any xsd:QName
representing a datatype definition in an XML Schema.
The namespace context from the parent bind
of the type
attribute is used to resolve the namespace qualification of the value.
Default Value: xsd:string
.
Inheritance Rules: does not inherit.
<model xmlns:my="http://example.org"> <xsd:schema targetNamespace="http://example.org" xmlns:my="http://example.org"> <xsd:simpleType name="Currency"> <xsd:restriction base="xsd:string"> <xsd:enumeration value="USD"/> <xsd:enumeration value="EUR"/> </xsd:restriction> </xsd:simpleType> <xsd:complexType name="Price"> <xsd:simpleContent> <xsd:extension base="xsd:double"> <xsd:attribute name="currency" type="my:Currency" use="optional" default="USD"/> </xsd:extension> </xsd:simpleContent> </xsd:complexType> </xsd:schema> <instance> <data xmlns="http://example.org"> <aString>Hello, world!</aString> <simpleType> <price>100.00</price> <price>abc</price> <price currency="EUR">100.00</price> <price currency="EUR">abc</price> </simpleType> <complexType> <price>100.00</price> <price>abc</price> <price currency="abc">100.00</price> <price currency="EUR">abc</price> </complexType> </data> </instance> <bind nodeset="my:aString" type="xsd:string"/> <bind nodeset="my:simpleType/my:price" type="xsd:double"/> <bind nodeset="my:complexType/my:price" type="my:Price"/> <bind nodeset="my:complexType/my:price[3]/@currency" type="my:Currency"/> <bind nodeset="/my:data" type="xsd:string"/> </model>
The first bind expresses the default datatype of xsd:string.
The second and third binds place type model item properties on each
of the four price
element children of the elements
simpleType
and complexType
. Both binds associate
the datatype xsd:double
with the nodes. In both cases,
the first and third nodes are considered valid according to the type
model item property because their content matches the xsd:double
datatype constraint. For both binds, the second and fourth price
nodes
are not valid due to their content.
The fourth bind places a type model item property on the currency
attribute of the third price
element. According to this association,
the currency
attribute node is not valid because its content does
not match the enumeration given for my:Currency
. Note that
the containing element price
is valid according to its type
model item property.
The fifth bind attempts to associate a datatype with the data
element. The association is ignored since the data
element
contains child elements.
Description: describes whether the value is restricted from changing.
Computed Expression: Yes.
Legal Values: Any expression that is convertible to XPath boolean
with boolean()
.
Default Value: false()
, unless a calculate
property is specified, then true()
.
Inheritance Rules: If any ancestor node evaluates to true
, this value is treated as true
. Otherwise, the local value is used.
Note:
This is the equivalent of taking the logical OR of the evaluated readonly
property on the local and every ancestor node.
When evaluating to true
, this model item property indicates that the XForms Processor should not allow any changes to the bound instance data node.
In addition to restricting value changes, the readonly
model item property provides a hint to the XForms user interface. Form controls bound to instance data with the readonly
model item property should indicate that entering or changing the value is not allowed. This specification does not define any effect on visibility, focus, or navigation order.
<instance> <my:person-name> <my:first-name>Roland</my:first-name> <my:last-name/> </my:person-name> </instance> <bind nodeset="/my:person-name/my:first-name" readonly="true()"/>
Here, we have associated a readonly
property with an element.
Description: describes whether a value is required before the instance data is submitted.
Computed Expression: Yes.
Legal Values: Any expression that is convertible to XPath boolean
with boolean()
.
Default Value: false()
.
Inheritance Rules: does not inherit.
A form may require certain values, and this requirement may be dynamic. When evaluating to true
, this model item property indicates that a non-empty instance data node is required before a submission of instance data can occur. Non-empty is defined as:
If the bound instance data node is an element, the element must not have the xsi:nil
attribute set to true
.
The value of the bound instance data node must be convertible to an XPath string
with a length greater than zero.
Except as noted below, the required
model item property does not provide a hint to the XForms user interface regarding visibility, focus, or navigation order. XForms authors are strongly encouraged to make sure that form controls that accept required
data are visible. An XForms Processor may provide an indication that a form control is required, and may provide immediate feedback, including limiting navigation. Chapter 4 Processing Model contains details on how the XForms Processor enforces required values.
<instance> <my:person-name> <my:first-name>Roland</my:first-name> <my:last-name /> </my:person-name> </instance> <bind nodeset="/my:person-name/my:last-name" required="true()"/>
Here, we have associated a required
property with element my:last-name
to indicate that a value must be supplied.
Note:
XML Schema has a similarly named concept with use
="required|optional|prohibited"
. This is different than the XForms Model item property, in two ways: 1) use
applies only to attributes, while XForms required
applies to any node. 2) use
is concerned with whether the entire attribute must be specified (without regard to value), while required
determines whether a value is required of the node before submission.
Description: indicates whether the model item is currently relevant. Instance data nodes with this property evaluating to false
are not serialized for submission.
Computed Expression: Yes.
Legal Values: Any expression that is convertible to XPath boolean
with boolean()
.
Default Value: true()
.
Inheritance Rules: If any ancestor node evaluates to XPath false
, this value is treated as false
. Otherwise, the local value is used.
Note:
This is the equivalent of taking the logical AND of the evaluated relevant
property on the local and every ancestor node.
Many forms have data entry sections that depend on other conditions. For example, a form might ask whether the respondent owns a car. It is only appropriate to ask for further information about their car if they have indicated that they own one.
The relevant
model item property provides information to the XForms user interface regarding visibility, focus, and navigation order. In general, when true
, associated form controls should be made visible. When false
, associated form controls (and any children) and group and switch elements (including content) must be made unavailable, removed from the navigation order, and not allowed focus. Typically, non-relevant content is not presented, or it may be styled as disabled.
Note:
A form control, group or switch must express a single node binding in order to be associated with an instance node.
<instance> <my:order> <my:item> <my:amount /> <my:discount>100</my:discount> </my:item> </my:order> </instance> <bind nodeset="my:item/my:discount" readonly="true()" relevant="../my:amount > 1000"/>
Here, we have associated a relevant
property with element my:discount
to indicate a discount is relevant when the order amount is greater than 1000.
Description: supplies an expression used to calculate a string value for the associated instance data node.
Computed Expression: Yes.
Legal Values: Any XPath expression.
Default Value: none.
Inheritance Rules: does not inherit.
An XForms Model may include model items whose string values are computed from other values. For example, the sum over line items for quantity times unit price, or the amount of tax to be paid on an order. Such computed values can be expressed with calculate
properties, whose XPath expressions are evaluated and converted to strings with the XPath string()
function. Chapter 4 Processing Model contains details of when and how the calculation is performed.
<instance> <my:order> <my:item> <my:amount /> <my:discount /> </my:item> </my:order> </instance> <bind nodeset="my:item/my:discount" calculate="../my:amount * 0.1" relevant="../my:amount > 1000"/>
Here, we have associated a relevant
property with element my:discount
to indicate a discount of 10% is relevant when the order amount is greater than 1000.
Description: specifies a predicate that needs to be satisfied for the associated instance data node to be considered valid.
Computed Expression: Yes.
Legal Values: Any expression that is convertible to XPath boolean
with boolean()
.
Default Value: true()
.
Inheritance Rules: does not inherit.
When evaluating to XPath false
, the associated model item is not valid; the converse is not necessarily true. Chapter 4 Processing Model contains details of when and how the constraint is calculated as well as when validation is performed.
<instance> <my:range> <my:from /> <my:to /> </my:range> </instance> <bind nodeset="my:to" constraint=". > ../my:from" />
Here, a constraint
property associated with element my:to
indicates that its value must be greater than that of element my:from
.
Note:
Specifying minimum and maximum occurrences for nodes in the instance data can be achieved by using the count()
function within a constraint
property.
Description: Attaches a P3P data element to an instance data node, indicating the specific kind of data collected there.
Computed Expression: No.
Legal Values: xsd:string
.
Default Value: none
Inheritance Rules: does not inherit.
This model item property holds a description of the kind of data collected by the associated instance data node, based on the P3P datatype system [P3P 1.0]. This information may be used to enhance the form-fill experience, for example by supplying previously-known data.
<instance> <my:person-name> <my:first-name /> <my:last-name /> </my:person-name> </instance> <bind type="my:nonEmptyString" nodeset="my:first-name" p3ptype="user.name.given"/>
Here, we have attached both XML Schema and P3P type information to element first-name
via element bind
.
Chapter 5 Datatypes described how XForms uses the XML Schema datatype system to constrain the value space of data values collected by an XForms Model. Such datatype constraints can be provided via an XML Schema. Alternatively, this section lists various mechanisms for attaching type constraints to instance data. Attributes xsi:schemaLocation
and xsi:noNamespaceSchemaLocation
are ignored for purposes for locating a Schema.
The XForms Processing Model applies XML Schema facets as part of the validation process. At the simplest level, it is necessary to associate a set of facets (through an XML Schema datatype) with a model item. This has the effect of restricting the allowable values of the associated instance data node to valid representations of the lexical space of the datatype.
The set of facets associated with a model item must be determined by the following list, as if it were processed in the given order. When multiple datatype restrictions apply to the same model item, the combination of all given restrictions must apply. Note that it is possible to produce a combination of restrictions that is impossible to satisfy; authors are encouraged to avoid this practice.
An XML Schema associated with the instance data.
An XML Schema xsi:type
attribute in the instance data.
An XForms type
constraint associated with the instance data node using XForms binding.
If no type constraint is provided, the instance data node defaults to type="xsd:string"
(default to string rule).
The following declares a datatype based on xsd:string
with an additional constraining facet.
<xsd:simpleType name="nonEmptyString"> <xsd:restriction base="xsd:string"> <xsd:minLength value="1"/> </xsd:restriction> </xsd:simpleType>
This new datatype would then be associated with one or more model items through one of the methods outlined here.
<my:first-name xsi:type="my:nonEmptyString"/>
This defines element first-name
to be of type my:nonEmptyString
.
<instance> <my:first-name /> </instance> <bind type="my:nonEmptyString" nodeset="/my:first-name"/>
Here, we have attached type information to element first-name
via element bind
. Thus the XForms author can extend external schemas without having the ability to change them.
XForms uses XPath to address instance data nodes in binding expressions, to express constraints, and to specify calculations. XPath expressions that are not syntactically valid, including attempted calls to undefined functions, result in an exception (4.5.4 The xforms-compute-exception Event), except for binding expressions, which produce a different exception (4.5.1 The xforms-binding-exception Event).
XPath datatypes are used only in binding expressions and computed expressions. XForms uses XPath datatypes boolean
, string
, number
, and node-set
. A future version of XForms is expected to use XPath 2.0, which includes support for XML Schema datatypes.
For this version of the XForms specification, the feature string for the [DOM2 Core] DOMImplementation
interface hasFeature
method call is "org.w3c.xforms.dom"
and the version string is "1.0"
.
For each model
element, the XForms Processor maintains the state in an internal structure called instance data that conforms to the XPath Data Model [XPath 1.0]. XForms Processors that implement DOM must provide DOM access to this instance data via the interface defined below.
Note:
Instance data always has a single root element, and thus corresponds to a DOM Document.
The IDL for this interface follows:
#include "dom.idl" pragma prefix "w3c.org" module xforms { interface XFormsModelElement : dom::Element { dom::Document getInstanceDocument(in dom::DOMString instanceID) raises(dom::DOMException); void rebuild(); void recalculate(); void revalidate(); void refresh(); }; };
If the instance-id
parameter is the empty string, then the document element of the default instance is returned. Otherwise, this method returns a DOM Document that corresponds to the instance data associated with the instance
element containing an ID
matching the instance-id
parameter. If there is no matching instance data, a DOMException
is thrown.
This method signals the XForms Processor to rebuild any internal data structures used to track computational dependencies within this XForms Model. This method takes no parameters and raises no exceptions.
This method signals the XForms Processor to perform a full recalculation of this XForms Model. This method takes no parameters and raises no exceptions.
Within XForms, the default model is the first model
in document order. The default instance of any model
is the first child instance
in document order within that model
.. XPath expressions appearing in various XForms attributes are used to reference instance data . Every XPath expression requires an evaluation context consisting of a node, position, size, variable bindings, function set, and namespace context. For all evaluation contexts in XForms,
No variable bindings are in place.
The available function library is defined below in 7.6 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.
A binding element is any element that is explicitly allowed to have a binding expression attribute, and a bound element is any element that explicitly declares a binding expression attribute. A binding expression attribute contains an XPath expression that references zero or more nodes of instance data. Every XPath expression requires an evaluation context. The in-scope evaluation context of a binding element provides an evaluation context for the binding expression attribute. The following rules are used in determining the node, position and size of the in-scope evaluation context:
A binding element is "outermost" if the element has no ancestor binding elements. If an outermost binding element is contained by a model
, then the context node for the outermost binding element is the top-level document element node of the default instance of the containing model
element. Otherwise, the context node for outermost binding elements is the top-level document element node of the default instance in the default model. For outermost binding elements, the context size and position are 1.
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. The dynamic in-scope evaluation context for each generated occurrence of the non-outermost binding element has a context size equal to the size of the nodeset identified by the Node Set Binding of the nearest ancestor binding element, the context node is the node for which the occurrence of the non-outermost binding element was generated, and the position is equal to the position of the generator node in the nodeset identified by the Node Set Binding of the nearest ancestor binding element.
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 a model
attribute that refers to a model
other than the one containing the context node, then the context node of the in-scope evaluation context is changed to be the top-level document element node of the default instance of the referenced model
, and the context position and size are changed to 1.
Note:
The rules above for determining the in-scope evaluation context are applicable to XForms elements that can contain a binding expression attribute even if they cannot contain a Single Node Binding or Node Set Binding. The elements bind
and submission
are examples.
The in-scope evaluation context of an element that is not a binding element is the same as if the element were a binding element. For example, the in-scope evaluation context for the setindex
action element is required to provide the context for evaluating the index
attribute, so it is determined as if the element could contain a binding expression attribute.
XPath expressions also appear in model item property attributes of the bind
element to define computed expressions. If the bind
element does not express a Node Set binding, then the in-scope evaluation context for model item property attributes of the bind
is equal to the in-scope evaluation context for the bind
. Otherwise, the bind
has a Node Set binding, and computed expressions for each model item property attribute are generated for each node. For each computed expression generated, the evaluation context node, position and size are determined by the same method as dynamic in-scope evaluation context rule above, except the computed expression is used in lieu of a binding expression attribute such that the bind
element is the nearest ancestor binding element.
XPath expressions also appear in the special attributes of several other XForms elements, such as the value
attribute on setvalue
and output
, the at
attribute of insert
and delete
, or the index
attribute of setindex
. Generally, if the containing element does not express a Single Node Binding or Node Set Binding, then the special attribute is evaluated using the in-scope evaluation context. Special attributes may be evaluated using the in-scope evaluation context even if the containing element expresses a Single Node Binding or Node Set Binding. However, for some special attributes, the evaluation context node, position and size are based on the result of the Single Node Binding or Node set Binding. Each special attribute that contains an XPath expression describes how its evaluation context node, position and size are determined.
In the following example, the group
has a binding expression of level2/level3
. According to the rules above, this outermost element node would have a context node of /level1
, which is the document element node of the instance data. The select1
form control then inherits a context node from the parent group.
<level1> <level2> <level3 attr="xyz"/> </level2> </level1>
<group ref="level2/level3"> <select1 ref="@attr" ... > <label>...</label> </select1> </group>
This section describes how the in-scope evaluation context of an element is determined, not whether the in-scope evaluation will be used. The Single-Node Binding or Node Set Binding of a non-outermost binding element is not evaluated if the in-scope evaluation context does not contain a context node. This can occur if the Single-Node Binding or Node Set Binding of the nearest ancestor bound element produces an empty nodeset. Also, if the Single-Node Binding or Node Set Binding of an element is expressed with the bind
attribute, then the resulting node or nodeset is obtained from the referenced bind
element. The nodeset
attribute of a bind
element is evaluated using the in-scope evaluation of the bind
element, not the in-scope evaluation context of an element that references it with a bind
attribute.
A binding expression is an XPath expression used in binding a model item property to one or more instance nodes, or to bind a form control to instance data, or to specify the node or node set for operation by an action. By default, all binding expressions refer to the first instance within the context model. This behavior can be changed with the instance()
function.
Not every possible XPath expression is acceptable as a binding expression. In particular, there are restrictions on model binding expressions that create dynamic dependencies, which are defined as follows:
An XPath predicate (in square brackets) is a possibly implicit boolean test. A dynamic dependency exists on any predicate unless all terms in the test are "fixed", where fixed means either a constant, or a value that will not change between operations explicitly defined as rebuilding computational dependencies.
Note:
For purposes of determining dynamic dependencies, the following subexpressions are considered fixed: position()
, last()
, count()
, and property()
. This is because the specification mandates a dependency rebuild after any event that could change the values returned by these functions.
Another dynamic dependency is any use of the id()
function, unless both the parameter to the function and the matching attribute of type xsd:ID
are fixed. In the same way, the instance()
function is dynamic unless the parameter to the function is fixed.
XPath variables that change in value from one recalculate to the next would also create dynamic dependencies (though XForms defines an empty variable context for all XPath expressions).
Authors that define extension functions are encouraged to follow these rules.
A model binding expression is a kind of binding expression that can be used to declare model item properties, and is used in attributes of the bind
element.
Dynamic dependencies in model binding expressions will generally require manual rebuilding of dependencies.
Binding references can be used to bind form controls to the underlying instance data as described here. Different attribute names, ref
and nodeset
distinguish between a single node and a node-set respectively. See 3.2.3 Single-Node Binding Attributes and 3.2.4 Node-Set Binding Attributes.
Dynamic dependences are allowed in UI binding expressions based on the conformance profile.
The XForms binding mechanism allows other XML vocabularies to bind user interface controls to an XForms Model using any of the techniques shown here. As an example, XForms binding attribute bind
might be used within XHTML 1.x user interface controls as shown below. See 3.2.3 Single-Node Binding Attributes and 3.2.4 Node-Set Binding Attributes.
<html:input type="text" name="..." xforms:bind="fn"/>
Consider the following document with the one-and-only XForms model:
<xforms:model id="orders"> <xforms:instance xmlns=""> <orderForm> <shipTo> <firstName>John</firstName> </shipTo> </orderForm> </xforms:instance> <xforms:bind nodeset="/orderForm/shipTo/firstName" id="fn" /> </xforms:model>
The following examples show three ways of binding user interface control xforms:input
to instance element firstName
declared in the model shown above.
ref
<xforms:input ref="/orderForm/shipTo/firstName">...
bind
<xforms:input bind="fn">...
<xforms:input model="orders" ref="/orderForm/shipTo/firstName">...
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.7 Boolean Functions, 7.8 Number Functions, 7.9 String Functions, 7.10 Date and Time Functions and 7.11 Node-set Functions.
The function library provided by an XForms processor may also contain other extension functions as described in 7.12 Extension Functions.
If an error occurs in an XPath function, an xforms-compute-exception
occurs if the function appears in the expression of a model item property.
If the error occurs in a function that appears in any other XForms attribute that contains an XPath expression, such as nodeset
, ref
or at
,
then an xforms-binding exception
occurs.
boolean boolean-from-string(string)
Function boolean-from-string
returns true
if the required parameter string
is
"true" or "1", or false
if parameter string
is "false", or "0". This is useful when referencing a
Schema xsd:boolean
datatype in an XPath expression. If the parameter string matches none of the above strings,
according to a case-insensitive comparison, the return value is false
.
number avg(node-set)
Function avg
returns the arithmetic average of the result of converting the string-values of each node in
the argument node-set to a number. The sum is computed with sum()
, and divided with div
by the
value computed with count()
. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN
,
the return value is NaN
.
number min(node-set)
Function min
returns the minimum value of the result of converting the string-values of each node in argument node-set
to a number. "Minimum" is determined with the <
operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN
, the return value is NaN
.
number max(node-set)
Function max
returns the maximum value of the result of converting the string-values of each node in argument node-set
to a number. "Maximum" is determined with the <
operator. If the parameter is an empty node-set, or if any of the nodes evaluate to NaN
, the return value is NaN
.
number count-non-empty(node-set)
Function count-non-empty
returns the number of non-empty nodes in argument node-set
. A node is considered non-empty if it is convertible into a string with a greater-than zero length.
number index(string)
Function index
takes a string argument that is the IDREF
of a repeat
and returns the
current 1-based position of the repeat index for the identified repeat
—see 9.3.1 The repeat Element for details on
repeat
and its associated repeat index. if the specified argument does not identify a repeat
,
the function returns NaN
.
Note:
The IDREF obtained from the function parameter may not uniquely identify
the desired repeat
if the repeat
element bearing the
matching ID resides
in a repeating construct such as element repeat
.
The general method described in
4.7 Resolving ID References in XForms
is used to determine the desired run-time case object.
<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>
number power(number, number)
Raises the first argument to the power of the second argument, returning the result. If
the calculation does not result in a real number, then NaN
is returned.
Examples:
power(-1, 0.5)
returns NaN
.
if (prin>0 and dur>0 and rate>0, prin*rate/(1-power(1+rate, -dur)), 0)
returns a compounded interest payment value given a non-zero principal (prin
),
duration (dur
) and periodic interest rate (rate
).
boolean luhn(string?)
If the string parameter conforms to the pattern restriction of the xforms:ID-card-number type, then this function applies the luhn
formula described in [ISO 7812-1:2000] 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 also 5.2.6 xforms:ID-card-number):
luhn(.)
returns true
if and only if the context node contains a string that contains 12 to 19 digits and satisfies the formula.
luhn('4111111111111111')
returns true
. Other examples of string constants that will return true
are : 5431111111111111
, 341111111111111
and 6011601160116611
.
luhn('123')
returns false
.
number random(boolean?)
This function generates and returns a uniformly distributed random or pseudorandom number between 0.0 and 1.0.
This function accepts an optional boolean parameter that is false
by default. If true
, the
random number generator for this function is first seeded with a source of randomness before generating the return value.
A typical implementation may seed the random number generator with the current system time in milliseconds when
random(true)
is invoked, and it may apply a linear congruential formula to generate return values on
successive invocations of the function.
Example:
random()
could return 0.14159265358979
string property(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 with full or basic |
Any other NCNAME | Reserved. Their use results in an exception (see 7.6 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:
property('version')
returns 1.1
property('conformance-level')
may return full
string encode(string, string?)
This function accepts a string of data and an optional string indicating an encoding method. The data string is serialized as UTF-8,
and the result is encoded by the indicated method and returned by the function. This recommendation defines the values
hex
and base64
for the second string parameter that indicates the encoding method. If the parameter
is missing, then the default is base64
. The hex
and base64
encoding methods of this
function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary
and
base64Binary
, respectively. Any other string value given for the encoding method results in an
exception (see 7.6 The XForms Function Library for the exception type).
Example:
encode('abc', 'hex')
returns 616263
string decode(string, string?)
This function accepts a string of data and an optional string indicating the encoding of the data. This recommendation defines the
values hex
and base64
for the second string parameter that indicates the data encoding. If the parameter
is missing, then the default is base64
. The hex
and base64
encoding methods of this function
correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary
and
base64Binary
, respectively. Any other string value given for the encoding method results in an
exception (see 7.6 The XForms Function Library for the exception type).
The data is base64 or hex decoded. If the data violates any base64 or hex encoding rules, such as containing invalid characters for the encoding, then an exception occurs (see 7.6 The XForms Function Library for the exception type). If the decoding succeeds, the result is interpreted as a UTF-8 serialization, and it is converted to an XPath string.If the decoded data is found to violate the UTF-8 encoding rules, then an empty string is returned. Otherwise, the XPath string result is returned.
Examples:
decode('616263', 'hex')
returns abc
decode('abcdefg', 'hex')
results in an exception due to odd length of data and invalid character in data
string digest(string, string, string?)
This function accepts a string of data, a string indicating a cryptographic hashing algorithm, and an optional string indicating an encoding method. The data string is serialized as UTF-8, the hash value is then computed using the indicated hash algorithm, and the hash value is then encoded by the indicated method, and the result is returned by the function. The following table presents the keywords for the second string parameter and the corresponding hash algorithms:
Keywords | Hash Algorithm | Status |
---|---|---|
md5, MD5 | The MD5 hash algorithm defined in [MD5] | Required |
sha1, sha-1, SHA1, SHA-1 | The SHA-1 hash algorithm defined in [SHA2] | Required |
sha256, sha-256, SHA256, SHA-256 | The SHA-256 hash algorithm defined in [SHA2] | Required |
sha384, sha-384, SHA384, SHA-384 | The SHA-384 hash algorithm defined in [SHA2] | Optional |
sha512, sha-512, SHA512, SHA-512 | The SHA-512 hash algorithm defined in [SHA2] | Optional |
Any other NCNAME | Reserved. Their use results in an exception (see 7.6 The XForms Function Library for the exception type) | Required |
QNameButNotNCNAME | An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see 7.6 The XForms Function Library for the exception type). | Required |
This recommendation defines the values hex
and base64
for the third string parameter that indicates
the encoding method. If the parameter is missing, then the default is base64
. The hex
and base64
encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary
and base64Binary
, respectively. Any other string value given for the encoding method results in an exception
(see 7.6 The XForms Function Library for the exception type).
hash-encode('abc', 'sha1', 'hex')
returns a9993e364706816aba3e25717850c26c9cd0d89d
.
hash-encode('abc', 'md5', 'hex')
returns 900150983cd24fb0d6963f7d28e17f72
.
hash-encode('abc', 'sha256', 'hex')
returns ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
string hmac(string, string, string, string?)
This function accepts a string for a key or shared secret, a string of data, a string indicating a cryptographic hashing algorithm, and an optional string indicating an encoding method. The key and data strings are serialized as UTF-8, and they are subjected to the HMAC algorithm defined in [HMAC] and parameterized by the the hash algorithm indicated by the third parameter. The result is encoded with the method indicated by the fourth parameter, and the result is returned by the function.
The following table presents the keywords for the third string parameter and the corresponding hash algorithms:
Keywords | Hash Algorithm | Status |
---|---|---|
md5 | The MD5 hash algorithm defined in [MD5] | Required |
sha1, sha-1, SHA1, SHA-1 | The SHA-1 hash algorithm defined in [SHA2] | Required |
sha256, sha-256, SHA256, SHA-256 | The SHA-256 hash algorithm defined in [SHA2] | Required |
sha384, sha-384, SHA384, SHA-384 | The SHA-384 hash algorithm defined in [SHA2] | Optional |
sha512, sha-512, SHA512, SHA-512 | The SHA-512 hash algorithm defined in [SHA2] | Optional |
Any other NCNAME | Reserved. Their use results in an exception (see 7.6 The XForms Function Library for the exception type) | Required |
QNameButNotNCNAME | An implementation-specific hash algorithm is used. If the implementation does not support the indicated hash algorithm, then an exception occurs (see 7.6 The XForms Function Library for the exception type). | Required |
This recommendation defines the values hex
and base64
for the fourth string parameter that indicates
the encoding method. If the parameter is missing, then the default is base64
. The hex
and base64
encoding methods of this function correspond to the encodings defined in [XML Schema part 2] for the datatypes hexBinary
and base64Binary
, respectively. Any other string value given for the encoding method results in an exception
(see 7.6 The XForms Function Library for the exception type).
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.
string now()
The now
function returns the current system date and time as a string value in the canonical
XML Schema xsd:dateTime
format. If time zone information is available, it is included (normalized to UTC).
If no time zone information is available, an implementation default is used.
Note:
Attaching a calculation of "now()
" to an instance data node would not result in a stream of continuous
recalculations of the XForms Model.
number days-from-date(string)
This function returns a whole number of days, according to the following rules:
If the string parameter represents a legal lexical xsd:date
or xsd:dateTime
, the return value
is equal to the number of days difference between the specified date or dateTime (normalized to UTC) and 1970-01-01
.
Hour, minute, and second components are ignored after normalization. Any other input parameter causes a return value of NaN
.
Examples:
days-from-date("2002-01-01")
returns11688
days-from-date("1969-12-31")
returns-1
string days-to-date(number)
This function returns a string containing a lexical xsd:date
that corresponds to the number of days passed as the parameter according to the following rules:
The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between the desired date and
1970-01-01
. An input parameter value of NaN
results in output of the empty string.
Examples:
days-to-date(11688)
returns 2002-01-01
days-to-date(-1)
returns 1969-12-31
number seconds-from-dateTime(string)
This function returns a possibly fractional number of seconds, according to the following rules:
If the string parameter represents a legal lexical xsd:dateTime
, the return value is equal to the number of seconds difference
between the specified dateTime (normalized to UTC) and 1970-01-01T00:00:00Z
. If no time zone is specified, UTC is used.
Any other input string parameter causes a return value of NaN
.
string seconds-to-dateTime(number)
This function returns string containing a lexical xsd:dateTime
that corresponds to the number of seconds
passed as the parameter according to the following rules:
The number parameter is rounded to the nearest whole number, and the result is interpreted as the difference between
the desired dateTime and 1970-01-01T00:00:00Z
. An input parameter value of NaN
results in output of the empty string.
Example:
seconds-to-dateTime(0)
returns 1970-01-01T00:00:00Z
string local-date()
This function returns a lexical xsd:date
obtained as if by the following rules: the result of now()
is
converted to a local date based on the user agent time zone information. If no time zone information is available, then the date portion
of the result of now()
is returned.
Example:
local-date()
could return 2006-10-13-07:00
substring(local-date(), 1, 10)
could return 2006-10-13
string local-dateTime()
This function returns a lexical xsd:dateTime
obtained as if by the following rules: the result of now()
is
converted to a local dateTime based on the user agent time zone information. If no time zone information is available, then the result of
now()
is returned.
Example:
local-dateTime()
could return 2006-10-13T16:04:17-07:00
number seconds(string)
This function returns a possibly fractional number of seconds, according to the following rules:
If the string parameter represents a legal lexical xsd:duration
, the return value is equal to the number specified in the
seconds component plus 60 * the number specified in the minutes component, plus 60 * 60 * the number specified in the hours component,
plus 60 * 60 * 24 * the number specified in the days component. The sign of the result will match the sign of the duration. Year and month
components, if present, are ignored. Any other input parameter causes a return value of NaN
.
Examples:
seconds("P1Y2M")
returns0
seconds("P3DT10H30M1.5S")
returns297001.5
seconds("3")
returnsNaN
Note:
Even though this function is defined based on a lexical xsd:duration
, it is intended for use only with
derived-from-xsd:duration
datatypes, specifically xforms:dayTimeDuration
.
number months(string)
This function returns a whole number of months, according to the following rules:
If the string parameter represents a legal lexical xsd:duration
, the return value is equal to the number specified in the
months component plus 12 * the number specified in the years component. The sign of the result will match the sign of the duration.
Day, hour, minute, and second components, if present, are ignored. Any other input parameter causes a return value of NaN
.
Examples:
months("P1Y2M")
returns14
months("-P19M")
returns-19
Note:
Even though this function is defined based on a lexical xsd:duration
, it is intended for use only with
derived-from-xsd:duration
datatypes, specifically xforms:yearMonthDuration
.
node-set instance(string?)
An XForms Model can contain more that 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 the string
function.
This string is treated as an IDREF, which is matched against instance
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="" id="orderform"> <orderForm> <shipTo> <firstName>John</firstName> </shipTo> </orderForm> </xforms:instance>
The following expression selects the firstName
node. Note that the instance
function returns an element node, effectively replacing the leftmost location step from the path:
ref="instance('orderform')/shipTo/firstName"
node-set current()
Returns the context 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="" id="convTable"> <convTable date="20040212" currency="cdn"> <rate currency="eur">0.59376</rate> <rate currency="mxn">8.37597</rate> <rate currency="jpy">80.23451</rate> <rate currency="usd">0.76138</rate> </convTable> </xforms:instance>
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 the rate
element whose currency
attribute value
matches the content of /converter/currency
.
For the following instance data:
<xforms:instance xmlns="" id="i1"> <months> <mon>01</mon> <mon>02</mon> <mon>03</mon> </months> </xforms:instance> <xforms:instance xmlns="" id="i2"> <months> <month code="01">Jan</month> <month code="02">Feb</month> <month code="03">Mar</month> </months> </xforms:instance>
and the following repeat structure:
<repeat nodeset="mon"> <output value="instance('i2')/month[@code = current()]/> </repeat>
the output should contain Jan Feb Mar
.
object choose(boolean, object, object)
If the boolean parameter is true, then the first object is returned, otherwise the second object is returned. If the types of the two object parameters are not the same (e.g. one node-set and the other a string), then the type of the object returned is determined by rationalizing the types of the two object parameters in the same manner as XPath comparison.
Example:
choose(count(x) > 0, x, y)
Returns the node-set of matching x
if it is non-empty and the node-set matching y
otherwise.
node-set id(object, node-set?)
The object
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. The node-set
parameter provides nodes in one or more documents to be searched. If the node-set parameter is not given or is empty,
then the 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 the
object
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 an xml: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, an xsi:type
attribute, or the type
model item property.
Example:
id('X Y', instance('Z'))
Returns nodes identified by X or Y from the XML document in the instance identified by Z.
object event(string)
Function event
returns context specific information determined by the string
argument. The returned context information is an XPath object whose type and content
depends 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 other XPath expression, such as a binding expression or model item property expression, this function returns the 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 the string argument, then an empty node-set is returned.
Examples:
event('binding')
If called from an xforms-insert
event handler, a string is returned containing the attribute value of the nodeset
or bind
attribute used by the insert
action.
event("resource-uri")
If called from an xforms-link-exception
or xforms-link-error
event handler, a string is returned containing the URI of the failed link.
XForms documents may use additional XPath extension functions beyond those described here. A number of useful community extensions are defined at [EXSLT]. The names of any such extension functions must be declared in attribute functions
on element model
. Such declarations are used by the XForms Processor to check against available extension functions. XForms Processors perform this check at the time the document is loaded, and stop processing by signaling an exception (4.5.4 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 error 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.
Form controls are declared using markup elements, and their behavior refined via markup attributes.
Element | Attributes | Minimal Content Model |
---|---|---|
input | Common, UI Common, Single Node Binding, inputmode (xsd:string), incremental (xsd:boolean) | label, (UI Common)* |
secret | Common, UI Common, Single Node Binding, inputmode (xsd:string), incremental (xsd:boolean) | label, (UI Common)* |
textarea | Common, UI Common, Single Node Binding, inputmode (xsd:string), incremental (xsd:boolean) | label, (UI Common)* |
output | Common, Single Node Binding (optional), appearance ("full"|"compact"|"minimal"|xforms:QNameButNotNCNAME), value (XPath Expression), mediatype (xsd:string) | label?, mediatype?, (UI Common)* |
upload | Common, UI Common, Single Node Binding, mediatype (xsd:string), incremental (xsd:boolean) | label, filename?, mediatype?, (UI Common)* |
range | Common, UI Common, Single Node Binding, start (xsd:string), end (xsd:string), step (xsd:string), incremental (xsd:boolean) | label, (UI Common)* |
trigger | Common, UI Common, Single Node Binding (optional) | label, (UI Common)* |
submit | Common, UI Common, Single Node Binding (optional), submission (xsd:IDREF) | label, (UI Common)* |
select | Common, UI Common, Single Node Binding, selection ("open" | "closed"), incremental (xsd:boolean) | label, (List UI Common)+, (UI Common)* |
select1 | Common, UI Common, Single Node Binding, selection ("open" | "closed"), incremental (xsd:boolean) | label, (List UI Common)+, (UI Common)* |
choices | Common | label?, (List UI Common)+ |
item | Common | label, value, (UI Common)* |
filename | Common, Single Node Binding | EMPTY |
mediatype | Common, Single Node Binding | EMPTY |
value | Common, Single Node Binding (optional) | (PCDATA|ANY)* |
label | Common, Single Node Binding (optional) | (PCDATA|(UI Inline))* |
help | Common, Single Node Binding (optional) | (PCDATA|(UI Inline))* |
hint | Common, Single Node Binding (optional) | (PCDATA|(UI Inline))* |
alert | Common, Single Node Binding (optional) | (PCDATA|(UI Inline))* |
See also: 9.3.3 The itemset Element.
Note:
Unless bound to form controls, instance data nodes are not presented to the user; consequently, there is no need for a form control corresponding to HTML input type="hidden"
.
The following attributes are common to many user-interface related XForms elements, here called the UI Common
attribute group.
Element | Attributes |
---|---|
(various) | appearance ("full"|"compact"|"minimal"|QName-but-not-NCName) |
Optional attribute to define an appearance hint. If absent, the user agent may freely choose any suitable rendering.
Note:
A host language is expected to add attributes such as xml:lang
as well as an attribute, named class
, that holds a list of strings that can be matched by CSS class selectors.
Further, a host language must provide a way to indicate overall navigation order among form controls and other elements included in the host language, as well as keyboard or direct access navigation to specific elements. One such proposal is to uses a pair of attributes named navindex
and accesskey
, defined as follows:
Optional attribute is a non-negative integer in the range of 0-32767 used to define the navigation sequence. This gives the author control over the sequence in which form controls are traversed. The default navigation order is specified in the chapter 4 Processing Model.
Optional attribute defines a shortcut for moving the input focus directly to a particular form control. The value of this is a single character which when pressed together with a platform specific modifier key (e.g., the alt key) results in the focus being set to this form control.
The user agent must provide a means of identifying the accesskeys that can be used in a presentation. This may be accomplished in different ways by different implementations, for example through direct interaction with the application or via the user's guide. The accesskey requested by the author might not be made available by the player (for example it may not exist on the device used, or it may be used by the player itself). Therefore the user agent should make the specified key available, but may map the accesskey to a different interaction behavior.
Additionally, this module defines the following content sets:
Content Set | Minimal Content Model |
---|---|
UI Common | (help|hint|alert|Action)* |
List UI Common | (choices|item|itemset)+ |
Form Controls | (input|secret|textarea|output|upload|range|trigger|submit|select|select1)* |
UI Inline | (output)* |
As shown above, the XML Events module adds the Actions content set into the UI Common content set. A host language should add inline markup to the Inline content set. When the XForms Extension module is present, it too should be included in the UI Common content set.
XForms user interface controls are bound to the underlying instance data using binding attributes as defined in the chapter 6 Model Item Properties.
Form controls enable accessibility by taking a uniform approach to such features as labels, help text, navigation, and keyboard shortcuts. Internationalization issues are addressed by following the same design principles as in XHTML. All form controls are suitable for styling as aural or visual media.
Form controls encapsulate high-level semantics without sacrificing the ability to deliver real implementations. For instance, the form control select
enables the user to select items from a set. These form controls distinguish the functional aspects of the underlying control from the presentational and behavioral aspects. This separation enables the expression of the intent underlying a particular form control—see [AUI97] for a definition of such high-level user interaction primitives.
Form controls when rendered display the underlying data values to which they are bound. While the data presented to the user through a form control must directly correspond to the bound instance data, the display representation is not required to match the lexical value. For example, user agents should apply appropriate conventions to the display of dates, times, durations and numeric values including separator characters.
All form controls must meet the following implementation requirements:
If a form control violates its data binding restriction, an xforms-binding-exception
must occur.
Form controls that write simpleContent to instance data must do so exactly as defined by the XForms Action 10.8 The setvalue Element
All form controls that read simpleContent instance data must do so as follows:
Element nodes: If element child nodes are present, then
an xforms-binding-exception
occurs. Otherwise,
if text child nodes are present, returns the string-value of the first text child node. Otherwise, returns "" (the empty string)
Attribute nodes: returns the string-value of the node.
Text nodes: returns the string-value of the node.
Namespace, processing instruction, comment, and the XPath root node: behavior is undefined.
Form controls must distinguish rendering between valid and invalid states. Control of this behavior should be made available to stylesheets.
Form controls must indicate when the bound instance data contains a value the form control is not capable of rendering. Control of this behavior should be made available to stylesheets.
Form controls must render upon request an explanation of the current state of a form control, including validity and associated model item properties. Control of this behavior should be made available to stylesheets.
Form controls must provide a default explanation for the above when no user-specified explanation is available.
Form controls are considered to be non-relevant if any of the following apply:
the Single Node Binding is expressed and resolves to empty nodeset,
the Single Node Binding is expressed and resolves to a non-relevant instance node,
the form control is contained by a non-relevant switch
or group
(which includes a non-relevant repeat
item), or
the form control is contained by a non-selected case
element of a switch
.
When a form control becomes non-relevant, it must receive event xforms-disabled
and then the
XForms action handlers that are listening for events on the non-relevant form control must be disabled.
When a non-relevant form control changes to being relevant, the XForms action handlers that listen for
events on the form control must become enabled and then the form control must be updated to represent the
current value(s) and model item properties of the instance node(s) to which it is bound or to which it refers.
The following events must be dispatched to the form control: xforms-enabled
, xforms-value-changed
,
one of xforms-valid
or xforms-invalid
, one of xforms-readonly
or xforms-readwrite
,
one of xforms-required
or xforms-optional
, and one of xforms-in-range
or xforms-out-of-range
.
Sections in this chapter define the various form controls by specifying the following:
Description
Common Attributes
Special Attributes
Examples
Data Binding Restrictions
Implementation Requirements
Description: This form control enables free-form data entry.
Common Attributes: Common, UI Common, Single Node Binding
Special Attributes:
Optional. This form control accepts an input mode hint. E Input Modes.
when true
, this form control will generate additional xforms-value-changed
events. The default value for this attribute is false
.
Example:
<input ref="order/shipTo/street" class="streetAddress"> <label>Street</label> <hint>Please enter the number and street name</hint> </input>
In the above, the class
attribute can be used by a style sheet to specify the display size of the form control. Note that the constraints on how much text can be input are obtained from the underlying XForms Model definition and not from these display properties.
A graphical browser might render the above example as follows:
Data Binding Restrictions: Binds to any simpleContent (except xsd:base64Binary
, xsd:hexBinary
or any datatype derived from these).
Implementation Requirements: Must allow entry of a lexical value for the bound datatype. Implementations should provide a convenient means for entry of datatypes and take into account localization and internationalization issues such as representation of numbers. For example, an input
bound to an instance data node of type xsd:date
might provide a calendar control to enter dates; similarly, an input control bound to of type boolean
might be rendered as a checkbox.
<input ref="order/shipDate"> <label>Ship By</label> <hint>Please specify the ship date for this order.</hint> </input>
A graphical browser might render the above example as follows:
The user can type a date into the text edit box, or press the button to open a calendar:
Description: This form control is used to provide the user with the ability to supply information to the system in a manner that makes it difficult for someone, other than the user, who may be observing the process to discern the value that is being supplied. A common use is for password entry.
Common Attributes: Common, UI Common, Single Node Binding
Special Attributes:
Optional. This form control accepts an input mode hint. E Input Modes.
when true
, this form control will generate additional xforms-value-changed
events. The default value for this attribute is false
.
Example:
<secret ref="/login/password"> <label>Password</label> <hint>The password you enter will not be displayed.</hint> </secret>
A graphical browser might render this form control as follows:
Data Binding Restrictions: Identical to input
.
Implementation Requirements: Implementations, including accessibility aids, must obscure the value being entered into this form control. One possible approach would be to render a "*" or similar character instead of the actual characters entered. Note that this provides only a casual level of security; truly sensitive information will require additional security measures outside the scope of XForms.
Description: This form control enables free-form data entry and is intended for use in entering multiline content, e.g., the body of an email message.
Common Attributes: Common, UI Common, Single Node Binding
Special Attributes:
Optional. This form control accepts an input mode hint. E Input Modes.
when true
, this form control will generate additional xforms-value-changed
events. The default value for this attribute is false
.
Example:
<textarea ref="message/body" class="messageBody"> <label>Message Body</label> <hint>Enter the text of your message here</hint> </textarea>
In the above, the class
attribute can be used by a style sheet to specify the display size of the form control. Note that the constraints on how much text can be input are obtained from the underlying XForms Model definition and not from these display properties.
A graphical browser might render the above example as follows:
Data Binding Restrictions: Binds to xsd:string
or any derived simpleContent.
Implementation Requirements: Must allow entry of a lexical value for the bound datatype, including multiple lines of text.
Description: This form control renders a value from the instance data, but provides no means for entering or changing data. It is used to display values from the instance, and is treated as display:inline
for purposes of layout. Element output
can be used to display the value at a particular location in the instance by using a binding expression; it can also be used to display the result of evaluating an XPath expression by specifying the XPath expression to be evaluated via attribute value
instead of ref
. Note that attributes ref
and value
on element output
are mutually exclusive.
Description: This form control renders content based in part on instance data, but it provides no means for entering or changing data. It is treated as display:inline
for purposes of layout. Element output
can be used to display the value at a particular location in the instance by using a Single-Node Binding; it can also be used to display the result of evaluating an XPath expression by specifying the XPath expression to be evaluated via attribute value
. Note that the Single-Node Binding attributes and value
on element output
are mutually exclusive.
By default, the output
element simply renders the plain text of the value
attribute or the node indicated by the Single-Node Binding. However, if the Single-Node Binding indicates a non-empty data node, and the media type is specified based on the mediatype attribute or mediatype child element, then the content of the data node must be decoded or dereferenced according to its datatype, and the result should be rendered according to the indicated media type if it is possible to do so (e.g. a voice-only device cannot render a digital image).
Note:
When the media type is specified, implementations may handle the output content as presentation-only or as interactive content, and interactive content may be isolated from or capable of accessing the enclosing document that contains the output
. Further implementation experience and user feedback is required. For example, if the output content includes XForms user interface elements, it may be desirable for them to access a default XForms model in the output content or from the enclosing document.
If the Single Node Binding is absent or if it does not indicate a non-empty instance node, then the media type specification is ignored if given. Otherwise, if the Single Node Binding produces a non-empty node, and the media type is specified, then decoding or dereferencing of the instance node prior to rendition is performed by datatype as follows:
If the instance node either is of type or is derived from type xsd:base64Binary
, then the data is base-64 decoded.
If the instance node either is of type or is derived from type xsd:hexBinary
, then the data is hex-binary decoded.
If the instance node either is of type or is derived from type xsd:anyURI
, then the data is treated as a URI and dereferenced.
If the instance node is of any other type, then the data is used without modification.
If the output
rendition is based on the value
attribute, then the rendition is updated if the nodes referenced by the value
expression change or if the content of any of the referenced nodes changes. Otherwise, the rendition of an output
is updated if the node referenced by the Single-Node Binding changes, if the content of the referenced node changes, or if the media type changes. The media type can change by a change to the mediatype
element's referenced node or its content (a host language may also allow DOM mutation of the content of the mediatype
attribute or element). A change to the label associated with the output
causes an update to the rendition of the label (which may affect the layout position of the main output content).
Failure to render the content indicated by the output
element should result in an xforms-output-error,
a non-fatal error that does not halt XForms processing. Failures can occur for many reasons, including
Data to be decoded does not conform to the format of xsd:base64Binary
or xsd:hexBinary
An xforms-link-error dereferencing the URI in a node of or derived from type xsd:anyURI
A data format error (e.g. invalid or unsupported image format)
An unrecognized media type identifier string
The content model for the output
element includes UI Common in order to allow action handlers for the xforms-output-error as well as to allow more comprehensive behavior and information to be provided for the output
, e.g. via the hint
element.
Common Attributes: Common, Single Node Binding (optional)
Special Attributes:
This form control does not use the UI Common attribute group, but nevertheless still contains an optional appearance
attribute, as defined above.
Optional. An XPath expression to be evaluated. The string result of the evaluation is rendered by the form control. If binding attributes are present to select a node, this attribute has no effect. The evaluation context is the same as would be applied to the evaluation of the single node binding. This XPath expression is re-evaluated whenever there is a change in any node to which the expression refers.
Optional attribute used to indicate that data obtained from the Single-Node Binding should be rendered (after decoding, if needed) according to a desired media type indicated by
the attribute value string, such as image/*
for image rendition. If the mediatype element appears as a child of
the output
, then it overrides this attribute. If the media type is not specified by this attribute or by the mediatype
element, then the the default is to present the
indicated data as plain text (with no decoding according to datatype).
Example:
I charged you - <output ref="order/totalPrice"/> - and here is why:
A graphical browser might render an output form control as follows:
<xforms:model> <xforms:instance xmlns=""> <data></data> </xforms:instance> <xforms:bind nodeset="/data" type="xsd:base64Binary"/> </xforms:model>
Given the model
above, the following controls can upload an image to instance data and display it:
<xforms:upload ref="/data" mediatype="image/*"> <xforms:label>Press me to attach a picture</xforms:label> </xforms:upload> <xforms:output ref="/data" mediatype="image/*"> <xforms:hint>This is the image you attached to the form.</xforms:hint> <xforms:message ev:event="xforms-output-error">Error attaching image data.</xforms:message> </xforms:output>
Data Binding Restrictions: Binds to any simpleContent.
Implementation Requirements: Must allow display of a lexical value for the bound datatype. Implementations should provide a convenient means for display of datatypes and take into account localization and internationalization issues such as representation of numbers and dates.
Example:
<bind nodeset="birthdate" type="xsd:date" /> ... <output ref="birthdate"> <label>Lexical: </label> </output> <output ref="birthdate" appearance="full"> <label>Full: </label> </output> <output ref="birthdate" appearance="minimal"> <label>Minimal: </label> </output>
A graphical browser may take into account the appearance
and the localization information from the host language and present the above output form controls as follows:
Lexical: 1998-01-19 Full: 19 janvier 1998 Minimal: 19/01/1998
Description: This form control enables the common feature found on Web sites to upload a file from the local file system, as well as accepting input from various devices including microphones, pens, and digital cameras.
Common Attributes: Common, UI Common, Single Node Binding
Special Attributes:
Optional. Space-separated list of suggested media types, used by the XForms Processor to determine the possible sources of data to upload.
When true
, this form control will generate additional xforms-value-changed
events. The default for this form control is false
.
Example:
<upload ref="mail/attachment" mediatype="image/*"> <label>Select image:</label> <filename ref="@filename" /> <mediatype ref="@mediatype" /> </upload>
A graphical browser might render this form control as follows:
Implementation Requirements:
On activation, if child element filename
is present and a filename is available, upload
places the filename of the data to upload in the instance at the node indicated by the binding attributes on child element filename
.
On activation, if child element mediatype
is present and a mediatype is available, upload
places the mediatype of the data to upload in the instance at the node indicated by the binding attributes on child element mediatype
.
Data Binding Restrictions: This form control can only be bound to datatypes xsd:anyURI
, xsd:base64Binary
or xsd:hexBinary
, or types derived by restriction from these.
Implementation Requirements: For base64Binary or hexBinary data binding:
When bound to an instance data node of type xsd:base64binary
, xsd:hexBinary
, or a type derived by restriction thereof, on activation upload
places the binary content in the content of the node with the indicated encoding.
Implementation Requirements: For anyURI data binding:
When bound to an instance data node of type xsd:anyURI
(or a type derived by restriction thereof), on activation upload
places a URI in the content of the node.
For security reasons, the XForms Processor must not dereference the URI bound to this form control without explicit user permission.
Note:
Implementors note that upload
must associate the binary content, mediatype, and filename with that URI for 11.11 Serialization as multipart/related and 11.12 Serialization as multipart/form-data serialization.
Implementations with a file system should support file upload—selecting a specific file. The types of files presented by default should reflect the mediatype specified by attribute mediatype
, for example defaulting to only audio file types in the file dialog when the mediatype is "audio/*".
Implementation Requirements: For all data bindings:
Implementations with specific pen/digitizer hardware should (and implementations with other pointing devices may) support scribble—allowing in-place creation of pen-based data.
Implementations with specific audio recording capabilities should support record audio—in-place recording of an audio clip.
Implementations with a digital camera, scanner interface or screen capture should support acquire image—in-place upload of images from an attached device.
Implementations with video recording capability should provide a record video option.
Implementations with 3d capabilities should provide a 3d interface option.
Implementations may provide proprietary implementations (for example, a mediatype of text/rtf
could invoke an edit window with a proprietary word processing application)
Implementations are encouraged to support other input devices not mentioned here.
Implementations which cannot support upload for the given mediatype must make this apparent to the user.
See the child elements filename
8.3.1 The filename Element and mediatype
8.3.2 The mediatype Element.
Description: This form control allows selection from a sequential range of values.
Common Attributes: Common, UI Common, Single Node Binding
Special Attributes:
Optional hint for the lexical starting bound for the range—a legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model.
Optional hint for the ending bound for the range—a legal value for the underlying data. If provided, this value is used to further refine the constraints specified by the underlying model.
Optional value to use for incrementing or decrementing the value. Must be of a type capable of expressing the difference between two legal values of the underlying data.
When true
, this form control will generate additional xforms-value-changed
events. The default for this form control is false
.
Example:
<range ref="/stats/balance" start="-2.0" end="2.0" step="0.5"> <label>Balance</label> </range>
A graphical browser might render this as follows:
Data Binding Restrictions: Binds only the following list of datatypes, or datatypes derived by restriction from those in the list: xsd:duration
, xsd:date
, xsd:time
, xsd:dateTime
, xsd:gYearMonth
, xsd:gYear
, xsd:gMonthDay
, xsd:gDay
, xsd:gMonth
, xsd:float
, xsd:decimal
, xsd:double
.
Implementation Requirements: Must allow input of a value corresponding to the bound datatype. Implementations should inform the user of the upper and lower bounds, as well as the step size, if any. If the instance data value is outside the upper or lower bounds, this form control must indicate an out-of-range condition. In graphical environments, this form control may be rendered as a "slider" or "rotary control".
Notice that the attributes of this element encapsulate sufficient metadata that in conjunction with the type information available from the XForms Model proves sufficient to produce meaningful prompts when using modalities such as speech, e.g., when using an accessibility aid. Thus, in the example below, an aural user agent might speak a prompt of the form Please pick a date in the range January 1, 2001 through December 31, 2001.
In the event of overlapping restrictions between the underlying datatype and the start
and end
hints, the most restrictive range should be used.
Example:
<range ref="/order/shipDate" start="2001-01-01" end="2001-12-31"> <label>Ship Date</label> </range>
Description: This form control is similar to the HTML element button
and allows for user-triggered actions. This form control may also be used to construct other custom form controls.
Common Attributes: Common, UI Common, Single Node Binding (optional)
Example:
<trigger> <label>Click here</label> </trigger>
Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute appearance
.
Suggested renditions for the pre-defined values of this attribute are as follows:
"full": visually rendered as a standard button control with border.
"compact": visually rendered as a standard button control without border
"minimal": rendered with no border, a transparent background and underline font effect. This rendition hint is meant to be analogous to the typical visual rendition of an XHTML anchor element.
Data Binding Restrictions: Binds to any node. This form control does not directly interact with form data, but is affected by model item properties of the bound node, thus binding attributes are not required.
Implementation Requirements: The user agent must provide a means to generate an DOMActivate
event on the form control. Graphical implementations might render this form control as a push-button with the label on the button face. Style sheets can be used to style this form control as an image, hyperlink, or other presentation.
Description: This form control initiates a submission .
Common Attributes: Common, UI Common, Single Node Binding (optional)
Special Attributes:
Optional reference to element submission
. If this attribute is given but does not identify a submission
element,
then activating the submit
does not result in the dispatch of an xforms-submit
event. If this attribute is omitted, then the first submission
in document
order from the model
associated with the in-scope evaluation context is used.
Example:
<submit submission="timecard"> <label>Submit Timecard</label> </submit>
Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute appearance
.
Suggested renditions for the pre-defined values of this attribute are the same as for trigger.
Data Binding Restrictions: Binds to any node. This form control does not directly interact with form data, but is affected by model item properties of the bound node, thus binding attributes are not required.
Implementation Requirements:
The default action for event DOMActivate
is to dispatch
event xforms-submit
to the submission
element specified by
attribute submission
(or its default).
Upon activation, this control must become unavailable for further activations until the submit process concludes with either an xforms-submit-done
or xforms-submit-error
event.
Description: This form control allows the user to make multiple selections from a set of choices.
Common Attributes: Common, UI Common, Single Node Binding
Special Attributes:
Optional attribute determining whether free entry is allowed in the list. Default is "closed".
When true
, this form control will generate additional xforms-value-changed
events. The default for this form control is true
.
Example:
<select ref="my:flavors"> <label>Flavors</label> <choices> <item> <label>Vanilla</label> <value>v</value> </item> <item> <label>Strawberry</label> <value>s</value> </item> <item> <label>Chocolate</label> <value>c</value> </item> </choices> </select>
In the above example, more than one flavor can be selected.
A graphical browser might render form control select
as any of the following:
appearance="full" | appearance="compact" | appearance="minimal" |
---|---|---|
Typically, a style sheet would be used to determine the exact appearance of form controls, though a means is provided to suggest an appearance through attribute appearance
.
The value of the attribute consists of one of the following values:
"full": all choices should be rendered at all times.
"compact": a fixed number of choices should be rendered, with scrolling facilities as needed
"minimal": a minimum number of choices should be rendered, with a facility to temporarily render additional choices
Data Binding Restrictions: any simpleContent capable of holding a sequence. The restriction to binding simpleContent exists when the choices are authored as part of the user interface control as shown in this section. Element itemset
for creating dynamic selections described in 9.3.3 The itemset Element allows the available choices to be obtained from an XForms Model, and when using that construct, the data binding restriction to simpleContent is relaxed.
Note:
A limitation of the XML Schema list datatypes is that white space characters in the storage values (the value
element) are always interpreted as separators between individual data values. Therefore, authors should avoid using white space characters within storage values with list simpleContent.
<item> <value>United States of America</value> ... </item>
When selected, this item would introduce not one but four additional selection values: "America", "of", "States", and "United".
Implementation Requirements: The label for each choice must be presented, allowing at any number of selections, possibly none. This form control stores the values corresponding to the selected choices as a space separated list in the location addressed by attribute ref
. The values to be stored are either directly specified as the contents of element value
, or specified indirectly through binding attributes on element value
.
Note that the datatype bound to this form control may include a non-enumerated value space, e.g., xsd:string
, or a union of a enumeration and a non-enumerated datatype (called an open enumeration). In this case, control select
may have attribute selection="open"
. The form control should then allow free data entry, as described in 8.1.2 The input Element. The form control may permit multiple values to be entered through free entry.
For closed selections: If the initial instance value matches the storage value of one or more of the given items, those items are selected. If there is no match, no items are initially selected. If any selected values do not have a choice with a matching storage value, the form control must indicate an out-of-range condition.
For open selections: If the initial instance values match the storage value specified by one or more of the items, the all such matching items are selected. If the initial instance values do not match the storage value specified by one or more of the items, all such non-matching items are included as selected values, as if entered through free entry. Free entry text is handled the same as form control input
8.1.2 The input Element, possibly in multiplicity. When using dynamic selections with complexTypes, open selection has no effect.
Implementation Hints: An accessibility aid might allow the user to browse through the available choices and leverage the grouping of choices in the markup to provide enhanced navigation through long lists of choices.
Description: This form control allows the user to make a single selection from multiple choices.
Common Attributes: Common, UI Common, Single Node Binding
Special Attributes:
Optional attribute determining whether free entry is allowed in the list. Default is "closed".
When true
, this form control will generate additional xforms-value-changed
events. The default for this form control is true
.
Example:
<select1 ref="my:flavor"> <label>Flavor</label> <item> <label>Vanilla</label> <value>v</value> </item> <item> <label>Strawberry</label> <value>s</value> </item> <item> <label>Chocolate</label> <value>c</value> </item> </select1>
In the above example, selecting one of the choices will result in the associated value given by element value
on the selected item being set in the underlying instance data at the location icecream/flavor
.
A graphical browser might render this form control as any of the following:
appearance="full" | appearance="compact" | appearance="minimal" |
---|---|---|
Data Binding Restrictions: Binds to any simpleContent. The restriction to binding simpleContent exists when the choices are authored as part of the user interface control as shown in this section. Element itemset
for creating dynamic selections described in 9.3.3 The itemset Element allows the available choices to be obtained from an XForms Model, and when using that construct, the data binding restriction to simpleContent is relaxed.
Implementation Requirements: The label for each choice must be presented, allowing at all times exactly one selection. This form control stores the value corresponding to the selected choice in the location addressed by attribute ref
. The value to be stored is either directly specified as the contents of element value
, or specified indirectly through binding attributes on element value
.
Note that the datatype bound to this form control may include a non-enumerated value space, e.g., xsd:string
, or a union of a enumeration and a non-enumerated datatype (called an open enumeration). In this case, control select1
may have attribute selection="open"
. The form control should then allow free data entry, as described in 8.1.2 The input Element.
For closed selections: If the initial instance value matches the storage value of one of the given items, that item is selected. If there is no match, the form control must indicate an out-of-range condition..
For open selections: If the initial instance value matches the storage value specified by one of the items, the first such matching item is selected. Otherwise, the selected value is the initial lexical value. Free entry text is handled the same as form control input
8.1.2 The input Element.
User interfaces may choose to render this form control as a pulldown list or group of radio buttons, among other options. The appearance
attribute offers a hint as to which rendering might be most appropriate, although any styling information (such as CSS) should take precedence.
This element is used within selection form controls to group available choices. This provides the same functionality as element optgroup
in HTML.
Common Attributes: Common
This element specifies the storage value and label to represent an item in a list. It is found within elements select1
and select
, or grouped in element choices
.
Common Attributes: Common
This element provides a storage value to be used when an item
is selected.
The storage value is determined by one of three methods, in order of precedence:
the value of a node indicated by a single node binding expression, if specified
the result of evaluating an XPath expression appearing in attribute value
, if specified
the inline content of the value
element (when neither the single node binding nor the value
attribute are expressed).
Common Attributes: Common, Single Node Binding (optional)
Special Attributes:
An XPath expression to be evaluated. The string result of the evaluation is used as the storage value of the
item
when it is selected. If a single node binding is expressed, then this attribute has no effect.
The evaluation context is the same as would be applied to the evaluation of the single node binding.
Data Binding Restriction: All lexical values must be valid according to the datatype bound to the selection control.
The child elements detailed below provide the ability to attach metadata to form controls.
Factoring all human readable messages to a separate resource XML file.
Using URIs into this XML resource bundle within individual label
elements
Finally, an XForms implementation could use content negotiation to obtain the appropriate XML resource bundle, e.g., based on the accept-language
headers from the client, to serve up the user interface with messages localized to the client's locale.
Binding attributes on optional element filename
specify the location in the instance for the parent element upload
, when activated, to place the filename for the chosen binary resource. For security reasons, upload
must not take action due to any existing value of the node.
Common Attributes: Common, Single Node Binding
In the following example, the user is prompted to select an image. When activated, upload
places in mail/attachment
either the binary data of the image or a URI for it, depending on the type declared for the mail/attachment
. The filename, perhaps "me.jpg
", is placed in the attribute node mail/attachment@filename
, and the mediatype, perhaps "image/jpeg
" in the attribute node mail/attachment@mediatype
.
Example:
<upload ref="mail/attachment" mediatype="image/*"> <label>Select an image to attach</label> <filename ref="@filename"/> <mediatype ref="@mediatype"/> </upload>
Binding attributes on optional element mediatype
specify either:
the location in the instance for the parent element upload
, when activated, to place the mediatype of the chosen binary resource, if available.
the location in the instance of the string that indicates the desired media type rendition for the parent output
.
Common Attributes: Common, Single Node Binding
This required element labels the containing form control with a descriptive label. Additionally, the label makes it possible for someone who can't see the form control to obtain a short description while navigating between form controls.
Common Attributes: Common, Single Node Binding (optional)
Special Attributes: None
The label specified can exist in instance data or as inline text. If more than one source of label is specified in this element, the order of precedence is: single node binding attributes, inline text.
An accessibility aid might speak the metadata encapsulated here when the containing form control gets focus.
The optional element help
provides a convenient way to attach help information to a form control.
Common Attributes: Common, Single Node Binding (optional)
Special Attributes: None
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.
An example of this element is at 10.12 The message Element.
The optional element hint
provides a convenient way to attach hint information to a form control.
Common Attributes: Common, Single Node Binding (optional)
Special Attributes: None
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.
An example of this element is at 10.12 The message Element.
The optional element alert
provides a convenient way to attach alert or error information to a form control. Rendering of this element is implementation-defined, and there is no default level
such as modal
or ephemeral
for the displayed message.
Common Attributes: Common, Single Node Binding (optional)
Special Attributes: None
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. See F XForms and Styling for examples to see how this might be presented to the user.
This chapter covers XForms features for combining form controls into user interfaces.
All form controls defined in 8 Form Controls are treated as individual units for purposes of visual layout e.g., in XHTML processing. Aggregation of form controls with markup defined in this chapter provides semantics about the relationship among user interface controls; such knowledge can be useful in delivering a coherent UI to small devices. For example, if the user interface needs to be split up over several screens, controls appearing inside the same aggregation would typically be rendered on the same screen or page. The elements and attributes included in this module are:
Element | Attributes | Minimal Content Model |
---|---|---|
group | Common, UI Common, Single Node Binding (optional) | label?, ((Form Controls)|group|switch|repeat|UI Common)* |
The group
element is used as a container for defining a hierarchy of form controls.
Groups can be nested to create complex hierarchies. A group is considered to
be non-relevant if and only if:
the Single Node Binding is expressed and resolves to empty nodeset,
the Single Node Binding is expressed and resolves to a non-relevant instance node,
the group
is contained by a non-relevant switch
or group
(which includes a non-relevant repeat
item), or
the group
is contained by a non-selected case
element of a switch
.
All content elements (e.g. form controls, groups, switches, repeats and host language content) within a non-relevant group
are handled as non-relevant. When a group
becomes non-relevant, it must receive event xforms-disabled
and then the
XForms action handlers that are listening for events on the non-relevant group
must be disabled. When a non-relevant group
changes to being relevant, the XForms action handlers that listen for events on the group
must become enabled and then the group
must receive the event xforms-enabled
.
Common Attributes: Common, UI Common, Single Node Binding (optional)
Note:
If a group is non-relevant, then the rendering approach used to signify non-relevance is applied to the entire content of the group.
The optional label
element has special significance when it appears as the first element child of group
, representing a label for the entire group.
Example:
<group ref="address"> <label>Shipping Address</label> <input ref="line_1"> <label>Address line 1</label> </input> <input ref="line_2"> <label>Address line 2</label> </input> <input ref="postcode"> <label>Postcode</label> </input> </group>
Setting the input focus on a group results in the focus being set to the first form control in the navigation order within that group.
This section defines a switch construct that allows the creation of user interfaces where the user interface can be varied based on user actions and events. The elements and attributes included in this module are:
Element | Attributes | Minimal Content Model |
---|---|---|
switch | Common, UI Common, Single Node Binding (optional) | case+ |
case | Common, selected (xsd:boolean) | label?, ((Form Controls)|Action|group|switch|repeat)* |
toggle | Common, case (xsd:IDREF) | case? |
This element contains one or more case
elements, any one of which is rendered at a given time.
Note:
This is separate from XForms relevant
processing (see 6.1.4 The relevant Property), which is based on the current state of the XForms Model. As an example, portions of a questionnaire pertaining to the user's automobile may become relevant only if the user has answered in the affirmative to the question 'Do you own a car?'.
The non-relevance of a switch is determined in the same way as it is for group
and similarly applies to the entire content. Also, as with group
,
when a switch
becomes non-relevant, it must receive event xforms-disabled
and then the
XForms action handlers that are listening for events on the non-relevant switch
must be disabled.
As well, when a non-relevant switch
changes to being relevant, the XForms action handlers that listen
for events on the switch
must become enabled and then the switch
must receive the event
xforms-enabled
.
Common Attributes: Common, UI Common, Single Node Binding (optional)
Example:
<switch> <case id="in" selected="true"> <input ref="yourname"> <label>Please tell me your name</label> <toggle ev:event="DOMActivate" case="out"/> </input> </case> <case id="out" selected="false"> <html:p>Hello <output ref="yourname" /> <trigger id="editButton"> <label>Edit</label> <toggle ev:event="DOMActivate" case="in"/> </trigger> </html:p> </case> </switch>
The above results in the portion of the user interface contained in the first case
being displayed initially. This prompts for the user's name; filling in a value and activating the control e.g., by pressing enter
results switches to the alternate case, with a read-only output
rendering. Activating the trigger labeled "Edit" in turn switches back to the original case.
This element encloses markup to be conditionally rendered. The content elements (e.g. form controls,
groups, switches, repeats and host language elements) within a non-selected case
behave as if they were in
a non-relevant group
(see 9.1.1 The group Element). Similarly, content elements in a case
that becomes
selected behave as if they were in a group
that has become relevant.
The attribute selected
determines the initial selected state.
Common Attributes: Common
Special Attributes:
Optional selection status for the case. The default value is "false".
If multiple case
s within a switch
are marked as selected="true"
, the first selected case
remains and all others are deselected. If none are selected, the first becomes selected.
This XForms Action selects one possible case from an exclusive list of alternatives in a switch
.
This action performs the following:
Dispatches an xforms-deselect
event to the currently selected case
in the switch
containing the identified case
.
Adjusts the selected
states (not the attribute values) on the affected cases to reflect the new state of the switch
containing the identified case
.
Dispatches an xform-select
event to the case
just selected.
Common Attributes: Common, Events
Special Attributes:
Optional reference to a case
element. The case to select is specified by
this attribute or by the child element case.
The case
to be selected by the switch
is identified by IDREF either by the attribute case
or by a child case element.
This section defines a child element of toggle
named case
that is an alternative means of providing the identity of a
case element to select with a switch.
Element: case
Common attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
case identity, the result of the expression is processed as if by call to the
XPath string
function.
The case to be selected by the toggle
action is given by the
case
attribute or the case
element.
If both are given, the element takes precedence. Due to the addition of the element, the case
attribute is no longer required,
but either the case
attribute or the case
element must appear.
The case
element can provide the identity of a case with either its string content
or the value
attribute. If both are given, then the value
attribute takes precedence.
<toggle> <case value="concat('case_', ../addressBlockType)"/> </toggle>
Note:
Whether the IDREF is obtained from the case
attribute or element, the IDREF may not uniquely identify
the desired case if the case
element bearing the matching ID resides
in a repeating construct such as element repeat
.
The general method described in 4.7 Resolving ID References in XForms is used to determine the desired run-time case object.
The XForms specification allows the definition of repeating structures such as multiple items within a purchase order. When defining the XForms Model, such higher-level collections are constructed out of basic building blocks; similarly, this section defines user interface construct repeat
that can bind to data structures such as lists and collections. The elements and attributes included in this module are:
Element | Attributes | Minimal Content Model |
---|---|---|
repeat | Common, UI Common, Node Set Binding, startindex (xsd:positiveInteger), number (xsd:nonNegativeInteger) | ((Form Controls)|group|switch|repeat)* |
itemset | Common, Node Set Binding | label, (value|copy), (UI Common)* |
copy | Common, Single Node Binding (optional) | EMPTY |
insert | Common, Events, Node Set Binding, at (XPath Expression), position ("before"|"after") | EMPTY |
delete | Common, Events, Node Set Binding, at (XPath Expression) | EMPTY |
setindex | Common, Events, repeat (xsd:IDREF), index (XPath Expression) | EMPTY |
(various) | [repeat-nodeset, repeat-bind, repeat-model] (Node Set Binding attributes), repeat-startindex (xsd:positiveInteger), repeat-number (xsd:nonNegativeInteger) | N/A |
This element defines a UI mapping over a homogeneous collection selected by Node Set Binding Attributes. This node-set must consist of contiguous child element nodes, with the same local name and namespace name of a common parent node. The behavior of element repeat
with respect to non-homogeneous node-sets is undefined.
For example:
<repeat nodeset="/cart/items/item"> <input ref="." ...> <label>...</label> </input> <html:br/> </repeat>
Common Attributes: Common, UI Common, Node Set Binding
Special Attributes:
Optional 1-based initial value of the repeat index. The default value is 1.
Optional hint to the XForms Processor as to how many elements from the collection to display.
This element operates over a homogeneous collection by binding the encapsulated user interface controls to each element of the collection. if an element of the collection is non-relevant, then the rendering approach used to signify non-relevance is applied to the associated user interface controls. Attributes on this element specify how many members of the collection are presented to the user at any given time. XForms Actions insert
, delete
, and setindex
can be used to operate on the collection—see 10 XForms Actions. Another way to view repeat processing (disregarding special user interface interactions) is to consider "unrolling" the repeat. The above example is similar to the following (given four item
elements in the returned node-set):
<!-- unrolled repeat --> <input ref="/cart/items/item[1]"><label>...</label></input><html:br/> <input ref="/cart/items/item[2]"><label>...</label></input><html:br/> <input ref="/cart/items/item[3]"><label>...</label></input><html:br/> <input ref="/cart/items/item[4]"><label>...</label></input><html:br/>
<model> <instance> <my:lines> <my:line name="a"> <my:price>3.00</my:price> </my:line> <my:line name="b"> <my:price>32.25</my:price> </my:line> <my:line name="c"> <my:price>132.99</my:price> </my:line> </my:lines> </instance> </model> ... <repeat id="lineset" nodeset="/my:lines/my:line"> <input ref="my:price"> <label>Line Item</label> </input> <input ref="@name"> <label>Name</label> </input> </repeat> <trigger> <label>Insert a new item after the current one</label> <action ev:event="DOMActivate"> <insert nodeset="/my:lines/my:line" at="index('lineset')" position="after"/> <setvalue ref="/my:lines/my:line[index('lineset')]/@name"/> <setvalue ref="/my:lines/my:line[index('lineset')]/price">0.00</setvalue> </action> </trigger> <trigger> <label>remove current item</label> <delete ev:event="activate" nodeset="/my:lines/my:line" at="index('lineset')"/> </trigger>
Element repeat
enables the creation of user interfaces for populating repeating structures. When using XForms within host languages like XHTML, it is often necessary to create repeating structures within constructs such as table
. Thus, one might wish to use element repeat
within a table
to create the rows of a table, where each row of the table binds to a distinct member of a homogeneous collection. Since html:table
doesn't (and probably never will) allow xforms:repeat
elements as children, another syntax is needed.
<table> <repeat nodeset="..."> <tr> <td>...</td> ... </tr> </repeat> </table>
More generally, there is a need to integrate repeat behavior into host languages at points where the content model of the host language does not or cannot provide the appropriate extension hooks via modularization. To accommodate this, XForms defines an alternative syntax that is functionally equivalent to the repeat
element, using the following attributes:
repeat-model
repeat-bind
repeat-nodeset
repeat-startindex
repeat-number
The above attributes are equivalent to the repeat
attributes of the same name, but without the prefix repeat-
. A host language can include these attributes in the appropriate places to enable repeating constructs. For example, a version of XHTML might use:
<html:table xforms:repeat-nodeset="..."> <html:tr> <html:td><xforms:output ref="..."/></html:td> </html:tr> </html:table>
Which could be validated against an appropriately configured XHTML Schema that includes the XForms Repeat module. Note that what gets repeated is the child elements of the element with the repeat-
attributes.
Additionally, when using XForms Action setindex
, attribute repeat
of type idref
can point to any element carrying the repeat attributes. Similarly, when using function index
against a repeating structure created via the repeat-
attributes, the id
of that element can be used as the argument to function index
.
This element allows the creation of dynamic selections within controls select
and select1
, where the available choices are determined at run-time. The node-set that holds the available choices is specified via the Node Set Binding. As with repeat
, this nodeset should refer to a homogeneous collection. Child elements label
and value
indirectly specify the label and storage values. Notice that the run-time effect of itemset
is the same as using element choices
with child item
elements to statically author the available choices.
For each node of the Node Set Binding, an associated item
is created. XForms Actions appearing in the content of an itemset
are created within each item
element, and the in-scope evaluation context for these XForms Actions is based on the node for which the item
was generated as described in Section 7.4 Evaluation Context. An XForms processor must not allow XForms Actions contained by an itemset
to handle events on the itemset
.
Common Attributes: Common, Node Set Binding
Note:
Whenever a refresh
event is dispatched the nodeset
is re-evaluated to update the list of available choices.
The following example shows element itemset
within control select
to specify a dynamic list of ice cream flavors:
<model id="cone"> <instance> <my:icecream> <my:order/> </my:icecream> </instance> </model> <model id="flavors"> <instance> <my:flavors> <my:flavor type="v"> <my:description>Vanilla</my:description> </my:flavor> <my:flavor type="s"> <my:description>Strawberry</my:description> </my:flavor> <my:flavor type="c"> <my:description>Chocolate</my:description> </my:flavor> </my:flavors> </instance> </model> <!-- user interaction markup --> <select model="cone" ref="my:order"> <label>Flavors</label> <itemset model="flavors" nodeset="/my:flavors/my:flavor"> <label ref="my:description"/> <copy ref="my:description"/> </itemset> </select> <!-- For all three items selected, this example produces instance data like <my:icecream> <my:order> <my:description>Vanilla</my:description> <my:description>Strawberry</my:description> <my:description>Chocolate</my:description> </my:order> </my:icecream> -->
Structurally, this element is similar to 8.2.3 The value Element. It differs in that it can only be used within itemset
, and that it works with subtrees of instance data rather than simple values.
Common Attributes: Common, Single Node Binding (optional)
When an item
becomes selected, the following rules apply:
The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an exception results (4.5.1 The xforms-binding-exception Event).
The element node associated with the item
, selected by the binding attributes on copy
, is deep copied as a child of the target node.
A full computational dependency rebuild is done.
When an item
becomes unselected, the following rules apply:
The target node, selected by the binding attributes on the list form control, must be an element node, otherwise an exception results (4.5.1 The xforms-binding-exception Event).
The child element node associated with the item
, selected by the binding attributes on copy
, is deleted.
A full computational dependency rebuild.
insert
Action
The insert
action is used to create one or more nodes of instance data by cloning one or more existing
instance nodes. Attributes of the insert
action specify the node or nodes to be cloned and the
location within instance data where the clones will appear. The clones are deep copies of the original nodes
except the contents of nodes of type xsd:ID
are modified to remain as unique values in the
instance data after the clones are inserted.
Common Attributes: Common, Events, Node Set Binding (optional)
Special Attributes:
Optional attribute containing an XPath expression evaluated using the in-scope evaluation context.
If the model
attribute is present, then it is processed as described in 7.4 Evaluation Context before evaluating this attribute. The Node Set Binding is required unless this
attribute is present. This attribute is ignored if the bind
attribute is present.
Otherwise, the result of the XPath expression is used to override the in-scope evaluation context.
If the result is an empty nodeset or not a nodeset, then the insert action is terminated with no
effect. Otherwise, the first node of the nodeset is used as the new in-scope evaluation context
node, and the context position and size are set to 1. By adjusting the in-scope evaluation context,
this attribute affects the evaluation of subsequent attributes that may appear on insert
,
including if
, while
, nodeset
and origin
.
Optional attribute containing an XPath expression evaluated using the in-scope evaluation context.
The origin node-set
is the set of one or more nodes to be cloned by the
insert
action. If this attribute is present and resolves to a non-empty nodeset, then the
result overrides the default setting of the origin node-set
as described below in the
processing of the insert
action.
Optional attribute containing an XPath expression evaluated using the in-scope evaluation context.
This attribute is ignored if the Node Set Binding is not specified or specifies an empty node-set.
The insert location node
is a node within the Node Set Binding node-set that is used
to help determine where in the instance to insert each node cloned by the insert
. If this
attribute is present, then its result is used to override the default setting of the insert
location node
as described below in the processing of the insert
action.
Optional selector that indicates where to put the cloned node or nodes relative to the insert
location node
. Valid values are before
and after
, and the latter
is the default. This attribute is ignored if the Node Set Binding node-set is not specified or
empty. If the node at the insert location node
within the Node Set Binding node-set is
the document element of an instance, then this attribute is ignored.
Processing for the insert
action is as follows:
The insert context
is determined. If the bind
attribute is present or if the
context
attribute is not given, the insert context
is the in-scope evaluation
context. Otherwise, the XPath expression provided by the context
attribute is evaluated
using the in-scope evaluation context, and the first node rule is applied to obtain the insert
context
. The insert
action is terminated with no effect if the insert
context
is the empty node-set, or if the insert context
is not an element.
The Node Set Binding node-set is determined. If a bind
attribute is present, it directly
determines the Node Set Binding node-set. If a nodeset
attribute is present, it is evaluated
within the insert context
to determine the Node Set Binding node-set. If the Node Set
Binding attributes are not present, then the Node Set Binding node-set is the empty node-set. The
insert
action is terminated with no effect if any of the following conditions is true:
The context
attribute is not given and the Node Set Binding node-set is the empty
node-set.
The context
attribute is given, the insert context
does not evaluate
to an element node and the Node Set Binding node-set is the empty node-set.
The origin node-set
is determined. If the origin
attribute is not given and the
Node Set Binding node-set is empty, then the origin node-set
is the empty node-set.
Otherwise, if the origin
attribute is not given, then the origin node-set
consists of the last node of the Node Set Binding node-set. If the origin
attribute is
given, the origin node-set
is the result of the evaluation of the origin
attribute in the insert context
. The insert
action is terminated with no effect
if the origin node-set
is the empty node-set.
The insert location node
is determined. If the Node Set Binding node-set is not specified
or empty, the insert location node
is the insert context
node. Otherwise, if
the at
attribute is not given, then the insert location node
is the last node
of the Node Set Binding node-set. Otherwise, an insert location node
is determined from the
at
attribute as follows:
The evaluation context node is the first node in document order from the Node Set Binding
node-set, the context size is the size of the Node Set Binding node-set, and the context
position is 1
.
The return value is processed according to the rules of the XPath function
round()
. For example, the literal 1.5
becomes 2
, and
the literal 'string'
becomes NaN
.
If the result is in the range 1 to the Node Set Binding node-set size, then the insert
location
is equal to the result. If the result is non-positive, then the insert
location
is 1
. Otherwise, the result is NaN
or exceeds the
Node Set Binding node-set size, so the insert location
is the Node Set Binding
node-set size.
The insert location node
is the node in the Node Set Binding node-set at the
position given by the insert location
.
Each node in the origin node-set
is cloned in the order it appears in the origin
node-set
.
The target location
of each cloned node or nodes is determined as follows:
If the Node Set Binding node-set is not specified or empty, the target location
depends on the node type of the cloned node. If the cloned node is an attribute, then the
target location
is before the first attribute of the insert location
node
. If the
cloned node is not an attribute, then the target location
is before the first
child of the insert location node
.
Otherwise, if the Node Set Binding node-set is specified and not empty and the type of the
cloned node is different from the type of the insert location node
, the
target location
depends on the node type of the cloned node. If the cloned node is
an attribute, then the target location
is before the first attribute of the
insert location node
node. If the cloned node is not an attribute, then the target
location
is before the first child of the insert location node
.
Otherwise, if insert location node
is the root element of an instance, then that
instance root element location is the target location
. If there is more than one
cloned node to insert, only the first node that does not cause a conflict is considered.
Otherwise, the target location
is immediately before or after the insert
location node
, based on the position
attribute setting or its default.
The cloned node or nodes are inserted in the order they were cloned at their target
location
depending on their node type. If the target location
was the root element
of an instance, then the cloned node replaces the instance root element. If the cloned node is a
duplicate of another attribute in its parent element, then the duplicate attribute is first removed. If
a cloned node cannot be placed at the target location
due to a node type conflict, then
the insertion for that particular clone node is ignored.
The index for any repeat
that is bound to a homogeneous collection where the cloned node was
added is updated to point to the newly inserted node, and the index of any repeat
nested
within an updated repeat
is re-initialized to the startindex
of the nested
repeat
. If the startindex
is less than 1 the index is set to 1. If the
startindex
is greater than the size of the homogeneous collection, then the index is set to
the size of the homogeneous collection.
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
The insert
action is successfully completed by dispatching the xforms-insert
event with appropriate context information.
... <xforms:instance id="people"> <people xmlns=""/> </xforms:instance> <xforms:instance id="personProto"> <person xmlns=""> <name>Jane Q. Public</name> </person> </xforms:instance> ... <xforms:trigger> <xforms:label>Append new person</xforms:label> <xforms:insert context="instance('people')" nodeset="person" origin="instance('personProto')" ev:event="DOMActivate"/> </xforms:trigger> <xforms:trigger> <xforms:label>Prepend new person</xforms:label> <xforms:insert context="instance('people')" nodeset="person" origin="instance('personProto')" at="1" position="before" ev:event="DOMActivate"/> </xforms:trigger> ...
Note:
Generalized append/prepend child can be done with nodeset="*"
for elements and
nodeset="@*"
for attributes.
... <xforms:instance id="people"> <people xmlns=""> <person> <name>Jane Q. Public</name> </person> <person> <name>John Hancock</name> </person> </people> </xforms:instance> ... <xforms:instance id="peopleProto"> <people xmlns=""/> </xforms:instance> ... <trigger> <label>Clear Person List</label> <insert context="instance('people')" nodeset="." origin="instance('peopleProto')" ev:event="DOMActivate"/> </trigger> ...
<insert nodeset="some/node"/>
<xforms:instance xmlns=""> <data> <item show="true">...</item> <item>...</item> <item willbesecondattr="true" show="false">...</item> <item willbesecondattr="false" show="false">...</item> </data> </xforms:instance> ... <insert nodeset="item[2]" origin="item[1]/@show"/> <insert nodeset="item[3]" origin="item[1]/@show"/> <insert nodeset="item[4]/@show" origin="item[1]/@show"/> ...
After the insert
actions, all item
elements have attribute show="true"
,
and it will be the first attribute except for the last item
. The existing show
attribute
is removed from the third and fourth item
, but in the third item
the location of the new
attribute is at the beginning due to node type mismatch, and in the fourth item
the location of
the new attribute after (due to position default) the existing show
attribute.
repeat
, whether or not it is emptyWhen the repeat
is empty, the at
index is zero so a new item
is prepended.
When the repeat
is non-empty, the new item
is added after the node currently indexed
by repeat R
.
... <xforms:instance xmlns=""> <purchaseOrder> <subtotal/> <tax/> <total/> </purchaseOrder> </xforms:instance> <xforms:instance xmlns="" id="prototypes"> <prototypes> ... <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>
... <xforms:instance xmlns="" id="destination"> <items/> </xforms:instance> <xforms:instance xmlns="" id="source"> <items> <item> <product/> <quantity/> <unitcost/> <price/> </item> <item> <product/> <quantity/> <unitcost/> <price/> </item> </items> </xforms:instance> ... <xforms:trigger> <xforms:label>Copy items</xforms:label> <xforms:insert ev:event="DOMActivate context="instance('destination')" origin="instance('source')/item"/> </xforms:trigger>
delete
ActionThis action deletes one or more nodes from instance data.
Common Attributes: Common, Events, Node Set Binding
Special Attributes:
Optional attribute containing an XPath expression evaluated using the in-scope evaluation context.
If the model
attribute is present, then it is processed as described in 7.4 Evaluation Context before evaluating this attribute. This attribute is ignored if the
bind
attribute is present. Otherwise, the result of the XPath expression is used to
override the in-scope evaluation context. If the result is an empty nodeset or not a nodeset, then
the delete
action is terminated with no effect. Otherwise, the first node of the
nodeset is used as the new in-scope evaluation context node, and the context position and size are
set to 1. By adjusting the in-scope evaluation context, this attribute affects the evaluation of
subsequent attributes that may appear on delete
, including if
,
while
, and nodeset
.
Optional attribute containing an XPath expression evaluated using the Node Set Binding node-set to
determine the delete location
. If the Node Set Binding node-set is empty, then this
attribute is ignored.
Processing for the delete
action is as follows:
The delete context
is determined. It is set to the in-scope evaluation context, possibly
overridden by the context
attribute if that attribute is present. The delete
action is terminated with no effect if the delete context
is the empty node-set.
The Node Set Binding node-set is determined. If a bind
attribute is present, it directly
determines the Node Set Binding node-set. If a nodeset
attribute is present, it is evaluated
within the delete context
to determine the Node Set Binding node-set. The
delete
action is terminated with no effect if Node Set Binding node-set is the empty node-set.
The delete location
is determined. If the at
attribute is not specified, there
is no delete location
. Otherwise, the delete location
is determined by
evaluating the XPath expression specified by the at
attribute as follows:
The evaluation context node is the first node in document order from the Node Set Binding
node-set, the context size is the size of the Node Set Binding node-set, and the context
position is 1
.
The return value is processed according to the rules of the XPath function
round()
. For example, the literal 1.5
becomes 2
, and the
literal 'string'
becomes NaN
.
If the result is in the range 1 to the Node Set Binding node-set size, then the delete
location
is equal to the result. If the result is non-positive, then the delete
location
is 1
. Otherwise, if the result is NaN
or exceeds the
Node Set Binding node-set size, the delete location
is the Node Set Binding
node-set size.
If there is no delete location
, each node in the Node Set Binding node-set is deleted,
except if the node is the root document element of an instance then that particular node is not
deleted. Otherwise, if there is a delete location
, the node at the delete
location
in the Node Set Binding node-set is deleted, except if the node is the root document
element of an instance then that node is not deleted. The delete action is terminated with no effect if
no node is deleted.
The index for any repeat
that is bound to a homogeneous collection that contained one of the
deleted nodes is adjusted as follows:
If, prior to node deletion, the index pointed to a node that is still contained in the collection after node deletion, the index is adjusted, if necessary, to point to that same node. If the index is changed, the indexes of inner repeats are reinitialized.
Otherwise, when the last remaining node in the collection is removed, the index position becomes 0 and the indexes of inner repeats become 0 as well.
Otherwise, when the index was pointing to one of the deleted nodes, and if the new size of the collection is smaller than the index, the index is changed to the new size of the collection and the indexes of inner repeats are reinitialized.
Otherwise, when the index was pointing to one of the deleted nodes, and if the new size of the collection is equal to or greater than the index, the index is not changed but the indexes of inner repeats are reinitialized.
To re-initialize a repeat index means to change its value to be equal to startindex
, or to
the size of the homogeneous collection if it contains less than startindex
items.
The XForms action system's deferred update flags for rebuild, recalculate, revalidate and refresh are set.
The delete
action is successfully completed by dispatching the xforms-delete
event with appropriate context information.
repeat
In this example, the trigger
is not in the repeat
. When it is activated, the indexed item
in the repeat is first deleted.
Next, if that was the last item
, then a new prototypical item
is inserted so that the repeat
does not become empty.
The focus is then sent back to the repeat
from the trigger
.
... <xforms:trigger> <xforms:label>Delete from purchase order</xforms:label> <xforms:action ev:event="DOMActivate"> <xforms:delete context="/purchaseOrder" nodeset="item" at="index('R')"/> <xforms:insert context="/purchaseOrder" if="not(item)" nodeset="item" origin="instance('prototypes')/item"/> <xforms:setfocus control="R"/> </xforms:action> </xforms:trigger>
Note:
The form author could have written nodeset="/purchaseOrder/item"
in
the delete
action, but the context
attribute was added for consistency
with the insert
action.
In this example, when the trigger
is activated, all the item
elements under the
shopping-cart
instance are deleted.
... <xforms:trigger> <xforms:label>Empty shopping cart</xforms:label> <xforms:delete ev:event="DOMActivate" context="instance('shopping-cart')" nodeset="item""/> </xforms:trigger>
This action marks a specific item as current in a repeating sequence (within 9.3.1 The repeat Element).
Common Attributes: Common, Events
Special Attributes:
Required reference to a repeating element.
Required XPath expression that evaluates to a 1-based offset into the sequence. The evaluation context is determined in the same manner as the evaluation context for a Single-Node Binding (see 7.4 Evaluation Context).
If the selected index is 0 or less, an xforms-scroll-first
event is dispatched and the index is set to 1. If the selected index is greater than the index of the last repeat item, an xforms-scroll-last
event is dispatched and the index is set to that of the last item. if the index evaluates to NaN the action has no effect. The indexes for inner nested repeat collections are re-initialized to startindex
. The implementation data structures for tracking computational dependencies are rebuilt or updated as a result of this action.
Note:
The IDREF from the repeat
attribute may not uniquely identify the desired repeat
if the repeat
element bearing the matching ID resides within the content of another repeat
.
The general method described in 4.7 Resolving ID References in XForms is used to determine the desired run-time repeat object.
The markup contained within the body of element repeat
specifies the user interface to be generated for each member of the underlying collection. During user interface initialization (see 4.2.2 The xforms-model-construct-done Event), the following steps are performed for repeat
:
The Node Set Binding is evaluated to locate the homogeneous collection to be operated on by this repeat
.
The index for this repeating structure is initialized to the value of startindex
. if the initial startindex
is less than 1 it defaults to 1. If the index is greater than the initial node-set then it defaults to the size of the node-set.
User interface as specified by the repeat
is generated for the requisite number of members of the collection as specified by attributes on element repeat
.
The processing model for repeating structures uses an index that points to the current item in the instance data. This repeat index is accessed via XForms function index
7.8.5 The index() Function and manipulated via XForms Action setindex
9.3.7 The setindex Element. This index is used as a reference point for insert
and delete
operations. Notice that the contained XForms form controls inside element repeat
do not explicitly specify the index of the collection entry being populated. This is intentional; it keeps both authoring as well as the processing model simple.
The binding expression attached to the repeating sequence returns a node-set of the collection being populated, not an individual node. Within the body of element repeat
, binding expressions are evaluated with a context node of the node determined by the index. Repeat processing uses XPath expressions to address the collection over which element repeat
operates.
The form controls appearing inside repeat
need to be suitable for populating individual items of the collection. A simple but powerful consequence of the above is that if the XForms Model specifies nested collections, then a corresponding user interface can nest repeat
elements.
It is possible to nest repeat elements to create more powerful user interface for editing structured data. G.2 Editing Hierarchical Bookmarks Using XForms is an example of a form using nested repeats to edit hierarchical data consisting of bookmarks within multiple sections. Consider the following insert
statement that appears as part of that example.
<xforms:insert nodeset="/bookmarks/section[index('repeatSections')]/bookmark" at="index('repeatBookmarks')" position="after"/>
The above insert
statement is used in that example to add new bookmark entries into the currently selected section. The inner (nested) repeat operates on bookmarks in this selected section; The index—as returned by XForms function index
—for this inner repeat starts at 1
. Hence, after a new empty section of bookmarks is created and becomes current, the first insert bookmark operation adds the newly created bookmark at the front of the list.
Element repeat
enables the binding of user interaction to a homogeneous collection. The number of displayed items might be less than the total number available in the collection. In this case, the presentation would render only a portion of the repeating items at a given time. For example, a graphical user interface might present a scrolling table. The current item indicated by the repeat index should be made available to the user at all times, for example, not allowed to scroll out of view. The XForms Actions enumerated at 10 XForms Actions may be used within event listeners to manipulate the homogeneous collection being populated by scrolling, inserting, and deleting entries.
Notice that the markup encapsulated by element repeat
acts as the template for the user interface that is presented to the user. As a consequence, statically authored IDREF
attributes must be interpreted based on a combination of repeat indexes and where the IDREF attributes appear relative to the element bearing the matching ID. Based on the IDREF resolution rules given in 4.7 Resolving ID References in XForms, it is possible to toggle the case
of a switch
even when it is within one or more repeat
elements. Similarly, it is possible to set the focus to controls and dispatch events to elements that are within one or more repeat
elements.
If the focus is transferred to a control within a repeat
by any means, such as by an XForms action or by user interaction, the index of the repeat
is changed to indicate the item of the homogeneous collection that contains the control. This effect is recursive; the index of each containing repeat
is adjusted appropriately.
This chapter defines 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 common behaviors 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, if (XPath Expression), while (XPath Expression) | (Action)+ |
dispatch | Common, Events, name (xsd:NMTOKEN), target (xsd:IDREF), delay (xsd:nonNegativeInteger), bubbles (xsd:boolean), cancelable (xsd:boolean), if (XPath Expression), while (XPath Expression) | name?, target?, delay? |
rebuild | Common, Events, model (xsd:IDREF), if (XPath Expression), while (XPath Expression) | EMPTY |
recalculate | Common, Events, model (xsd:IDREF), if (XPath Expression), while (XPath Expression) | EMPTY |
revalidate | Common, Events, model (xsd:IDREF), if (XPath Expression), while (XPath Expression) | EMPTY |
refresh | Common, Events, model (xsd:IDREF), if (XPath Expression), while (XPath Expression) | EMPTY |
setfocus | Common, Events, control (xsd:IDREF), if (XPath Expression), while (XPath Expression) | control? |
load | Common, Events, Single Node Binding (optional), resource (xsd:anyURI), show ("new" | "replace"), if (XPath Expression), while (XPath Expression) | resource? |
setvalue | Common, Events, Single Node Binding, value (XPath Expression), if (XPath Expression), while (XPath Expression) | PCDATA |
send | Common, Events, submission (xsd:IDREF), if (XPath Expression), while (XPath Expression) | EMPTY |
reset | Common, Events, model (xsd:IDREF), if (XPath Expression), while (XPath Expression) | EMPTY |
message | Common, Events, Single Node Binding (optional), level ("ephemeral" | "modeless" | "modal"), if (XPath Expression), while (XPath Expression) | (PCDATA|UI Inline)* |
prompt | Common, Events, if (XPath Expression), while (XPath Expression) | label, trigger+ |
See also: 9.2.3 The toggle Element; 9.3.5 The insert Action; 9.3.6 The delete Action; and 9.3.7 The setindex Element.
This module also defines the content set "Action", which includes the following elements (of these, toggle
comes from the XForms Switch module, and insert
, delete
, and setindex
come from the XForms Repeat module):
(action|dispatch|rebuild|refresh|recalculate|revalidate|setfocus|
load|prompt|setvalue|send|reset|message|toggle|insert|delete|setindex)*
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:
<xforms:trigger> <xforms:label>Reset</xforms:label> <xforms:reset ev:event="DOMActivate" model="thismodel"/> </xforms:trigger>
This example recreates the behavior of the HTML reset 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].
An outermost action handler is an action that is activated when the XForms processor is not executing any other action handlers.
An inner action handler is an action that is activated when the XForms processor is executing the declared actions of an outermost 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 the outermost 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 the outermost action handler, as described here. Each XForms model can be thought of as having a set of deferred update Boolean flags, initially false
at the start of an outermost action handler, to indicate whether each of the actions rebuild
, recalculate
, revalidate
, and refresh
are required for that model upon termination of the outermost 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 in 10.14 Conditional Execution of XForms Actions and 10.15 Iteration of XForms Actions.
Execution of an outermost action handler begins by setting the XForms processor into the state of executing an outermost action handler. The outermost action handler is then performed, which may include the execution of inner action handlers. Finally, the XForms processor is set into the state of not executing an outermost action handler and then the deferred update is performed for each model. The deferred update behavior for a model consists of examining each deferred update Boolean flag in the order of rebuild
, recalculate
, revalidate
, and refresh
, and for each true
flag, set the flag to false
and then dispatch the proper event to the model for that deferred update flag (i.e. dispatch xforms-rebuild
for a true rebuild
flag, xforms-recalculate
for a true recalculate
flag, xforms-revalidate
for a true revalidate
flag, and xforms-refresh
for a true refresh
flag).
Note:
The XForms processor is not considered to be executing an outermost action handler at the time that it performs deferred update behavior for XForms models. Therefore, event handlers for events dispatched to the user interface during the deferred refresh behavior are considered to be new outermost action handler.
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
XForms Actions that change the tree structure of instance data result in setting all four deferred update flags to true
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 for recalculate
, revalidate
, and refresh
to true
and making no change to the deferred update flag for rebuild
for the model over which they operate. The XForms Actions in this category are:
setvalue
Finally, the reset
action clears all of the deferred update flags for a model. Similarly, if the default processing of xforms-submit
replaces instance data in a model, then the deferred update flags for that model are cleared immediately before the behaviors are peformed for xforms-rebuild
, xforms-recalculate
, xforms-revalidate
, and xforms-refresh
.
This action causes its child actions to be invoked in the order that they are specified in the document.
Common Attributes: Common, Events
<trigger> <label>Click me</label> <action ev:event="DOMActivate"> <reset model="thismodel"/> <setvalue ref="."/> </action> </trigger>
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 the bubbles
and cancelable
attributes are ignored and the standard semantics as defined in 4 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
Special Attributes:
Optional name of the event to dispatch. The event name is specified by this attribute or by the child element name.
Optional reference to the event target. The event target is specified by this attribute or by the child element target.
Optional attribute that indicates the minimum number of milliseconds to delay dispatching of the event to the target.
The default is 0
(zero). The event delay is specified by this attribute or by the child element
delay.
Optional boolean indicating if this event bubbles—as defined in [DOM2 Events]. The default value is true
for a custom event. For predefined events, this attribute has no effect.
Optional boolean indicating if this event is cancelable—as defined in [DOM2 Events]. The default value is true
for a custom event. For predefined events, this attribute has no effect.
This section defines a new child element of dispatch
that provide an alternative means of specifying the
name of the event to dispatch.
Element: name
Common attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
event name, the result of the expression is processed as if by call to the XPath string
function.
The event name of the dispatch
action is given by the name
attribute or the name
element.
If both are given, the element takes precedence. Due to the addition of the element, the name
attribute is no longer required,
but either the name
attribute or the name
element must appear.
The name
element can provide the event name with either its string content or the value
attribute.
If both are given, then the value
attribute takes precedence.
This section defines a new child element of dispatch
that provide an alternative means of specifying the
target of the event to be dispatched.
Element: target
Common attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
event target, the result of the expression is processed as if by call to the XPath string
function.
The event target of the dispatch
action is given by the target
attribute or the target
element.
If both are given, the element takes precedence. Due to the addition of the element, the target
attribute is no longer required,
but either the target
attribute or the target
element must appear.
The target
element can provide an IDREF for the event target with either its string content or the value
attribute.
If both are given, then the value
attribute takes precedence.
Note:
Whether the IDREF is obtained from the target
attribute or 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 element repeat
.
The general method described in 4.7 Resolving ID References in XForms is used to determine the desired target object.
This section defines a new child element of dispatch
that provides an alternative means of specifying the
delay imposed on the event to be dispatched.
Element: delay
Common attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
event delay, the result of the expression is processed as if by call to the XPath string
function. If
the result does not conform lexically to xsd:nonNegativeInteger
, then the result of 0
(zero) is used.
The event delay of the dispatch
action is given by the delay
attribute or the delay
element.
If both are given, the element takes precedence. The delay
element can provide the delay with either its string content or the value
attribute.
If both are given, then the value
attribute takes precedence.
If the event delay is 0
(zero), then the specified event is dispatched as the result of the dispatch
action.
Otherwise, the event delay is greater than 0
(zero), and the specified event is added to the delayed event queue
unless an event with the same name and target element already exists on the delayed event queue. The dispatch
action has no effect if the event delay is greater than zero 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 one event with the same name and target IDREF. It is the name and the target run-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 a repeat
with an instance data node that is destroyed.
As soon as possible after the specified delay in milliseconds has elapsed, the event is removed from the delayed event queue and then dispatched. In the same manner used to handle user-generated events or the completion of an asynchronous submission, the dispatch and processing of delayed events is done without interrupting the processing of another event and its event handlers.
Note:
Because the delayed event is first removed from the delayed event queue and then dispatched, a handler for a given
event may dispatch the event again with a delay. This can be used to perform simple polling operations. Moreover, the
if attribute can be applied to the dispatch
action to decide when to
discontinue the polling based on a setting in instance data.
This action causes the processing of xforms-rebuild
to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-rebuild
event). This action results in the XForms Processor rebuilding any internal data structures used to track computational dependencies among instance data nodes —see 4.3.7 The xforms-rebuild Event.
Common Attributes: Common, Events
Special Attributes:
Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the
model
associated with the in-scope evaluation context node.
Note:
This action has special deferred update behavior.
This action causes the processing of xforms-recalculate
to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-recalculate
event). As a result, instance data nodes whose values need to be recalculated are updated as specified in the processing model—see 4.3.6 The xforms-recalculate Event.
Common Attributes: Common, Events
Special Attributes:
Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the
model
associated with the in-scope evaluation context node.
Note:
This action has special deferred update behavior.
This action causes the processing of xforms-revalidate
to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-revalidate
event). This results in the instance data being revalidated as specified by the processing model—see 4.3.5 The xforms-revalidate Event.
Common Attributes: Common, Events
Special Attributes:
Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the
model
associated with the in-scope evaluation context node.
Note:
This action has special deferred update behavior.
This action causes the processing of xforms-refresh
to happen, bypassing the normal event flow (i.e. the behavior occurs without dispatching the xforms-refresh
event). This action results in the XForms user interface being refreshed, and the presentation of user interface controls being updated to reflect the state of the underlying instance data—see 4.3.4 The xforms-refresh Event.
Common Attributes: Common, Events
Special Attributes:
Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the
model
associated with the in-scope evaluation context node.
Note:
This action has special deferred update behavior.
This action initiates reset processing by dispatching an xforms-reset
event to the specified model
. Processing of event xforms-reset
is defined in the processing model—see 4.3.8 The xforms-reset Event.
Common Attributes: Common, Events
Special Attributes:
Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes. If this attribute is omitted, then the default is the
model
associated with the in-scope evaluation context node.
Note:
This action has special deferred update behavior.
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.
Common Attributes: Common, Events, Single Node Binding
Special Attributes:
Optional XPath expression to evaluate, with the result stored in the selected instance data node. The evaluation context for this XPath expression is the result from the Single Node Binding.
The element content of setvalue
specifies the literal value to set; this is an alternative to specifying a computed value via attribute value
. The following two examples contrast these approaches:
<setvalue bind="put-here" value="a/b/c"/>
This causes the string value at a/b/c
in the instance data to be placed on the single node selected by the bind element with id="put-here"
.
<setvalue bind="put-here">literal string</setvalue>
This causes the value "literal string" to be placed on the single node selected by the bind element with id="put-here"
.
If neither a value
attribute nor text content are present, the effect is to set the value of the selected node to the empty string (""). If both are present, the value
attribute is used.
All strings are inserted into the instance data as follows:
Element nodes: If the element has any child text nodes, the first text node is replaced with one corresponding to the new value. If no child text nodes are present, a text node is created, corresponding to the new value, and appended as the first child node.
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.
Namespace, processing instruction, comment, and the XPath root node: behavior is undefined.
Note:
This action has special deferred update behavior.
This action dispatches an xforms-focus
event (4.3.2 The xforms-focus Event) to the element
identified by attribute control
or child element control
.
Note that this event is implicitly invoked to implement XForms accessibility features such as accesskey
.
Common Attributes: Common, Events
Special Attributes:
Optional reference to a form control. The form control is specified by this attribute or by the child element control.
Setting focus to a repeating structure sets the focus to the repeat item represented by the repeat index.
This section defines a child element of setfocus
named control
that is an alternative means of providing the
element that receives the xforms-focus
event.
Element: control
Common attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
desired element identifier, the result of the expression is processed as if by call to the XPath string
function.
The identity of the element to which the setfocus
action dispatches xforms-focus
is is given by
the control
attribute or the control
element.
If both are given, the element takes precedence. Due to the addition of the element, the control
attribute is no longer required,
but either the control
attribute or the control
element must appear.
The control
element can provide the desired element identifier with either its string content or the value
attribute.
If both are given, then the value
attribute takes precedence.
<setfocus> <control value="concat('input_', ../paymentType)"/> </setfocus>
Note:
Whether the IDREF is obtained from the control
attribute or element, the IDREF may not uniquely identify
the desired form control if the element bearing the matching ID resides in a repeating construct such as element repeat
.
The general method described in 4.7 Resolving ID References in XForms is used to determine the desired form control.
This action traverses the specified link. If the link traversal fails, then xforms-link-error is dispatched to
to the model
associated with the in-scope evaluation context node of the load
element.
Common Attributes: Common, Events, Single-Node Binding (optional)
Special Attributes:
Optional. Link to an external resource to load.
Optional link behavior specifier. if this attribute is missing, a default value of "replace" is assumed.
When it appears as the first child element of load
, the resource
element provides the URI of the link,
overriding the resource
attribute. This element allows the URI used by the load
to be dynamically calculated
based on instance data.
Common Attributes: None
Special Attributes:
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 XPath string
function.
The URI to be used by the load
can be specified with either the value
attribute or
the string content of the resource
element. If both are specified, then the value
attribute takes precedence.
If the load
does not have a resource
element as its first child, then the URI is obtained from
the resource
attribute or the Single Node Binding, if given.
The URI specifying the link to traverse may be pointed to by the Single Node Binding attributes, if given, or by the resource
element or resource
attribute. Individually, the Single Node Binding, resource
element and resource
attribute are not required. If none are given, the action has no effect. If the Single Node Binding is present and does not select an instance
data node, then this action has no effect. If the Single Node Binding is given in addition to one of the
resource
attribute or resource
element, then the action has no effect.
The URI obtained in this manner is treated as a link ot an external resource, defined as an [XLink 1.0] link between
th load
element and the remote resource indicated. No XLink actuate
value is defined, since control of actuation is
defined by XML Events. The XLink show
value depends on the show
attribute.
Based on the URI obtained above, the link is traversed. If the link traversal fails, it is treated as an error (4.5.3 The xforms-link-error Event).
Otherwise, processing for the document (or portion of the document) reached by traversing the link is specified by the show
attribute.
The following are the possible values for the show
attribute and the corresponding processing behaviors:
The document is loaded into a new presentation context, e.g., a new window. Form processing in the original window continues.
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.
This action initiates submit processing by dispatching an xforms-submit
event. Processing of event xforms-submit
is defined in the processing model—see 4.3.9 The xforms-submit Event.
Common Attributes: Common, Events
Special Attributes:
Optional reference to a submission
element. If this attribute is given but does not identify a submission
element,
then the send
action has no effect. If this attribute is omitted, then the first submission
in document order from the model
associated with the in-scope
evaluation context is used.
This action encapsulates a message to be displayed to the user.
Common Attributes: Common, Events, Single Node Binding (optional)
Special Attributes:
Optional message level identifier, one of ("ephemeral"|"modeless"|"modal"|QName-but-not-NCName). The default is "modal" if the attribute is not specified. This specification does not define behavior for QName values.
The message specified can exist in instance data or as inline text. If more than one source of message is specified in this element, the order of precedence is: single node binding attributes, inline text.
The user interface for the message
action is considered to be created at the time the action occurs. If the message is obtained from the inline content of the message
action, then the output of any output
controls in the message
content is determined based on the instance data available when the message
action occurs. For example, the following example displays the message Hello, world!
as the form starts up:
<model> <instance xmlns=""> <data> <name>John</name> </data> </instance> <action ev:event="xforms-ready"> <setvalue ref="name">world</setvalue> <message level="modal">Hello, <output ref="name"/>!</message> ...</action> </model>
In this example, the message includes the latest user input even though other form controls not in the message
action are not guaranteed to be updated until the end of the xforms-refresh
event processing:
<input ref="birthday"> <label>Enter birthday:</label> <message ev:event="xforms-invalid"><output ref="."/> isn't a valid birthday</message> </input>
Note:
Due to deferred update behavior, if a message
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 the recalculate
action before the message
action.
A graphical browser might render a modal message as follows:
<model> <message level="modal" ev:event="xforms-ready">This is not a drill!</message> ... </model>
A modeless message is the foundation for displaying a help
message, which a graphical browser might render as follows:
<secret ref="/login/password"> <label>Password</label> <help>Have you forgotten your password? Simply call 1-900-555-1212 and have a major credit card handy.</help> </secret>
An ephemeral message is the foundation for displaying a hint
message, which a graphical browser might render as follows:
<input ref="po/address/street1"> <label>Street</label> <hint>Please enter the number and street name</hint> </input>
prompt
Action ElementThis action provides a prompt and a modal method for the user to respond by activating a trigger
.
If XForms actions are associated with the DOMActivate
of the trigger
activated by
the user, then those actions are performed. When a DOMActivate
event bubbles up to the
prompt
element from any of its child trigger
controls, this action releases the modal prompt
and stops the propagation of the event. More generally, this action stops the propagation in the bubble phase
of any events that reaches the prompt
element.
Common attributes: Common, Events
Special attributes: None
Content: label
, trigger+
<trigger> <label>Submit Personal Business Commitments</label> <prompt ev:event="DOMActivate"> <label>You will not be able to modify your PBC's again unless your manager returns them to you. Are you sure you want to submit?</label> <trigger> <label>Yes</label> <send ev:event="DOMActivate" submission="X"/> </trigger> <trigger> <label>No</label> </trigger> </prompt> </trigger>
Note:
Actions performed in response to activation of a trigger
in a prompt
are subject to
normal deferred update behavior (i.e. rebuild, recalculate, revalidate, refresh do not occur until after the
prompt
, or later if the prompt
is part of an even larger action sequence).
The if
attribute can optionally be added to any XForms action. It contains an [XPath 1.0] expression
that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is
converted to a boolean
as if converted with the boolean()
function defined by the
[XPath 1.0] specification.
If the converted result of the expression evaluates to false
, then the action is not performed. If the
converted result is true
, then the action is performed.
If this attribute is applied to an XForms action
element and the converted result of evaluation is
false
, then all of the actions within the action
element are omitted from the execution
of the XForms action sequence that invoked the action
element. If the result is true
,
then the contained actions are performed according to the normal processing rules such as deferred update behavior
and applicability of conditional and iterative attributes.
The setfocus
action in each input control is executed only if the node bound to the control
is a number of a particular length. The exacting form author could perform further validity tests.
... <input ref="areaCode" id="AreaCodeControl" incremental="true"> <label>Area Code</label> <setfocus ev:event="xforms-value-changed" control="ExchangeControl" if="string-length(.)=3 and . > 0"/> </input> <input ref="exchange" id="ExchangeControl" incremental="true"> <label>Exchange</label> <setfocus ev:event="xforms-value-changed" control="LocalControl" if="string-length(.)=3 and . > 0"/> </input> <input ref="local" id="LocalControl" incremental="true"> <label>Local</label> <setfocus ev:event="xforms-value-changed" control="ExtensionControl" if="string-length(.)=4 and . > 0"/> </input> ...
The trigger that performs a delete conditionally sets the focus to a control outside of the repeat if
the repeat becomes empty due to the deletion. The setfocus
is called first because the
delete
removes the context node.
... <trigger id="InsertControl"> <label>Insert Row</label> <action ev:event="DOMActivate"> <insert context="purchaseOrder/lines" nodeset="line" at="index('PurchaseOrderRepeat')" origin="instance('prototype')"/> <setfocus control="PurchaseOrderRepeat"/> </action> </trigger> <repeat nodeset="purchaseOrder/lines/line" id="PurchaseOrderRepeat"> ... <trigger> <label>Delete Row</label> <action ev:event="DOMActivate"> <setfocus control="InsertControl" if="last()=1"/> <delete nodeset="../line" at="index('PurchaseOrderRepeat')"/> </action> </input> ... </repeat>
The while
attribute can optionally be added to any XForms action. It contains an [XPath 1.0] expression
that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is
converted to a boolean
as if converted with the boolean()
function defined by the
[XPath 1.0] specification.
If the converted result of the expression is true
, then the XForms action is performed and then the
expression is re-evaluated. The XForms action is executed repeatedly until the converted result of the expression
evaluates to false
.
If this attribute is applied to an XForms action
element, then the sequence of XForms actions in its content are
executed repeatedly once for each time the immediately preceding evaluation of the expression yields a result of true
.
When XForms actions are iteratively executed, they are still subject to the normal action processing rules such as deferred update and applicability of conditional and iterative attributes.
An XForms action may be executed zero times due to this attribute. Furthermore, if an action bears this attribute and the
if
attribute, then the expressions of both attributes must evaluate to true
before each iterative
execution of the action.
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=". + /some/nodes[instance('temps')/counter]" if="boolean-from-string(/some/nodes[instance('temps')/counter]/@selected)"/> <setvalue ref="instance('temps')/counter" value=". + 1"/> </action> </action> </trigger>
In addition to the action handlers detailed in this chapter, XForms defines four actions as part of the XForms Switch and Repeat modules: 9.2.3 The toggle Element, 9.3.5 The insert Action, 9.3.6 The delete Action, and 9.3.7 The setindex Element.
XForms is designed to gather instance 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.
The submission
element represents declarative instructions on what to submit, and how.
Common Attributes: Common
Special Attributes:
Optional selector binding expression enabling submission of a portion of the instance data. The selected node, and all descendants, are selected for submission. The default value is "/".
Optional reference to a bind
element. When present, the binding reference on this attribute is used in preference to any binding reference from the ref
attribute.
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.
This attribute may be used in place of the action
attribute, and it may be overridden by a resource
element, which can
dynamically specify the URI based on instance data.
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.
Optional attribute defaulting to "asynchronous" and with legal values of "synchronous" and "asynchronous". This attribute
controls whether or not the processing of the result of a submission is performed as part of the default processing of event
xforms-submit
. An asynchronous submission can complete default processing for this event before the
result of the submission is received, and the result is received asynchronously and processed when it is completely received.
Required attribute specifying the protocol to be used to transmit the serialized instance data. There is no default value.
Optional attribute that overrides the submission protocol verb for the submission.
Optional boolean attribute with default "true" that indicates whether or not the data validation checks of the submission are performed.
Optional boolean attribute with default "true" that indicates whether or not the relevance pruning of the submission is performed.
Optional boolean attribute with default "true" that indicates whether or not the instance data is 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.
Optional attribute specifying the version
of XML to be serialized.
Optional attribute specifying whether the serializer should add extra white space nodes for readability.
Optional attribute specifying the mediatype for XML instance serialization. Authors should ensure that the type specified is compatible with application/xml
.
Optional attribute specifying an encoding for serialization.
Optional attribute specifying whether to omit the XML declaration on the serialized instance data.
Optional attribute specifying whether to include a standalone declaration in the serialized XML.
Optional attribute specifying element names to be serialized with CDATA sections.
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".
Optional attribute specifying the instance to replace when the replace
attribute value is "instance".
When the attribute is absent, then the default is the instance that contains the submission data.
An xforms-binding-exception (4.5.1 The xforms-binding-exception Event) occurs if this attribute does not
indicate an instance in the same model as the submission.
Optional attribute containing a binding expression that indicates the
target node for data replacement. If replace
is "instance", then the target node is replaced by the submission result.
If replace
is "text", then the content of the target node is replaced by the submission result. For other values of
the replace
attribute, this attribute is ignored. By default, the target node is the document element of the
instance indicated by the instance
attribute.
Optional attribute specifying the separator character between name/value pairs in urlencoding. The default value is ';'.
Optional attribute providing control over namespace serialization. If absent, all namespace nodes present in the instance data are considered for serialization. If present, specifies list of namespace prefixes to consider for serialization, in addition to those visibly utilized. As in [Exc-C14N], the special value #default
specifies the default namespace.
The following examples show how various options on element submission
can affect serialization as application/xml
. Given the following XForms fragment:
<xforms:model xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:my="http://ns.example.org/2003"> <xforms:instance> <qname xmlns="">my:sample</qname> </xforms:instance> <xforms:submission method="post" action="..."/> </xforms:model>
Note that the includenamespaceprefixes
attribute is not present, which causes all namespace nodes to be serialized, resulting in the following serialized instance data:
<qname xmlns:xforms="http://www.w3.org/2002/xforms" xmlns:my="http://ns.example.org/2003">my:sample</qname>
In particular, note that the XForms namespace has been serialized. To prevent this example from including the unneeded XForms namespace while maintaining the needed my
prefix, includenamespaceprefixes="my"
must be added to the submission element. When this attribute is present, the author takes responsibility to list all namespace prefixes not visibly utilized by the submitted instance data.
The following attributes correspond (in spelling, processing, and default values) to attributes on the output
element of [XSLT 1.0], with the exception of using xsd:boolean
to replace "yes"|"no"
:
version
indent
encoding
omit-xml-declaration
cdata-section-elements
Note:
The following XSLT attributes have no counterpart in XForms:
doctype-system
doctype-public
Elements defined in the XForms Actions module, when that module is included, are also allowed in the content model of submission
.
Under no circumstances may more than a single concurrent submit process be under way for a particular
XForms submission. From the start of the default action of xforms-submit
, until
immediately before xforms-submit-done
or
xforms-submit-error
) is dispatched, the default action for subsequent
xforms-submit
events is to
dispatch xforms-submit-error
with context information containing an
error-type
of submission-in-progress
.
Otherwise, the default action for this event results in the following steps:
The data model is updated. Specifically, if the deferred update rebuild
flag is set for the model
containing this
submission
, then the rebuild operation is performed without dispatching an event to invoke the operation. Then, if the deferred update
recalculate
flag is set for the model
containing this submission
, then the recalculate operation is performed
without dispatching an event to invoke the operation. Performing the operations clears the flags.
A node from the instance data is selected, based on attributes on the submission
element.
If the attributes of submission
select an empty nodeset, a non-relevant node or a non-element node, then
submission processing is stopped after dispatching event xforms-submit-error
with context information containing an error-type
of no-data
.
Otherwise, the indicated node and all nodes for which it is an ancestor are considered for the remainder
of the submit process. If the attribute relevant
is true
, whether by default or declaration,
then any node which is considered not relevant as defined in
6.1.4 The relevant Property is removed.
If the attribute validate
is true
,whether by default or declaration, then
all selected instance data nodes are checked for validity according to the definition in
4.3.5 The xforms-revalidate Event
(no notification events are marked for dispatching due to this operation).
Any selected instance data node that is required but empty or found to
be invalid stops submission processing after dispatching event
xforms-submit-error
with context information containing an
error-type
of validation-error
.
The submission headers
are determined using the header
element(s) in the submission and
the mediatype
attribute or its default.
The submission verb
is determined using the verb
element, verb
attribute, or the
method
attribute.
The submission URL
is determined using the resource
element,
resource
attribute, or the action
attribute.
If the serialize
attribute is false
, then the submission serialization is the empty string.
Otherwise, the submission serialization is determined as follows. The event xforms-submit-serialize
is dispatched.
If the submission-body
property of the event is changed from the initial value of empty string, then the content
of the submission-body
property string is used as the submission serialization
.
Otherwise, the submission serialization
consists of a serialization of the selected instance data according to the rules stated at
11.9 Submission Options.
The submission is performed based on the headers
, verb
, URL
,
and submission serialization
. The exact rules of submission are based on the protocol scheme and
the method
as defined in 11.9 Submission Options.
If the mode
of the submission
is asynchronous
, then default processing for this event
ends after the above steps, and submission processing is resumed once the response from the submission is returned. If the mode
of the submission
is synchronous
, then the XForms processor suspends user interaction with all form controls
of the document and action processing is blocked within in the default processing for this event until the response from the submission is returned.
The response returned from the submission is applied as follows:
For a success response including a body, when the value of the replace
attribute on element submission
is "all
",
the event xforms-submit-done
is dispatched with appropriate context information,
and submit processing concludes with entire containing document being replaced with the returned body.
For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023]),
when the value of the replace
attribute on element submission
is "instance
", the response is parsed as XML.
if the parse fails, then submission processing concludes
after dispatching xforms-submit-error
with appropriate context information, including an error-type
of parse-error
.
However, if the XML parse succeeds, then instance data replacement is performed according to
the rules specified in 11.18 Replacing Data with the Submission Response. This operation may fail if the target
attribute is specified and does not
produce an element node result. In this case, submission ends after dispatching event xforms-submit-error
with appropriate
context information, including an error-type
of target-error
. Otherwise, the instance data replacement succeeds.
Once the XML instance data has been successfully replaced, the rebuild, recalculate, revalidate and refresh operations are
performed on the model, without dispatching events to invoke those four operations.
This sequence of operations affects the deferred update behavior
by clearing the deferred update flags associated with the operations performed.
Submission processing then concludes after dispatching xforms-submit-done
with appropriate context information.
For a success response including a body of a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023]),
when the value of the replace
attribute on element submission
is "instance
", nothing in the document is replaced and submission
processing concludes after dispatching xforms-submit-error
with appropriate context information, including an error-type
of resource-error
.
For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023])
or a text media type (as defined by a content type of text/*
), when the value of the replace
attribute on element submission
is "text
", the response is encoded as text. Then, the content replacement is performed according to the rules
specified in 11.18 Replacing Data with the Submission Response. If the evaluation of an expressed target
attribute failed, then the submission processing concludes after dispatching xforms-submit-error
with appropriate context information, including an error-type
of target-error
. Otherwise, if
the replaced content contained one or more element nodes, then the rebuild operation is invoked without dispatching an event for the operation.
Then, the recalculate, revalidate and refresh operations are performed on the model, without dispatching events to invoke those operations.
This sequence of operations affects the deferred update behavior by
clearing the deferred update flags associated with the operations performed.
Finally, submission processing then concludes after dispatching xforms-submit-done
with appropriate context information.
For a success response including a body that is both a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023])
and a non-text type (i.e. with a content type not matching text/*
),
when the value of the replace
attribute on element submission
is "text
", nothing in the document is replaced and submission
processing concludes after dispatching xforms-submit-error
with appropriate context information, including an error-type
of resource-error
.
For a success response including a body, when the value of the replace
attribute on element
submission
is "none
", submission
processing concludes after dispatching xforms-submit-done
with appropriate context information.
For a success response not including a body, submission processing concludes after dispatching
xforms-submit-done
with appropriate context information.
Behaviors of other possible values for attribute replace
are not defined in this specification.
For an error response nothing in the document is replaced, and submission processing concludes after dispatching xforms-submit-error
with appropriate context information, including an error-type
of resource-error
.
Dispatched at the beginning of submission
serialization (see 11.2 The xforms-submit Event).
Target: submission
Bubbles: Yes
Cancelable: No
Context Info:
Property | Type | Value |
---|---|---|
submission-body | string (text node) | An initially empty string into which event handlers can write data to use in the submission in lieu of the default instance data serialization. |
Note:
The submission-body
property is a string, but the event()
function encapsulates
the string in a text node so that the string can be modified by the setvalue
action,
which sets a value into a node determined by its Single Node Binding.
Note:
Since the submission-body
is a string, this feature may be used to submit non-XML data.
Default Action: If the event context submission-body
property string is empty, then no operation is performed so that the submission
will use the normal serialization data
(see 11.2 The xforms-submit Event).
Otherwise, if the event context submission-body
property string is non-empty, then the serialization data for the submission
is set to be the content of the submission-body
string.
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, or NaN if the submission did not receive an error 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 of header with no namespace URI and two child elements, name and value , 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.
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, or NaN 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 of header with no namespace URI and two child elements, name and value , 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 with text/ ), then the response body is returned as a
string. Otherwise, an empty string is returned.
|
Default Action: None; notification event only.
In XForms 1.0, the URI for submission is provided by the action
attribute. For consistency, form authors may now alternately
use the attribute resource
of type xsd:anyURI
. If both action
and resource
are present, then the
resource
attribute takes precedence.
When it appears as the first child element of submission
, the resource
element provides the submission URI, overriding
the resource
attribute and the action
attribute. This element allows the URI used
for submission to be dynamically calculated based on instance data. Individually, the resource
element, the
resource
attribute and the action attribute are not required. However, one of the three is mandatory.
Common Attributes: None
Special Attributes:
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 XPath string
function.
The URI to be used by the submission
can be specified with either the value
attribute or
the string content of the resource
element. If both are specified, then the value
attribute takes precedence.
If the submission
does not have a resource
element as its first child, then the submission URI is obtained from
the resource
attribute or the action
attribute.
The submission
element must allow a new optional attribute named verb
of type string.
The default value is determined based on the URI scheme and the method
attribute using the rules in 11.9 Submission Options.
For example, under the http
and https
schemes, the methods post
and urlencoded-post
correspond to the verb POST
. If given, the verb
attribute overrides the default verb used in submission.
The submission
element can optionally a child element named verb
, which must appear immediately after the optional
resource
element. This element provides the submission verb, overriding the setting obtained from the verb
attribute
(or its default).
Common Attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
verb, the result of the expression is processed as if by call to the XPath string
function.
The verb to be used by the submission
can be specified with either the value
attribute or
the string content of the verb
element. If both are specified, then the value
attribute takes precedence.
If the submission
does not have a verb
element, then the submission verb is obtained from
the verb
attribute (or its default).
The header
element can be used to contribute information to the preamble of a submission in a manner appropriate to the protocol.
The submission
element can contain zero or more header
child elements, which must appear immediately
after the optional resource
and verb
elements.
Common Attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. One header is generated for each node selected by this attribute.
Content: name
, value
If the header
element does not contain a nodeset
attribute, then one header is created.
If the header
element contains a nodeset
attribute, then one header is created per selected node.
The name and value of the header are obtained from the required child elements name
(11.8.1 The name Element)
and value
(11.8.2 The value Element).
If the name obtained from the name
element is the empty string, then the header is omitted from the submission preamble.
If a header
element defines the Content-type
header, then this setting overrides a Content-type
set by the mediatype
attribute.
The headers defined by header
elements are appended to the set of other headers which may exist for a submission. In
the case of a multipart submission, the headers are appended to those for the first part of the submission.
When the name
element appears as a child of element header
, it is used to specify the name of a header
to be added to the preamble of a submission. The name
element may be used more than once if the containing header
element specifies a nodeset
attribute.
Common Attributes: None
Special Attributes:
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 XPath string
function.
The header name may be given by the string content of the name
element, or by the result of the value
attribute. If both are given,
the result from the value
attribute takes precedence. If the resulting header name is the empty string, then the header is considered
to be void, and it is not added to the submission preamble.
When the value
element appears as a child of element header
, it is used to specify the value component of a header
to be added to the preamble of a submission. The value
element may be used more than once if the containing header
element specifies a nodeset
attribute.
Common Attributes: None
Special Attributes:
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context.
To obtain the header value, the result of the expression is processed as if by call to the XPath string
function.
The header value may be given by the string content of the value
element, or by the result of the value
attribute. If both are given,
the result from the value
attribute takes precedence.
The XForms Model specifies a submission
element containing the following attributes and child elements
that affect serialization and submission.
This section summarizes the behaviors for the allowable values of these attributes and child elements,
and introduces the following sections that define the behavior for serialization and submission. (See
3.3.3 The submission Element
for additional submission
attributes and subelements that affect serialization.)
attribute action
(xsd:anyURI), attribute resource
or resource
element
attribute method
(xsd:string, enumerated below)
header
elements
the verb
element or attribute
For the URI scheme obtained from the action
attribute, resource
attribute or resource
element,
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]
The method
attribute determines the serialization format, and the URI scheme used in the action
attribute attribute or resource
element
determines the submission protocol, according to the following table:
URI scheme | method | Serialization | Submission |
---|---|---|---|
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 other QNAME with no prefix | N/A | N/A |
(any) | any QNAME with a prefix | implementation-defined | implementation-defined |
Note:
Foreign-namespaced attributes are allowed on element submission
, but no behavior is defined by XForms.
Note:
The verb
element or attribute overrides the default submission verb from the submission column in the submission options table above.
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 the submission
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, attribute includenamespaceprefixes
on element submission
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 the includenamespaceprefixes
attribute. The special value #default
represents the default namespace.
Mediatype: By default, the mediatype of the serialized XML instance is application/xml
, but can be changed to a compatible type using element submission
attribute mediatype
. Authors should ensure that the type specified is compatible with application/xml
.
This format is intended for integration of XForms into environments that involve large amounts of binary data where the inclusion of the data as xsd:base64Binary
or xsd: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 in 11.10 Serialization as application/xml. Binary content from xsd:anyURI
instance nodes populated by the upload
(see 8.1.6 The upload Element) control is serialized in separate parts of the [RFC 2387] multipart/related
message.
This format follows the rules of multipart/related
MIME data streams for in [RFC 2387], with specific requirements of this serialization listed below:
multipart/related
message header requirements:
Must contain a type
parameter of the mediatype of the serialized XML instance.
Must contain a start
parameter referring to the Content-ID first body part (root).
First body part (root) requirements:
Must have Content-Type
parameter of the type specified by the submission
mediatype
attribute.
Content is serialized by the rules at 11.10 Serialization as application/xml.
Subsequent part requirements:
One part for each node with a datatype of xsd:anyURI
populated by upload
with:
A Content-Type
header that represents the type of the attachment if known, otherwise application/octet-stream
.
A Content-Transfer-Encoding
header.
A Content-ID
header whose value matches the URI in the associated instance data node.
The binary content associated with the URI, serialized according to the Content-Transfer-Encoding
heading.
Content-Type: multipart/related; boundary=f93dcbA3; type=application/xml; start="<980119.X53GGT@example.com>" Content-Length: xxx --f93dcbA3 Content-Type: application/xml; charset=UTF-8 Content-ID: <980119.X53GGT@example.com> <?xml version="1.0"?> <uploadDocument> <title>My Proposal</title> <author>E. X. Ample</author> <summary>A proposal for a new project.</summary> <notes image="cid:980119.X17AXM@example.com">(see handwritten region)</notes> <keywords>project proposal funding</keywords> <readonly>false</readonly> <filename>image.png</filename> <content>cid:980119.X25MNC@example.com</content> </uploadDocument> --f93dcbA3 Content-Type: image/png Content-Transfer-Encoding: binary Content-ID: <980119.X25MNC@example.com> ...Binary data here... --f93dcbA3 Content-Type: image/png Content-Transfer-Encoding: binary Content-ID: <980119.X17AXM@example.com> ...Binary data here... --f93dcbA3--
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 the Content-Disposition: form-data
name
and filename
parameters. Since this serialization method is supported for legacy applications only, new applications should use application/xml
or multipart/related
.
This format follows the rules for multipart/form-data
MIME data streams in [RFC 2388], with specific requirements of this serialization listed below:
Each element node is visited in document order.
Each element that has exactly one text node child is selected for inclusion.
Element nodes selected for inclusion are as encoded as Content-Disposition: form-data
MIME parts as defined in [RFC 2387], with the name
parameter being the element local name.
Element nodes of any datatype populated by upload
are serialized as the specified content and additionally have a Content-Disposition
filename
parameter, if available.
The Content-Type
must be text/plain
except for xsd:base64Binary
, xsd:hexBinary
, and derived types, in which case the header represents the media type of the attachment if known, otherwise application/octet-stream
. If a character set is applicable, the Content-Type
may have a charset
parameter.
Example:
Content-Type: multipart/form-data; boundary=AaB03x Content-Length: xxx --AaB03x Content-Disposition: form-data; name="document"; filename="b.txt" Content-Type: text/plain; charset=iso-8859-1 This is a file. It has two lines. --AaB03x Content-Disposition: form-data; name="title" A File --AaB03x Content-Disposition: form-data; name="summary" This is my file file test --AaB03x--
This format represents an extension of the [XHTML 1.0] form content type application/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. Each element that has one text node child is selected for inclusion. Note that attribute information is not preserved.
Element nodes selected for inclusion are encoded as EltName=value
, where =
is a literal character, EltName
represents the element local name, and value
represents the contents of the text node. The separator character {sep} from the separator
attribute on submission
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 of EltName
and value
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
, where HH
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:
GivenName=Ren%C3%A9
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.
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, then a separator character from the attribute separator
is appended.
The serialized form data is appended to the URI.
No message body is sent with the request.
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.
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.
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 the get submission method (see 11.14 The get Submit Method).
The submission
element allows an optional attribute named target
. The attribute value is interpreted as
a binding expression to which the first node rule is applied to obtain a
replacement target node for the submission response. This attribute is ignored unless the value of the
replace
attribute is "instance" or "text".
The default replacement target node is the document element node of the instance identified by the instance
attribute, which
is equal to the default instance of the model if not specified. The evaluation context for this attribute is the in-scope evaluation context
for the submission
element, except the context node is modified to be the document element of the instance identified by the
instance
attribute if it is specified.
This attribute is evaluated only once a successful submission response has been received and if the replace
attribute
value is "instance" or "text". If the evaluation of the target
attribute produces an empty nodeset
or a nodeset in which the first node is not an element node, then submission processing ends after dispatching the event
xforms-submit-error
with an error-type
of target-error
.
If the replace
attribute contains the value "text" and the
submission response conforms to an XML mediatype (as defined by the content type specifiers in [RFC 3023]) or
a text media type (as defined by a content type specifier of text/*
), then the response data is encoded as text and replaces the
content of the replacement target node.
If the replace
attribute contains the value "instance" and the submission response conforms to an XML mediatype
(as defined by the content type specifiers in [RFC 3023]) and the XML parse of the submission response succeeds, then
the XML obtained from the submission response is used to replace the target node. The XML in the response may have comment
and processing instruction nodes before and after the document element. These nodes are discarded if the replacement target node
is not the document element of an instance. Otherwise, those processing instructions and comments replace any processing instructions
and comments that previously appeared outside of the document element of the instance being replaced.
This section describes the integration of XForms submission with [SOAP 1.1] and [SOAP 1.2]
The single-node binding of the submission
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 an xforms-submit
event handler. The form author is responsible for declaring the appropriate model item properties on both instances (e.g. the relevant
declarations).
For a SOAP submission, the mediatype
attribute of the submission
must be set to the MIME type of application/soap+xml
. The form author may append charset
and action
MIME parameters.
Note:
The action
MIME parameter has no effect unless the submission method
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.
The method
attribute of the submission
must be set to get
or post
in order to access the SOAP HTTP binding.
If method="get"
, then the SOAP response message exchange pattern is used. The HTTP headers must contain the Accept parameter with a value conforming to the following properties:
must begin with application/soap+xml
If the submission mediatype
contains a charset
MIME parameter, then it is appended to the application/soap+xml
MIME type
No other MIME parameters from the mediatype
are copied to the application/soap+xml
MIME type
The q
MIME parameter must not be specified in the application/soap+xml
MIME type so that the default quality of 1 is used.
If method="post"
, then the SOAP request-response message exchange pattern is used. For SOAP 1.2, the current submission behavior of using the mediatype
attribute value as the value of the Content-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:
the Content-type
HTTP header is change to text/xml
the charset
MIME parameter is appended if it was specified in the mediatype
if the action
MIME parameter appears in the mediatype
then a SOAPAction HTTP header is added and given a value equal to the content of the action
MIME parameter
Note:
XForms 1.1 does not support the SOAP email binding, so method="post" with a mailto:
scheme results in an xforms-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.
The XForms processor must 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 an xforms-submit-error
event is dispatched.
On successful completion, the results are consumed according to the XForms submission process, culminating in an xforms-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.
All XForms Containing Documents must conform to the following specifications, except as qualified below:
XForms elements are typically inserted into a containing document in multiple places. The root element for each individual fragment of XForms
must be model
, a form control, group
, repeat
, or switch
. Individual XForms fragments
must be schema-valid according to the Schema for XForms (A Schema for XForms), except that
the host language may add elements of its own namespace to the content models of the following elements:
group
, repeat
, case
, label
, help
, hint
, alert
and message
. .
A host language may introduce additional conformance requirements.
XForms generators should generate conforming XForms documents.
The following are base technologies for XForms. An XForms Processor therefore must conform to the following specifications, except as qualified below:
[XML Events] (not all aspects are required)
XForms is a generalized XML processing language. Therefore, the XForms specification is intended for implementation on hardware platforms of all sizes, from tiny hand-held devices to high-powered servers. This section describes two main levels of conformance that are useful in varied scenarios.
This conformance level is distinguished by the processor's property()
function returning a string beginning with "model"
for the conformance-level
property.
An XForms model
can contain or reference XML schemas, XForms instance
elements, XForms bind
elements,
XForms submission
elements, and XForms actions. XForms submission
elements can also contain XForms actions.
An XForms Model Processor is a reduced functionality XForms Processor with required, recommended and optional features described in this section.
An XForms Model Processor must
support all attributes of the model
element. The processor must support the valid attributes
and content of the instance
element, and it should support the notification events xforms-insert
and xforms-delete
. The processor must support all attributes, content and other
aspects of bind
elements, except p3ptype
support is optional.
The processor must fully support [XPath 1.0], including all XForms extension functions
(though the index()
function may return 1
if the processor has no
information about the identified repeat
element). The processor must make available the automatic
schema datatype information defined by XForms. The processor must be able to parse inline and external
declared XML schema and consume their schema datatype information [XML Schema part 2], and the processor
should consume all schema information available where appropriate in the XForms processing model.
An XForms Model Processor may
(and hence may not) support user interface creation and refresh behaviors described for model
processing.
An XForms Model Processor must
support action handlers for the events xforms-model-construct-done
, xforms-ready
, xforms-link-exception
and xforms-version-exception
. The processor may support action handlers for the
xforms-refresh
event, and it should support all other events targetted at model
elements.
The support for attributes and elements of [XML Events] is described below in the description of the support for XForms Actions.
An XForms Model Processor should support
the XForms Submission module. If it does, then all attributes and events must be
supported except as follows. The support for attributes and elements of [XML Events] on action handlers for submission events is described
below in the description of the support for XForms Actions.
All submission methods should be supported, and the following methods must
be supported: get
, post
, put
, delete
, and urlencoded-post
. The
http
submission scheme must be supported. The https
and file
schemes should be supported. Other schemes may be supported
such as mailto
or ftp
.
An XForms Model Processor must support
the following actions: action
, insert
, delete
, setvalue
, reset
, rebuild
, recalculate
, revalidate
,
dispatch
, and close
. The processor should support send
and load
.
The processor may support refresh
, setindex
, setfocus
, toggle
,
prompt
and message
. For every supported action, the processor must support all local attributes defined
for the action, including conditional and iteration attributes.
An XForms Model Processor must support the attribute
ev:event
so that XForms action handlers can appear as children of either the target elements of the events they handle or ancestors of those
elements. The processor should support the attribute ev:target
so action handlers can identify the
events targetted at a particular descendant of the action handler's parent element (e.g. the xforms-insert
or xforms-delete
event on a particular instance
of the model
). The processor may support all other features of
[XML Events].
This conformance level is distinguished by the processor's property()
function returning a string beginning with "full"
for the conformance-level
property.
An XForms Full Processor is an XForms Processor consisting of a conforming XForms Model Processor along with the following additional required, recommended and optional features:
The processor must support user interface creation and refresh behaviors described for
model
processing.
The processor must support all basic form controls (input
, secret
, textarea
,
output
, upload
, range
, trigger
, submit
, select
, and select1
), including all of their attributes
and child elements.
The processor must support the actions refresh
, setfocus
,
prompt
and message
.
The processor should support the XForms Group Module.
If the processor does not support this module and a group
element is encountered during user interface initialization, then the processor
must terminate processing after dispatching xforms-binding-exception.
The processor should support the toggle
action and the
XForms Switch Module. If the processor does not support this module and a switch
element is
encountered during user interface initialization, then the processor must terminate processing after dispatching
xforms-binding-exception.
The processor should support the setindex
action and the
XForms Repeat Module, except that support of the repeat-*
attributes is optional. If the processor does not support this module and a repeat
element is
encountered during user interface initialization, then the processor must terminate processing after dispatching
xforms-binding-exception.
The processor should support all interaction and notification events targetted at basic form controls,
group
, switch
, repeat
, and their descendant elements (e.g. case
and item
).
The processor may support the Extension and MustUnderstand modules.
[Definition: A "binding" connects an instance data node to a form control or to a model item constraint by using a binding expression as a locater.]
[Definition: An [XPath 1.0] expression used in a binding.]
[Definition: An [XPath 1.0] expression used in a binding that declares a model item property.]
[Definition: An [XPath 1.0] expression used in binding a form control to the instance, or to specify the node or node-set for operation by an action.]
[Definition: An [XPath 1.0] expression used by model item properties such as relevant and calculate to include dynamic functionality in XForms.]
[Definition: A specific document, for example an XHTML document, in which one or more <model> elements are found.]
[Definition: From XML Schema [XML Schema part 2]: A 3-tuple, consisting of a) a set of distinct values, called its value space, b) a set of lexical representations, called its lexical space, and c) a set of facets that characterize properties of the value space, individual values or lexical items.]
[Definition: From XML Schema [XML Schema part 2]: A single defining aspect of a value space. Generally speaking, each facet characterizes a value space along independent axes or dimensions.]
[Definition: When a UI Single-Node Binding attribute selects a node-set of size > 1, the first node in the node-set is used.]
[Definition: An XForms user interface control that serves as a point of user interaction.]
[Definition: An XML vocabulary, such as XHTML, into which XForms is embedded.]
[Definition: An internal tree representation of the values and state of all the instance data nodes associated with a particular form.]
[Definition: An [XPath 1.0] node from the instance data.]
[Definition: From XML Schema [XML Schema part 2]: A lexical space is the set of valid literals for a datatype.]
[Definition: An instance data node with associated constraints.]
[Definition: An XForms-specific annotation to an instance data node.]
[Definition: A restriction, applied to form data, based on XML Schema datatypes.]
[Definition: From XML Schema [XML Schema part 2]: A set of values for a given datatype. Each value in the value space of a datatype is denoted by one or more literals in its lexical space.]
[Definition: The non-visible definition of an XML form as specified by XForms. The XForms Model defines the individual model items and constraints and other run-time aspects of XForms.]
[Definition: A software application or program that implements and conforms to the XForms specification.]
The XML Schema for XForms, which has a target namespace http://www.w3.org/2002/xforms
, is located at
http://www.w3.org/MarkUp/Forms/2007/XForms-11-Schema.xsd.
This XML Schema for XML Events is referenced by the XML Schema for XForms, and located at http://www.w3.org/TR/2003/REC-xml-events-20031014/#a_schema_attribs.
P3P privacy policies may be associated with any forms transmitted over HTTP that have URIs associated with them. In the future, mechanisms may be specified for associating P3P policies with content transmitted over other protocols.
P3P allows for policies to be associated with an individual URI or a set of URIs. By associating a separate policy with each URI a site can declare a very precise policy that addresses exactly what data is collected with a particular HTTP request and how that data will be used. However, site management is substantially easier for many sites if they declare a single policy that covers many URIs, or even their entire Web presence.
The P3P specification specifies several methods for referencing a P3P policy reference file, which in turn associates P3P policies with URIs and cookies. XForms can be P3P enabled using any of the methods that are appropriate for the Web site in which they are embedded. Some special considerations regarding forms are addressed in the P3P Specification. [P3P 1.0]
Different P3P policies may be applied to the representation of a form embedded in a containing document to that which is associated with the data submitted via that form. If the form representation is served from a different server than the form is submitted to, it is likely that separate P3P policy reference files and policies will be needed. Typically the form representation causes only clickstream data (as defined in [P3P 1.0] section 5.6.4) to be transferred, while a form submission causes much more data to be transferred.
XForms Processors are free (and encouraged) to skip or optimize any steps in this algorithm, as long as the end result is the same. The XForms recalculation algorithm considers model items and model item properties to be vertices in a directed graph. Edges between the vertices represent computational dependencies between vertices.
Following is the default handling for a recalculate
action. Action recalculate
is defined in 10.4 The recalculate Element.
A master dependency directed graph is created as detailed in D.1 Details on Creating the Master Dependency Directed Graph.
To provide consistent behavior, implementations must reduce the number of vertices to be processed by computing a pertinent dependency subgraph consisting only of vertices and edges that are reachable from nodes that require recomputation. This is detailed in D.2 Details on Creating the Pertinent Dependency Subgraph. Note that on a first recomputation (such as on form load), the pertinent dependency subgraph will be the same as the master dependency directed graph.
A topological sort is performed on the vertices of the pertinent dependency subgraph, resulting in an order of evaluation in which each vertex is evaluated only after those vertices on which it depends and before all vertices which depend on it. The topological sort algorithm is discussed at [Algorithms].
The recalculate
process completes.
The master dependency directed graph can be considered an array with one record for each vertex, each having the following fields:
InstanceNode: a reference to the associated instance data node
type: indicates the aspect of the instance node represented by the vertex (the text content or a model item property such as readOnly or required)
depList: a list of vertices that refer to this vertex
in-degree: the number of vertices on which this vertex depends
visited: a flag used to ensure vertices are not added to a subgraph multiple times
index: an association between vertices in the master dependency directed graph and a subgraph
The depList
for each vertex is assigned to be the referenced XML nodes of a given instance node, which are obtained by parsing the computed expression in the node (e.g., the calculate, relevant, readonly, or required property). Any expression violating any Binding Expression Constraint causes an exception (4.5.4 The xforms-compute-exception Event), terminating the recalculate
process.
The depList
for a vertex v
is assigned to be the vertices other than v
whose computational expressions reference v
(described below). Vertex v
is excluded from its own depList
to allow self-references to occur without causing a circular reference exception.
A computational expression appearing in a calculate
attribute controls the text content (value) of one or more instance nodes. A vertex exists for each instance node to represent the expression in the context of the node. Likewise, computational expressions for model item properties such as readOnly
and required
are applied to one or more instance nodes, and vertices are created to represent such expressions in the context of each applicable node. The computational expression of each vertex must be examined to determine the XML nodes to which it refers. Any expression violating any Binding Expression Constraint causes an exception (4.5.4 The xforms-compute-exception Event), terminating the recalculate
process. A computation expression refers to a vertex v
if a subexpression indicates the InstanceNode for v
and v
represents the instance node text content (its value). In this version of XForms, model item properties such as readOnly
and required
cannot be referenced in an expression.
If all calculations must be performed, which is the case on form load, then the pertinent dependency subgraph is simply a duplicate of the master dependency directed graph. If the recalculation algorithm is invoked with a list of changed instance data nodes since the last recalculation, then the pertinent dependency subgraph is obtained by exploring the paths of edges and vertices in the computational dependency directed graph that are reachable from each vertex in the change list. The method of path exploration can be depth first search, a suitable version of which appears in the pseudo-code below.
This algorithm creates a pertinent dependency subgraph S
from a list of changed instance data nodes L<sub>c</sub>
. Variables such as v
and w
represent vertices in the master dependency directed graph. The same variables ending with S
indicate vertices in the pertinent dependency subgraph S
.
// Use depth-first search to explore master digraph subtrees rooted at // each changed vertex. A 'visited' flag is used to stop exploration // at the boundaries of previously explored subtrees (because subtrees // can overlap in directed graphs). for each vertex r in Lc if r is not visited { Push the pair (NIL, r) onto a stack while the stack is not empty { (v, w) = pop dependency pair from stack if w is not visited { Set the visited flag of w to true Create a vertex wS in S to represent w Set the index of w equal to the array location of wS Set the index of wS equal to the array location of w Set the InstanceNode of wS equal to the InstanceNode of w Set the type of wS equal to the type of w For each dependency node x of w Push the pair (w, x) onto the stack } else Obtain wS from index of w if v is not NIL { Obtain vS from index of v Add dependency node for wS to vS Increment inDegree of wS } } } // Now clear the visited flags set in the loop above for each vertex vS in S { Obtain v from index of vS Assign false to the visited flag of v }
Note that the number of vertices and dependency nodes in the pertinent dependency subgraph is not known beforehand, but a method such as array doubling (see [DDJ-ArrayDoubling]) can be used to ensure that building the subgraph is performed in time linear in the size of S
.
The following steps process vertices, resulting in a recalculated form:
A vertex with inDegree of 0 is selected for evaluation and removed from the pertinent dependency subgraph. In the case where more than one vertex has inDegree zero, no particular ordering is specified. If the pertinent dependency subgraph contains vertices, but none have an inDegree of 0, then the calculation structure of the form has a loop, and an exception (4.5.4 The xforms-compute-exception Event) must be thrown, terminating processing.
If the vertex corresponds to a computed item, computed expressions are evaluated as follows:
calculate
: If the value of the model item changes, the corresponding instance data is updated and the dirty flag is set.
relevant
, readOnly
, required
, constraint
: If any or all of these computed properties change, the new settings are immediately placed into effect for associated form controls.
For each vertex in the depList
of the removed vertex, decrement the inDegree by 1.
If no vertices remain in the pertinent dependency subgraph, then the calculation has successfully completed. Otherwise, repeat this sequence from step 1.
For example, consider six vertices a
, b
, v
, w
, x
, and y
. Let a
and b
represent the text content of instance nodes that will be set by a binding from user input controls. Let v
and w
be vertices representing the calculated value and the validity property of a third instance node c
. These vertices would result from a bind
element B
with calculate
and constraint
attributes and a nodeset
attribute that indicates c
. Suppose that the value of c
is the product of a
and b
and that the value is only valid if it does not exceed 100. Likewise, suppose x
and y
are vertices representing the calculated value and the validity property of a fourth instance node d
. Let the value of d
be the sum of a
and b
, and let d
be valid if the value does not exceed 20. The figure below depicts the dependency digraph for this example.
Vertices a
and b
have edges leading to v
and x
because these vertices represent the calculate expressions of c
and d
, which reference a
and b
to compute their product and sum, respectively. Similarly, v
and x
have directed edges to w
and y
, respectively, because w
and y
represent the constraint
expressions of c
and d
, which reference the values of c
and d
to compare them with boundary values.
If a
and b
are initially equal to 10, and the user changes a
to 11, then it is necessary to first recalculate v
(the value of c
) then recalculate w
(the validity property of the value of c
). Likewise, x
(the value of d
) must be recalculated before recalculating y
(the validity property of the value of d
). In both cases, the validity of the value does not change to false
until after the new product and sum are computed based on the change to a
. However, there are no interdependencies between v
and x
, so the product and sum could be computed in either order.
The pertinent subgraph excludes b
and only vertex a
has in-degree of zero. The vertex a
is processed first. It is not a computed vertex, so no recalculation occurs on a
, but its removal causes v
and x
to have in-degree zero. Vertex v
is processed second. Its value changes to 121, and its removal drops the in-degree of vertex w
to zero. Vertex x
is processed next, changing value to 21. When x
is removed, its neighbor y
drops to in-degree zero. The fourth and fifth iterations of this process recalculate the validity of w
and y
, both of which change to false.
The attribute inputmode
provides a hint to the user agent to select an appropriate input mode for the text input expected in an associated form control. The input mode may be a keyboard configuration, an input method editor (also called front end processor) or any other setting affecting input on the device(s) used.
Using inputmode
, the author can give hints to the agent that make form input easier for the user. Authors should provide inputmode
attributes wherever possible, making sure that the values used cover a wide range of devices.
inputmode
Attribute Value SyntaxThe value of the inputmode
attribute is a white space separated list of tokens. Tokens are either sequences of alphabetic letters or absolute URIs. The later can be distinguished from the former by noting that absolute URIs contain a ':'. Tokens are case-sensitive. All the tokens consisting of alphabetic letters only are defined in this specification, in E.3 List of Tokens (or a successor of this specification).
This specification does not define any URIs for use as tokens, but allows others to define such URIs for extensibility. This may become necessary for devices with input modes that cannot be covered by the tokens provided here. The URI should dereference to a human-readable description of the input mode associated with the use of the URI as a token. This description should describe the input mode indicated by this token, and whether and how this token modifies other tokens or is modified by other tokens.
Upon entering an empty form control with an inputmode
attribute, the user agent should select the input mode indicated by the inputmode
attribute value. User agents should not use the inputmode
attribute to set the input mode when entering a form control with text already present. To set the appropriate input mode when entering a form control that already contains text, user agents should rely on platform-specific conventions.
User agents should make available all the input modes which are supported by the (operating) system/device(s) they run on/have access to, and which are installed for regular use by the user. This is typically only a small subset of the input modes that can be described with the tokens defined here.
Note:
Additional guidelines for user agent implementation are found at [UAAG 1.0].
The following simple algorithm is used to define how user agents match the values of an inputmode
attribute to the input modes they can provide. This algorithm does not have to be implemented directly; user agents just have to behave as if they used it. The algorithm is not designed to produce "obvious" or "desirable" results for every possible combination of tokens, but to produce correct behavior for frequent token combinations and predictable behavior in all cases.
First, each of the input modes available is represented by one or more lists of tokens. An input mode may correspond to more than one list of tokens; as an example, on a system set up for a Greek user, both "greek upperCase" and "user upperCase" would correspond to the same input mode. No two lists will be the same.
Second, the inputmode
attribute is scanned from front to back. For each token t in the inputmode
attribute, if in the remaining list of tokens representing available input modes there is any list of tokens that contains t, then all lists of tokens representing available input modes that do not contain t are removed. If there is no remaining list of tokens that contains t, then t is ignored.
Third, if one or more lists of tokens are left, and they all correspond to the same input mode, then this input mode is chosen. If no list is left (meaning that there was none at the start) or if the remaining lists correspond to more than one input mode, then no input mode is chosen.
Example: Assume the list of lists of tokens representing the available input modes is: {"cyrillic upperCase", "cyrillic lowerCase", "cyrillic", "latin", "user upperCase", "user lowerCase"}, then the following inputmode
values select the following input modes: "cyrillic title" selects "cyrillic", "cyrillic lowerCase" selects "cyrillic lowerCase", "lowerCase cyrillic" selects "cyrillic lowerCase", "latin upperCase" selects "latin", but "upperCase latin" does select "cyrillic upperCase" or "user upperCase" if they correspond to the same input mode, and does not select any input mode if "cyrillic upperCase" and "user upperCase" do not correspond to the same input mode.
Tokens defined in this specification are separated into two categories: Script tokens and modifiers. In inputmode
attributes, script tokens should always be listed before modifiers.
Script tokens provide a general indication the set of characters that is covered by an input mode. In most cases, script tokens correspond directly to [Unicode Scripts]. Some tokens correspond to the block names in Java class java.lang.Character.UnicodeBlock ([Java Unicode Blocks]) or Unicode Block names. However, this neither means that an input mode has to allow input for all the characters in the script or block, nor that an input mode is limited to only characters from that specific script. As an example, a "latin" keyboard doesn't cover all the characters in the Latin script, and includes punctuation which is not assigned to the Latin script. The version of the Unicode Standard that these script names are taken from is 3.2.
Input Mode Token | Comments |
---|---|
arabic | Unicode script name |
armenian | Unicode script name |
bengali | Unicode script name |
bopomofo | Unicode script name |
braille | used to input braille patterns (not to indicate a braille input device) |
buhid | Unicode script name |
canadianAboriginal | Unicode script name |
cherokee | Unicode script name |
cyrillic | Unicode script name |
deseret | Unicode script name |
devanagari | Unicode script name |
ethiopic | Unicode script name |
georgian | Unicode script name |
greek | Unicode script name |
gothic | Unicode script name |
gujarati | Unicode script name |
gurmukhi | Unicode script name |
han | Unicode script name |
hangul | Unicode script name |
hanja | Subset of 'han' used in writing Korean |
hanunoo | Unicode script name |
hebrew | Unicode script name |
hiragana | Unicode script name (may include other Japanese scripts produced by conversion from hiragana) |
ipa | International Phonetic Alphabet |
kanji | Subset of 'han' used in writing Japanese |
kannada | Unicode script name |
katakana | Unicode script name (full-width, not half-width) |
khmer | Unicode script name |
lao | Unicode script name |
latin | Unicode script name |
malayalam | Unicode script name |
math | mathematical symbols and related characters |
mongolian | Unicode script name |
myanmar | Unicode script name |
ogham | Unicode script name |
oldItalic | Unicode script name |
oriya | Unicode script name |
runic | Unicode script name |
simplifiedHanzi | Subset of 'han' used in writing Simplified Chinese |
sinhala | Unicode script name |
syriac | Unicode script name |
tagalog | Unicode script name |
tagbanwa | Unicode script name |
tamil | Unicode script name |
telugu | Unicode script name |
thaana | Unicode script name |
thai | Unicode script name |
tibetan | Unicode script name |
traditionalHanzi | Subset of 'han' used in writing Traditional Chinese |
user | Special value denoting the 'native' input of the user (e.g. to input her name or text in her native language). |
yi | Unicode script name |
Modifier tokens can be added to the scripts they apply in order to more closely specify the kind of characters expected in the form control. Traditional PC keyboards do not need most modifier tokens (indeed, users on such devices would be quite confused if the software decided to change case on its own; CAPS lock for upperCase may be an exception). However, modifier tokens can be very helpful to set input modes for small devices.
Input Mode Token | Comments |
---|---|
lowerCase | lowercase (for bicameral scripts) |
upperCase | uppercase (for bicameral scripts) |
titleCase | title case (for bicameral scripts): words start with an upper case letter |
startUpper | start input with one uppercase letter, then continue with lowercase letters |
digits | digits of a particular script (e.g. inputmode='thai digits') |
symbols | symbols, punctuation (suitable for a particular script) |
predictOn | text prediction switched on (e.g. for running text) |
predictOff | text prediction switched off (e.g. for passwords) |
halfWidth | half-width compatibility forms (e.g. Katakana; deprecated) |
User agents may use information available in an XML Schema pattern facet to set the input mode. Note that a pattern facet is a hard restriction on the lexical value of an instance data node, and can specify different restrictions for different parts of the data item. Attribute inputmode
is a soft hint about the kinds of characters that the user may most probably start to input into the form control. Attribute inputmode
is provided in addition to pattern facets for the following reasons:
The set of allowable characters specified in a pattern may be so wide that it is not possible to deduce a reasonable input mode setting. Nevertheless, there frequently is a kind of characters that will be input by the user with high probability. In such a case, inputmode
allows to set the input mode for the user's convenience.
In some cases, it would be possible to derive the input mode setting from the pattern because the set of characters allowed in the pattern closely corresponds to a set of characters covered by an inputmode
attribute value. However, such a derivation would require a lot of data and calculations on the user agent.
Small devices may leave the checking of patterns to the server, but will easily be able to switch to those input modes that they support. Being able to make data entry for the user easier is of particular importance on small devices.
This is an example of a form for Japanese address input. It is shown in table form; it will be replaced by actual syntax in a later version of this specification.
Caption: | inputmode |
---|---|
Family name | hiragana |
(in kana) | katakana |
Given name | hiragana |
(in kana) | katakana |
Zip code | latin digits |
Address | hiragana |
(in kana) | katakana |
latin lowerCase | |
Telephone | latin digits |
Comments | user predictOn |
This informative section provides a broad outline of new and existing CSS features needed to style XForms content. A future Recommendation from the CSS Working Group will fully develop the specification of these features.
A CSS pseudo-class is used to select elements for styling based on information that lies outside of the document tree or that cannot be expressed using the other selectors.
Name | Defined in: | Relationship to XForms |
---|---|---|
:enabled & :disabled | [CSS3] | Selects any form control bound to a node with the model item property relevant evaluating to true or false (respectively). |
:required & :optional | TBD | Selects any form control bound to a node with the model item property required evaluating to true or false (respectively). |
:valid & :invalid | TBD | Selects any form control bound to a node that is currently valid or invalid (respectively), as defined by XForms. |
:read-only & :read-write | TBD | Selects any form control bound to a node with the model item property readonly evaluating to true or false (respectively). |
:out-of-range & :in-range | TBD | Selects any form control bound to a node that contains a value the form control is not or is capable of rendering, (respectively). |
This list is not exhaustive; other pseudo-classes may be defined.
Pseudo-elements are abstractions about the document tree beyond those specified by the document language. Pseudo-elements do not appear in the DOM; they are used only for purposes of styling.
Name | Defined in: | Relationship to XForms |
---|---|---|
::value | TBD | Represents the "active" area of a form control excluding the label; this corresponds in HTML to input and other form control elements. This pseudo-element is a child of the form control element, and appears immediately after the required label element. |
::repeat-item | TBD | Represents a single item from a repeating sequence. Its position is as a parent to all the elements in a single repeating item. Each ::repeat-item is associated with a particular instance data node, and is affected by the model item properties (e.g. 'relevant ') found there, as the related style properties will cascade to the child elements. |
::repeat-index | TBD | Represents the current item of a repeating sequence. Its position is as a parent of all the elements in the index repeating item (and as a child to the ::repeat-item pseudo-element), thus any style declarations applying to this pseudo-element override those on the parent ::repeat-item . |
This list is not exhaustive; other pseudo-elements may be defined.
The following examples show how basic styling can be accomplished on form controls and repeating structures.
@namespace xforms url(http://www.w3.org/2002/xforms); /* Display a red background on all invalid form controls */ *:invalid { background-color:red; } /* Display a red asterisk after all required form controls */ *:required::after { content: "*"; color:red; } /* Do not render non-relevant form controls */ *:disabled { visibility: hidden; } /* The following declarations cause form controls and their labels to align neatly, as if a two-column table were used */ xforms|group { display: table; } xforms|input { display: table-row; } xforms|input > xforms|label { display: table-cell; } xforms|input::value { border: thin black solid; display: table-cell; } /* Display an alert message when appropriate */ *:valid > xforms|alert { display: none; } *:invalid > xforms|alert { display: inline; } /* Display repeat-items with a dashed border */ *::repeat-item { border: dashed; } /* Display a teal highlight behind the current repeat item */ *::repeat-index { background-color: teal; }
This section presents complete XForms examples. These and additional examples are maintained at http://www.w3.org/MarkUp/Forms/2002/Examples.
Schema file payschema.xsd
:
Initial instance file bookmarks.xml
:
The following example shows one possible way of integrating XForms with [SVG 1.1]. Note that the complete set of rules for integrating XForms and SVG are not fully specified at the time this specification was published. Future versions of the XForms, SVG, or other W3C specifications might define more complete rules for integrating XForms and SVG which might not be compatible with the example below.
Note that the example below does not use SVG's switch
and requiredExtensions
features, which are commonly used in conjunction with foreignObject
.
This section summarizes changes since the 14 March 2006 XForms 1.0 Recommendation.
Applied published errata.
Applied changes described in the prior working draft of XForms 1.1, which described new features and change to existing features of XForms 1.0.
This document was produced with the participation of current XForms Working Group participants:
This document was encoded in the XMLspec DTD (which has documentation available). The XML sources were transformed using xmlspec.xsl style sheet. The XML Schema portion of the Appendix was rendered into HTML with the xmlverbatim XSLT stylesheet (used with permission). The primary tools used for editing were SoftQuad XMetaL and EMACS with psgml and XAE. The XML was validated using XMLLint (part of the GNOME libxml package) and transformed using XSLTProc—part of the GNOME libxsl package). The multi-file HTML version was produced using the Xalan processor. The HTML versions were also produced at times with the Saxon engine. The editors used the W3C CVS repository and the W3C IRC server for collaborative authoring.