XForms 1.0 (Third Edition) code { font-family: monospace; }div.constraint,div.issue,div.note,div.notice { margin-left: 2em; }ol.enumar { list-style-type: decimal; }ol.enumla { list-style-type: lower-alpha; }ol.enumlr { list-style-type: lower-roman; }ol.enumua { list-style-type: upper-alpha; }ol.enumur { list-style-type: upper-roman; }div.exampleInner pre { margin-left: 1em; margin-top: 0em; margin-bottom: 0em}div.exampleOuter {border: 4px double gray; margin: 0em; padding: 0em}div.exampleInner { background-color: #d5dee3; border-top-width: 4px; border-top-style: double; border-top-color: #d3d3d3; border-bottom-width: 4px; border-bottom-style: double; border-bottom-color: #d3d3d3; padding: 4px; margin: 0em }div.exampleWrapper { margin: 4px }div.exampleHeader { font-weight: bold; margin: 4px}.xmlverb-default { color: #333333; background-color: #ffffff; font-family: monospace }.xmlverb-element-name { color: #990000 }.xmlverb-element-nsprefix { color: #666600 }.xmlverb-attr-name { color: #660000 }.xmlverb-attr-content { color: #000099; font-weight: bold }.xmlverb-ns-name { color: #666600 }.xmlverb-ns-uri { color: #330099 }.xmlverb-text { color: #000000; font-weight: bold }.xmlverb-comment { color: #006600; font-style: italic }.xmlverb-pi-name { color: #006600; font-style: italic }.xmlverb-pi-content { color: #006666; font-style: italic } XForms 1.0 (Third Edition) W3C Recommendation 29 October 2007This version: http://www.w3.org/TR/2007/REC-xforms-20071029/ Latest version: http://www.w3.org/TR/xforms/ Previous version: http://www.w3.org/TR/2007/PER-xforms-20070725/ Editor:John M. Boyer, IBMPrevious Editors:John M. Boyer, IBM - XForms 1.0 Second EditionMicah Dubinko, Cardiff Software - XForms 1.0 First EditionLeigh L. Klotz, Jr., Xerox Corporation - XForms 1.0 First EditionDavid Landwehr, Novell - XForms 1.0 Second EditionRoland Merrick, IBM - XForms 1.0 First and Second EditionsT. V. Raman, Google - XForms 1.0 First and Second EditionsPlease refer to the errata for this document, which may include normative corrections.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.Abstract XForms is an XML application that represents the next generation of forms for the Web. By splitting traditional XHTML forms into three parts—XForms model, instance data, and user interface—it separates presentation from content, allows reuse, gives strong typing—reducing the number of round-trips to the server, as well as offering device independence and a reduced need for scripting.XForms is not a free-standing document type, but is intended to be integrated into other markup languages, such as XHTML or SVG.Status of this DocumentThis 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 Recommendation of the W3C. This document supersedes XForms 1.0 Second Edition. This document has been produced by the W3C Forms Working Group as part of the Forms Activity within the W3C Interaction Domain. The authors of this document are the Forms Working Group participants.This document has been reviewed by W3C Members, by software developers, and by other W3C groups and interested parties, and is endorsed by the Director as a W3C Recommendation. It is a stable document and may be used as reference material or cited from another document. W3C's role in making the Recommendation is to draw attention to the specification and to promote its widespread deployment. This enhances the functionality and interoperability of the Web.The W3C Forms Working Group has released a public test suite for XForms 1.0. A list of current known XForms Implementations is also available.Comments on this document are welcome. Please send them to the public mailing list www-forms-editor@w3.org. (archive). It is inappropriate to send discussion email to this address. 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. Table of Contents1 About the XForms 1.0 Specification 1.1 Background 1.2 Reading the Specification 1.3 How the Specification is Organized 1.4 Documentation Conventions2 Introduction to XForms 2.1 An Example 2.2 Providing XML Instance Data 2.3 Constraining Values 2.4 Multiple Forms per Document3 Document Structure 3.1 The XForms Namespace 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 Element4 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.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 and xforms-delete Events 4.4.6 The xforms-valid Event 4.4.7 The xforms-invalid Event 4.4.8 The DOMFocusIn Event 4.4.9 The DOMFocusOut Event 4.4.10 The xforms-readonly Event 4.4.11 The xforms-readwrite Event 4.4.12 The xforms-required Event 4.4.13 The xforms-optional Event 4.4.14 The xforms-enabled Event 4.4.15 The xforms-disabled Event 4.4.16 The xforms-in-range Event 4.4.17 The xforms-out-of-range Event 4.4.18 The xforms-submit-done Event 4.4.19 The xforms-submit-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 Element5 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:yearMonthDuration6 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 Datatype7 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.9 String Functions 7.9.1 The property() 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 seconds-from-dateTime() Function 7.10.4 The seconds() Function 7.10.5 The months() Function 7.11 Node-set Functions 7.11.1 The instance() Function 7.12 Extension Functions8 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 Element9 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.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 Element 9.3.6 The delete Element 9.3.7 The setindex Element 9.3.8 Repeat Processing 9.3.9 Nested Repeats 9.3.10 User Interface Interaction10 XForms Actions 10.1 The XForms Action Module 10.1.1 The action Element 10.1.2 The dispatch Element 10.1.3 The rebuild Element 10.1.4 The recalculate Element 10.1.5 The revalidate Element 10.1.6 The refresh Element 10.1.7 The setfocus Element 10.1.8 The load Element 10.1.9 The setvalue Element 10.1.10 The send Element 10.1.11 The reset Element 10.1.12 The message Element 10.1.13 Actions insert, delete and setindex11 Submit 11.1 The xforms-submit Event 11.2 Submission Options 11.3 Serialization as application/xml 11.4 Serialization as multipart/related 11.5 Serialization as multipart/form-data 11.6 Serialization as application/x-www-form-urlencoded 11.7 The post, multipart-post, form-data-post, and urlencoded-post Submit Methods 11.8 The put Submit Method 11.9 The get Submit Method12 Conformance 12.1 Conformance Levels 12.1.1 XForms Full 12.2 Conformance Description 12.2.1 Conforming XForms Processors 12.2.2 Conforming XForms Documents 12.2.3 Conforming XForms Generators13 Glossary Of TermsAppendicesA Schema for XForms A.1 Schema for XML EventsB References B.1 Normative References B.2 Informative ReferencesC Privacy Considerations C.1 Using P3P with XFormsD 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 ProcessingE 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 ExamplesF XForms and Styling (Non-Normative) F.1 Pseudo-classes F.2 Pseudo-elements F.3 ExamplesG Complete XForms Examples (Non-Normative) G.1 XForms in XHTML G.2 Editing Hierarchical Bookmarks Using XForms G.3 Survey Using XForms and SVGH Changelog (Non-Normative)I Acknowledgments (Non-Normative)J Production Notes (Non-Normative)1 About the XForms 1.0 Specification1.1 BackgroundForms 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 1.0 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. 1.2 Reading the SpecificationThis 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 optional, required, recommended, may, must, and should in accord with [RFC 2119]. 1.3 How the Specification is OrganizedThe specification is organized into the following chapters: Chapters 1 and 2An introduction to XForms. The introduction outlines the design principles and includes a brief tutorial on XForms. Chapters 3 and upXForms 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. AppendixesAppendixes contain a normative description of XForms described in XML Schema, information on references, and other useful information. 1.4 Documentation ConventionsThroughout this document, the following namespace prefixes and corresponding namespace identifiers are used: xforms: The XForms namespace (http://www.w3.org/2002/xforms) 3.1 The XForms Namespacehtml: The XHTML namespace (http://www.w3.org/1999/xhtml) [XHTML 1.0]xsd: The XML Schema namespace (http://www.w3.org/2001/XMLSchema)[XML Schema part 1]xsi: The XML Schema for instances namespace (http://www.w3.org/2001/XMLSchema-instance)[XML Schema part 1]ev: The XML Events namespace (http://www.w3.org/2001/xml-events)[XML Events]my: Any user defined namespaceThis 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 itemExample ItemReferences to external documents appear as follows: [Sample Reference] with links to the references section of this document. Sample ReferenceReference - linked to from above.The following typesetting convention is used for non-normative commentary: Note:A gentle explanation or admonition to readers. 2 Introduction to XForms XForms has been designed on the basis of several years' experience with HTML forms. HTML Forms have formed the backbone of the e-commerce revolution, and having shown their worth, have also indicated numerous ways they could be improved.The primary difference when comparing XForms with HTML Forms, apart from XForms being in XML, is the separation of the data being collected from the markup of the controls collecting the individual values. By doing this, it not only makes XForms more tractable by making it clear what is being submitted where, it also eases reuse of forms, since the underlying essential part of a Form is no longer irretrievably bound to the page it is used in.A second major difference is that XForms, while designed to be integrated into XHTML, is no longer restricted only to be a part of that language, but may be integrated into any suitable markup language.XForms has striven to improve authoring, reuse, internationalization, accessibility, usability, and device independence. Here is a summary of the primary benefits of using XForms:Strong typingSubmitted data is strongly typed and can be checked using off-the-shelf tools. This speeds up form filling since it reduces the need for round trips to the server for validation.XML submissionThis obviates the need for custom server-side logic to marshal the submitted data to the application back-end. The received XML instance document can be directly validated and processed by the application back-end.Existing schema re-useThis obviates duplication, and ensures that updating the validation rules as a result of a change in the underlying business logic does not require re-authoring validation constraints within the XForms application.External schema augmentationThis 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.InternationalizationUsing XML 1.0 for instance data ensures that the submitted data is internationalization ready.Enhanced accessibilityXForms separates content and presentation. User interface controls encapsulate all relevant metadata such as labels, thereby enhancing accessibility of the application when using different modalities. XForms user interface controls are generic and suited for device-independence.Multiple device supportThe high-level nature of the user interface controls, and the consequent intent-based authoring of the user interface makes it possible to re-target the user interaction to different devices.Less use of scriptingBy defining XML-based declarative event handlers that cover common use cases, the majority of XForms documents can be statically analyzed, reducing the need for imperative scripts for event handlers.2.1 An ExampleIn 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 1.0 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.2.2 Providing XML Instance DataThe XForms Processor can directly submit the data collected as XML. In the example, the submitted data would look like this:Submitted Data<ecommerce> <method>cc</method> <number>1235467789012345</number> <expiry>2001-08</expiry></ecommerce>XForms processing keeps track of the state of the partially filled form through 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:Model<xforms:model> <xforms:instance> <payment method="cc" xmlns="http://commerce.example.com/payment"> <number/> <expiry/> </payment> </xforms:instance> <xforms:submission action="http://example.com/submit" method="post" includenamespaceprefixes="#default"/></xforms:model>In this case the submitted data would look like this:Submitted Data<payment method="cc" xmlns="http://commerce.example.com/payment"> <number>1235467789012345</number> <expiry>2001-08</expiry></payment>This design has features worth calling out:There is complete flexibility in the structure of the XML instance data, including the use of attributes. Notice that XML namespaces are used, and that a wrapper element of the author's choosing contains the instance data.Empty 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:Binding Form Controls to Instance Nodes with 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.2.3 Constraining ValuesXForms 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:Declarative Validation with Model Item Properties... xmlns:my="http://commerce.example.com/payment"... <xforms:model> ... <xforms:bind nodeset="/my:payment/my:number" relevant="/my:payment/@method = 'cc'" required="true()" type="my:ccnumber"/> <xforms:bind nodeset="/my:payment/my:expiry" relevant="/my:payment/@method = 'cc'" required="true()" type="xsd:gYearMonth"/> <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:number2.4 Multiple Forms per DocumentXForms 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.Adding a 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:Form Controls for 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.3 Document StructureXForms 1.0 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.3.1 The XForms NamespaceThe XForms namespace has the URI: http://www.w3.org/2002/xforms. XForms Processors must use the XML namespaces mechanism [XML Names] to recognize elements and attributes from this namespace.3.2 XForms Core Attribute Collections3.2.1 Common AttributesThe Common Attribute Collection applies to every element in the XForms namespace.idThe optional id attribute of type xsd:ID assigns an identity to the containing element.anyAttributeForeign attributes are allowed on all XForms elements.3.2.2 Linking AttributesThe Linking Attributes Collection applies to XForms elements which include a link to a remote resource.srcThe src attribute assigns a URI to be automatically retrieved.Note:Since linking attribute URIs are defined in terms of the XML Schema datatype xsd:anyURI, the same internationalization benefits and white space cautions apply as discussed in [XML Schema part 2].Behavior of relative URIs in links is determined by the host language, although [XML Base] processing is strongly recommended.Note:The Forms Working Group is tracking with the HTML Working Group on a method of describing link structures.3.2.3 Single-Node Binding AttributesThe 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.refBinding expression interpreted as XPath. This attribute has no meaning when a bind attribute is present.modelOptional 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.bindReference 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.3.2.4 Node-Set Binding AttributesThe 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.nodesetBinding expression interpreted as XPath. This attribute has no meaning when a bind attribute is present.modelOptional 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.bindReference 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.3.2.5 Model Item Property AttributesThis 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.3.3 The XForms Core ModuleThe 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:ElementAttributesMinimal Content ModelmodelCommon, Events, functions (QNameList), schema (list of xsd:anyURI), version xforms:versionList(instance|xsd:schema| submission|bind|Action)*instanceCommon, Linking(ANY) submission Common, ref (binding-expression), bind (xsd:IDREF), action (xsd:anyURI), method ("post"|"get"|"put"|"form-data-post"|"urlencoded-post"|qname-but-not-ncname), 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"|"none"|QNameButNotNCNAME), instance (xsd:IDREF), separator (';' | '&'), includenamespaceprefixes (xsd:NMTOKENS)Action*bindCommon, 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.3.3.1 The model Element 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, EventsAttributes 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:functionsOptional 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.schemaOptional 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".versionOptional attribute with a default value of empty string and legal values defined by the datatype xforms:versionList. Examples are "1.0" and "1.0 1.1". If one or more versions are indicated by this attribute on the default model, then an XForms Processor must support at least one of the listed language versions of XForms. Otherwise, the XForms Processor must terminate processing after dispatching the event xforms-version-exception to the default model. If the XForms Processor supports more than one language version indicated by the version setting on the default model or if the version setting on the default model is empty string (whether specified or by default), then the XForms Processor may execute the XForms content using any language conformance level available to it. If any non-default model has a version setting that is incompatible with the language version selected by the XForms Processor, or if any model contains an illegal version attribute value, then the XForms Processor must terminate processing after dispatching the event xforms-version-exception to the default model. The version attribute is optional to implement, but future versions of XForms are expected to support it, so implementation support is strongly encouraged.This example shows a simple usage of model, with the XForms namespace defaulted:Model<model id="Person" schema="MySchema.xsd"> <instance src="http://example.com/cgi-bin/get-instance" /> ...</model>3.3.2 The instance ElementThis optional element contains or references initial instance data.Common Attributes: CommonSpecial Attributes:Linking AttributesOptional link to externally defined initial instance data. If the link traversal fails, it is treated as an exception (4.5.2 The xforms-link-exception Event).If both an attribute and inline content are provided, the linked version takes precedence as described at 4.2.1 The xforms-model-construct 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 detached copy of the inline instance data fails due to an XML error, then processing should halt with an xforms-link-exception. This could happen, for example, if the inline content had two element nodes, which would imply creating an XML document with two document elements.Note:In XForms 1.1, a new exception event will be issued.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.3.3.3 The submission ElementThis element represents declarative instructions on what to submit, and how. Details of submit processing are described at 11 Submit.Common Attributes: CommonSpecial Attributes:bindOptional 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.refOptional 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 "/".action 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.methodRequired attribute specifying the protocol to be used to transmit the serialized instance data. There is no default value.versionOptional attribute specifying the version of XML to be serialized.indentOptional attribute specifying whether the serializer should add extra white space nodes for readability.mediatypeOptional attribute specifying the mediatype for XML instance serialization. Authors should ensure that the type specified is compatible with application/xml. encodingOptional attribute specifying an encoding for serialization.omit-xml-declarationOptional attribute specifying whether to omit the XML declaration on the serialized instance data.standaloneOptional attribute specifying whether to include a standalone declaration in the serialized XML.cdata-section-elementsOptional attribute specifying element names to be serialized with CDATA sections.replaceOptional attribute specifying how the information returned after submit should be applied. In the absence of this attribute, "all" is assumed.instanceOptional 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.separatorOptional attribute specifying the separator character between name/value pairs in urlencoding. The default value is ';'.includenamespaceprefixesOptional 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":versionindentencodingomit-xml-declarationcdata-section-elementsNote:The following XSLT attributes have no counterpart in XForms:doctype-systemdoctype-publicElements defined in the XForms Actions module, when that module is included, are also allowed in the content model of submission.3.3.4 The bind ElementElement 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:nodesetAn 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..3.4 The XForms MustUnderstand ModuleCertain 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.ElementAttributesMinimal Content ModelANYxforms:mustUnderstand (xsd:boolean)n/aIt 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.3.5 The XForms Extension ModuleThere 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.ElementAttributesMinimal Content ModelextensionCommon ANY3.5.1 The extension ElementOptional 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: CommonFor 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>4 Processing ModelThis 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:InitializationInteractionNotificationError Conditions4.1 Events OverviewXForms 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 nameCancelable?Bubbles?Target element 4.2 Initialization Eventsxforms-model-constructNoYes model xforms-model-construct-doneNoYes model xforms-readyNoYes model xforms-model-destructNoYes model 4.3 Interaction Eventsxforms-previousYesNoform controlxforms-nextYesNoform controlxforms-focusYesNoform controlxforms-helpYesYesform controlxforms-hintYesYesform controlxforms-rebuildYesYes model xforms-refreshYesYes model xforms-revalidateYesYesmodelxforms-recalculateYesYes model xforms-resetYesYes model xforms-submitYesYes submission 4.4 Notification EventsDOMActivateYesYesform controlxforms-value-changedNoYesform controlxforms-selectNoYesitem or casexforms-deselectNoYesitem or casexforms-scroll-firstNoYes repeat xforms-scroll-lastNoYes repeat xforms-insertNoYesinstancexforms-deleteNoYesinstancexforms-validNoYesform controlxforms-invalidNoYesform controlDOMFocusInNoYesform controlDOMFocusOutNoYesform controlxforms-readonlyNoYesform controlxforms-readwriteNoYesform controlxforms-requiredNoYesform controlxforms-optionalNoYesform controlxforms-enabledNoYesform controlxforms-disabledNoYesform controlxforms-in-rangeNoYesform controlxforms-out-of-rangeNoYesform controlxforms-submit-doneNoYessubmissionxforms-submit-errorNoYessubmission 4.5 Error Indicationsxforms-binding-exceptionNoYesany element that can contain a binding expressionxforms-link-exceptionNoYesmodelxforms-link-errorNoYesmodelxforms-compute-exceptionNoYesmodelxforms-version-exceptionNoYesthe default model4.2 Initialization EventsThis 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.4.2.1 The xforms-model-construct EventDispatched to each XForms model by the XForms processor.Target: modelBubbles: YesCancelable: NoContext Info: NoneThe 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).If an external source for the initial instance data is given, an XPath data model [7 XPath Expressions in XForms] is constructed from it; otherwise if inline initial instance data is given, that is used instead. 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, then default processing of this event ends because 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 initialized. [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.4.2.2 The xforms-model-construct-done EventDispatched after the completion of xforms-model-construct processing.Target: modelBubbles: YesCancelable: NoContext Info: NoneThe 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.4.2.3 The xforms-ready EventDispatched as part of xforms-model-construct-done processing.Target: modelBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: None; notification event only.4.2.4 The xforms-model-destruct EventDispatched 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: modelBubbles: NoCancelable: NoContext Info: NoneThe default action for this event results in the following: None; notification event only.4.3 Interaction Events4.3.1 The xforms-next and xforms-previous EventsDispatched in response to: user request to navigate to the next or previous form control.Target: form controlBubbles: NoCancelable: YesContext Info: NoneThe 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.4.3.2 The xforms-focus EventDispatched in response to: set focus to a form control.Target: form controlBubbles: NoCancelable: YesContext Info: NoneThe 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.4.3.3 The xforms-help and xforms-hint EventsDispatched in response to: a user request for help or hint information.Target: form controlBubbles: YesCancelable: YesContext Info: NoneThe 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.4.3.4 The xforms-refresh EventDispatched in response to: a request to update all form controls associated with a particular XForms Model.Target: modelBubbles: YesCancelable: YesContext Info: NoneThe 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 valueits validitywhether it is required, readonly or relevant.4.3.5 The xforms-revalidate EventDispatched in response to: a request to revalidate a particular XForms Model.Target: modelBubbles: YesCancelable: YesContext Info: NoneAn instance node is valid if and only if the following conditions hold:the constraint model item property is truethe 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 invalid to valid 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. 4.3.6 The xforms-recalculate EventDispatched in response to: a request to recalculate all calculations associated with a particular XForms Model.Target: modelBubbles: YesCancelable: YesContext Info: NoneThe 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.4.3.7 The xforms-rebuild EventDispatched in response to: a request to rebuild the internal data structures that track computational dependencies within a particular XForms Model.Target: modelBubbles: YesCancelable: YesContext Info: NoneThe 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.4.3.8 The xforms-reset EventDispatched in response to: a user request to reset the model.Target: modelBubbles: YesCancelable: YesContext Info: NoneThe 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.4.3.9 The xforms-submit EventSee chapter 11 Submit.4.4 Notification Events4.4.1 The DOMActivate EventDispatched in response to: the "default action request" for a form control, for instance pressing a button or hitting enter.Target: form controlBubbles: YesCancelable: YesContext Info: NoneThe default action for this event results in the following: None; notification event only.4.4.2 The xforms-value-changed EventDispatched in response to: a change to an instance data node bound to a form control.Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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.4.4.3 The xforms-select and xforms-deselect EventsDispatched in response to: an item in a select, select1, or switch becoming selected or deselected.Target: item or caseBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: None; notification event only.4.4.4 The xforms-scroll-first and xforms-scroll-last EventsDispatched in response to: a setindex action attempting to set an index outside the range of a repeat.Target: repeatBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: None; notification event only.4.4.5 The xforms-insert and xforms-delete EventsDispatched in response to: A event handler invoking an XForms Action insert or delete, successfully adding or deleting a repeat item..Target: instanceBubbles: YesCancelable: NoContext Info: Path expression used for insert/delete (xsd:string).The default action for these events results in the following: None; notification event only.4.4.6 The xforms-valid EventDispatched in response to: an instance data node either changing and being or becoming valid.Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.7 The xforms-invalid EventDispatched in response to: an instance data node either changing and being or becoming invalid. Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.8 The DOMFocusIn EventDispatched in response to: a form control receiving focus.Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: None; notification event only.4.4.9 The DOMFocusOut EventDispatched in response to: a form control losing focus.Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: None; notification event only.4.4.10 The xforms-readonly EventDispatched in response to: an instance data node either changing and being or becoming readonly. Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.11 The xforms-readwrite EventDispatched in response to: an instance data node either changing and being or becoming read-write. Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.12 The xforms-required EventDispatched in response to: an instance data node either changing and being or becoming required. Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.13 The xforms-optional EventDispatched in response to: an instance data node either changing and being or becoming optional. Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.14 The xforms-enabled EventDispatched in response to: an instance data node either changing and being or becoming enabled. Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.15 The xforms-disabled EventDispatched in response to: an instance data node either changing and being or becoming disabled. Target: form controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.16 The xforms-in-range EventDispatched 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 controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.17 The xforms-out-of-range EventDispatched 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 controlBubbles: YesCancelable: NoContext Info: NoneThe 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. 4.4.18 The xforms-submit-done EventDispatched in response to: completion of submit processing, including processing any returned document.Target: submissionBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: None; notification event only.4.4.19 The xforms-submit-error EventDispatched as an indication of: a failure of the submit process, as defined at 11 SubmitTarget: submissionBubbles: YesCancelable: NoContext Info: The submit method URI that failed (xsd:anyURI)The default action for this event results in the following: None; notification event only.4.5 Error IndicationsError 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.4.5.1 The xforms-binding-exception EventDispatched 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 expressionBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: Fatal error.4.5.2 The xforms-link-exception EventDispatched as an indication of: a failure in link traversal of a linking attribute.Target: modelBubbles: YesCancelable: NoContext Info: The URI that failed to load (xsd:anyURI)The default action for this event results in the following: Fatal error.4.5.3 The xforms-link-error EventDispatched as an indication of: a failure in link traversal of a linking attribute, in a situation not critical to form processing.Target: modelBubbles: YesCancelable: NoContext Info: The URI that failed to load (xsd:anyURI)The default action for this event results in the following: None; notification event only.4.5.4 The xforms-compute-exception EventDispatched as an indication of: an error occurring during XPath evaluation.Target: modelBubbles: YesCancelable: NoContext Info: Implementation-specific error string.The default action for this event results in the following: Fatal error.4.5.5 The xforms-version-exception EventDispatched as an indication of failure of the version checks defined in the description of the version attribute in Section 3.3.1 The model Element.Target: the default modelBubbles: YesCancelable: NoContext Info: NoneThe default action for this event results in the following: Fatal error.4.6 Event SequencingThe 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].4.6.1 For 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.4.6.2 For output ControlsNo event sequences are defined.4.6.3 For 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.4.6.4 For trigger ControlsActivating the form control causes the event sequence defined at 4.6.8 Sequence: Activating a Trigger.4.6.5 For 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.4.6.6 Sequence: Selection Without Value Changexforms-deselectxforms-select4.6.7 Sequence: Value Changexforms-recalculatexforms-revalidatexforms-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 necessary4.6.8 Sequence: Activating a TriggerDOMActivate4.6.9 Sequence: Submissionxforms-submitxforms-submit-done or xforms-submit-error4.7 Resolving ID References in XFormsThe 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. 4.7.1 References to Elements within a repeat ElementWhen 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.4.7.2 References to Elements within a bind ElementWhen 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.5 DatatypesThis chapter defines the datatypes used in defining an XForms Model.5.1 XML Schema Built-in DatatypesXForms 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:hexBinaryxsd:float xsd:decimal * xsd:double xsd:anyURI * xsd:QNameNote: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:normalizedStringxsd:tokenxsd:languagexsd:Namexsd:NCNamexsd:IDxsd:IDREFxsd:IDREFSxsd:NMTOKENxsd: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 * 5.2 XForms DatatypesThe Schema for XForms derives the following types to facilitate defining model in XForms.5.2.1 xforms:listItemThis 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. 5.2.2 xforms:listItemsXForms 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.5.2.3 xforms:dayTimeDurationXForms 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.5.2.4 xforms:yearMonthDurationXForms 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.6 Model Item PropertiesThis 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.6.1 Model Item Property DefinitionsModel 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:DescriptionComputed Expression (yes or no)Legal ValuesDefault ValueInheritance Rules6.1.1 The type PropertyDescription: 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.Associating datatypes with instance nodes<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.6.1.2 The readonly PropertyDescription: 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.Attaching a readonly property<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.6.1.3 The required PropertyDescription: 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.Attaching a required property<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. 6.1.4 The relevant PropertyDescription: 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.Attaching a relevant property<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.6.1.5 The calculate PropertyDescription: 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.Attaching a calculate property<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.6.1.6 The constraint PropertyDescription: 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. Attaching a constraint property<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.6.1.7 The p3ptype PropertyDescription: 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: noneInheritance 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. Attaching a type constraint using Binding<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.6.2 Schema ConstraintsChapter 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.6.2.1 Atomic DatatypeThe 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.Type Constraint Using XML Schema<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.Attaching A Type Constraint<my:first-name xsi:type="my:nonEmptyString"/>This defines element first-name to be of type my:nonEmptyString. Attaching Type Constraint Using XForms Binding<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.7 XPath Expressions in XForms 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, re | |
