1 Introduction
This document uses the terms must, must not,
required, shall, shall not,
recommended, should, should not,
may, and optional in accord with [RFC 2119].
This document describes XForms for HTML, which provides a set of attributes and script methods encompassing a useful subset of XForms functionality and mapping that functionality to syntactic constructs that are familiar to authors of HTML and XHTML web pages. The intent of this module is to simplify the means by which web page authors gain access to the rich functionality available from the hybrid execution model of XForms, which combines declarative constructs with event-driven imperative processing. These attributes and script methods increase the initial consumability of XForms by allowing injection of rich semantics directly into the host language markup. In turn, the behaviors of the attributes and script methods are mapped to the XForms model-view-controller-connector architecture so that applications manifest behaviors consistent with having used XForms markup elements. This allows authors to gradually address greater application complexity as it arises in the software lifecycle by opportunistically, i.e. as the need arises, switching from the attributes and script methods of this specification to the corresponding XForms markup elements. This gradual adoption strategy is being further supported by the modularization of XForms into components that can be consumed incrementally by authors and implementers.
The XForms for HTML attributes are offered to HTML and XHTML web pages as a set of local attributes. Other consuming host language markup languages may adopt these attributes as global attributes in the XForms namespace (http://www.w3.org/2002/xforms).
Host language processors should be, but are not required to be, namespace aware. For clarity, this specification describes integration with explicitly declared XForms elements by using the prefix xf to indicate the XForms namespace (http://www.w3.org/2002/xforms) being applied to those elements. A host language processor may adopt the XForms elements into its own namespace for ease of authoring.
3 Default Data Instance
This section describes the management of data instances in a form as well as the basic attributes
that can be used to generate or bind to a default data instance based on element structure in the host
language markup.
A form can contain any number of explicitly declared data instances using the
<xf:instance> element.
If a form also contains an explicitly declared <xf:model> element, then any
<xf:instance> elements in the form that are not children of the
<xf:model> element must be ignored by implementations conformant to
this specification. An author who adds <xf:model> element to a form
is advised to place any preexisting <xf:instance> elements within it.
The default data instance of the form is indicated by the instance attribute on
the form element, or its default. If the instance attribute indicates the ID
of an <xf:instance> element, then the indicated <xf:instance>
provides the default data instance of the form. Otherwise, the instance attribute
is absent, empty or does not indicate the ID of an <xf:instance> element.
In these cases an implicit default data instance is generated for the form based on the attributes
defined in this section that appear on elements or tags within the content of the form element.
The implicit default data instance is known as the generated data instance.
The generated data instance is created as the first element child of the form's XForms model.
The process of creating the generated data instance is known as data instance generation.
Regardless of whether the model is generated or declared, the process of data instance generation
occurs before the xforms-model-construct event occurs for the model.
Note:
If a form contains no elements or tags that have a name attribute, then a
generated data instance is not created for the form's XForms model.
If the <xf:model> element is explicitly declared for a form, and it contains no declared
<xf:instance> element and the form does not contain any elements bearing the
name attribute, then a default data instance is constructed for the <xf:model>
according to the method described in the xforms-model-construct-done event.
A default data instance constructed in this manner is defined to be a constructed data instance,
not a generated data instance. Therefore, the initializations described below for the generated data instance
are not applicable to the constructed data instance.
The following attributes are pertinent to the data instance generation process and the creation of
form controls within a form.
| Attributes | Content Model | Description |
|---|
| instance | IDREF or empty | Used on a form element to indicate the default data instance, which is the data
instance to which form controls bind with the name attribute. If the instance attribute
indicates the ID of an <xf:instance> in the form, then that <xf:instance> is used
as the default data instance of the form. Otherwise, the default data instance for the form is the
generated data instance. |
| name | xsd:QName | The element bearing the attribute is a form control bound to the data node or nodes
that match the attribute value. |
| value | xsd:string | When used in combination with name (in other words, when used on a form control),
this attribute helps to provides an initial value when generating a node in the generated data instance. |
| type | xsd:string | This attribute is used on a form control to help determine how the value attribute
contributes to the initialization of the generated data instance. This specification defines data
initialization behavior only for case-insensitive value matches to the string "radio" and
"checkbox". |
| checked | true (also TRUE, checked or CHECKED), or false (also FALSE) | This attribute is used on a form control to help determine whether the value attribute
contributes to the initialization of the generated data instance. In HTML, if the attribute value is not specified,
then the existence of the attribute is construed as a true result, and its absence is construed as a false result. |
| startsize | xsd:nonNegativeInteger | This attribute indicates that the form control bearing this a repeat form control. The content of the form
control is to be treated as a template. The template and the named data node are to be repeated any number of times
during document execution. During default data instance generation, the number given by the attribute value determines
the number of data nodes to initially generate and the number of copies of the template content to generate. |
| number | xsd:nonNegativeInteger | This attribute indicates how many copies of the template of a repeat form control
should be presented to the user at any given time. The user interface processor should provide
a scrolling mechanism to allow the user to change the set of template copies being presented. |
An element or tag that bears the name attribute is called a form control.
A form control that also bears a startsize attribute is called a repeat form control.
Content within a repeat form control is treated as a template which can be generated multiple times
corresponding to a number of data nodes matched by the name attribute value of the
repeat form control. The template elements that bear a name attribute are not form controls,
but the elements generated from the template in response to repeated data nodes are form controls if
they bear the name attribute, and they are known as generated form controls.
A form control that contains a form control or is a repeat form control is known as a
container form control. The child form control list of a container form control
is an ordered list of form controls for which the container form control is the nearest ancestor form control.
The position of a form control in a child form control list is based on document order for non-generated
form controls, and on document order of the template form control combined with generation order for
generated form controls. The focus order of all form controls in a form is based on depth
depth-first pre-order visitation of form controls and the order sequence of child form control lists of
the container form controls.
If a form element does not bear the name attribute, then the default for
the name on the form element is data. The default for name
only applies on a form element, and this default has two effects.
First, it provides a name for the root element of the generated data instance.
Second, whether or not the form element explicitly declares the name attribute,
the form element is a container form control for all form controls within its content.
See 3.1 The name Attribute for further details on how the data instance is
generated in response to the name and startsize attributes.
Note:
The name attribute can be used on the form element to assign a namespace qualified
name to the root element of the generated data instance.
Given the following markup:
<form xmlns:my="http://example.org" name="my:form" ... >
...
</form>
The following generated instance is produced:
<xf:instance>
<my:form xmlns="" xmlns:my="http://example.org">
...
</my:form>
</xf:instance>In the second example below, the namespace prefix my is not defined in the namespace
context of the form element:
<form name="my:form" ... >
...
</form>
And as a result, the root element node is named data
and placed in the empty namespace:
<xf:instance>
<data xmlns="">
...
</data>
</xf:instance>In the third example below, an unprefixed name is given in the name attribute:
<form name="mydata"... >
...
</form>
And as a result, the root element node is named mydata
and placed in the empty namespace:
<xf:instance>
<mydata xmlns="">
...
</mydata>
</xf:instance>In the fourth example below, the name attribute is omitted:
And as a resulting generated data instance uses the default name of data:
<xf:instance>
<data xmlns="">
...
</data>
</xf:instance>If the startsize attribute appears on a form element, it must be ignored because the
default data instance of a form must be singly rooted. For the same reason, if a number
attribute appears on a form element, then it must be ignored. Finally, the attributes value,
and checked are ignored if they appear on a form element because it is a container form control.
3.1 The name Attribute
Data instance generation for a form is based on the name attributes on the elements or tags
within the form.
On the form element, if the name attribute is absent, then the default value is data.
The name attribute does not have a default except for form elements. If the name
attribute appears on an element or tag that is not a form element, then that element or tag is a form control within the
nearest ancestor form element.
If the name attribute value contains a PrefixedName, but the namespace prefix is not in the
namespace context of the element bearing the name attribute, then the name
attribute is ignored. On a form element, this causes the default value to be used. On any element
other than a form element, this causes the element to not be a form control.
During data instance generation, a data node is generated based on the name of each
form control. The QName of a generated data instance node is equal to the attribute value of the
name attribute on the form control bound to the data node. The data node for the form element
is created as the root element of the generated data instance. For each descendant form control in a form, the
data node is created as a child element of the data node created for the nearest ancestor container form control,
and the position of the data node is equal to the position of the form control in the child form control list of the
nearest ancestor container form control. This method creates a generated data instance whose structure matches
the user interface structure within the markup. This generation method is amended for simple repetition in Section
3.3 The startsize Attribute.
The root element of the generated data instance always bears the declaration xmlns="".
The root element of the generated data instance will also bear the correct namespace prefix definition
if the the data node has a PrefixedName. For any descendant nodes of the generated
data instance root element, if the node is not a PrefixedName, then no namespace qualifiers are added
when the node is initially generated. Otherwise, if the non-root node has a
PrefixedName, then a namespace prefix declaration
node must be added for the prefix of the non-root node. However, the following namespace
prefix promotion method is used:
The nearest ancestor is obtained in the generated data instance that has the matching namespace prefix
defined.
If no such ancestor is found, then the namespace prefix declaration is added to the root element
of the generated data instance.
If the nearest ancestor is found with a namespace prefix declaration for the prefix needed by the node being
generated, and the namespace URI of the ancestor node's prefix declarationmatches the namespace URI of
the prefix needed for the data node being generated, then no new namespace prefix declaration is
added because the declaration at the ancestor node will be inherited into the namespace context
of the newly generated node.
If the nearest ancestor namespace prefix declaration for the prefix needed by the node being
generated has a different namespace URI from the one needed for the data node being generated,
a new namespace prefix declaration with the proper namespace URI is added to the farthest ancestor
of the node being generated that is still a descendant of the ancestor with the conflicting namespace
prefix declaration.
This method generally minimizes the number of namespace declarations appearing in the generated data instance,
if the form author chooses to use namespaces in the data.
Once the data node for a form control is generated, the form control is bound to that data node
as if by an XForms user interface binding.
If, during data instance generation, a form control is encountered whose name
matches a node already generated, then a new data instance node is not generated since one
already exists. Instead, the form control is simply bound to the preexisting data instance node.
Note:
Duplicated names do not result in repeated data with the same name because XForms for HTML
offers an attribute and run-time form operations for handling dynamic data repetition.
When the form control also has the startsize attribute, then the form control is a repeat
form control, so it is simultaneously bound to all data nodes that match the name attribute value
that appear as children of the data node bound to the nearest ancestor container form control of the
repeat form control. Section 3.3 The startsize Attribute describes how multiple
nodes corresponding to the name of a repeat form control are generated, and Section
4.4 Dynamically Changing the Size of a Repeat Form Control describes run-time operations for increasing and decreasing the
number of data nodes associated with a repeat form control.
3.2 Initializing Generated Data Nodes
During data instance generation, the value, type, and checked
attributes are used to help determine initial values for the data nodes being generated on behalf of form control
with a name attribute. Additional semantics can be assigned to these attributes beyond the behaviors
described in this section.
This specification defines no processing for value, type, checked
when they appear on container form controls, which also includes the form element and repeat form controls.
A form control that is not a container form control is called a core form control.
When a data instance node is generated on behalf of a core form control, the node is also given
an initial value of either empty string or a copy of the value attribute value using the
the following method:
If the type attribute value has a case-insensitive match to
the value radio or checkbox, then the initial value
of the data node is obtained from the value attribute if it is given
and if the checked attribute produces a true result, and otherwise the
initial value of the data node is the empty string.
If the type attribute is not given or does not have a case-insensitive
match to the value radio or checkbox,
then the initial value of the data node is obtained from the value attribute if it
is given, and otherwise the initial value of the data node is the empty string.
If, during data instance generation, a core form control is encountered whose name
matches a data node already generated, then the value attribute, if given, is used to
amend the initial value of the preexisting data node using the following method:
If the type attribute value has a case-insensitive match to
the value radio, then the initial value of the data node is replaced
with a copy of the value attribute value.
If the type attribute value has a case-insensitive match to
the value checkbox, then the value attribute value is
appended to the initial value of the data node, with a separating space if the
data node was not an empty string.
Otherwise, the value attribute is regarded as a duplicate initializer and
is ignored.
Given the following HTML form:
<form action="preferences.asp" method="get">
<label for="name">Name: </label>
<input type="text" name="name" value="John Q. Public" />
<br />
<fieldset name="region">
<label for="city">City: </label>
<input type="text" name="city" value="Victoria" />
<br />
<label for="country">Country: </label>
<input type="text" name="country" value="Canada" />
<br />
</fieldset>
<label for="favorite">Choose your favorite music type: </label>
<input type="radio" name="favorite" value="rock"> Rock<br>
<input type="radio" name="favorite" value="pop" checked> Pop<br>
<input type="radio" name="favorite" value="alternative"> Alternative<br>
<input type="radio" name="favorite" value="classical"> Classical<br>
<label for="prefs">Choose all the music types you enjoy: </label>
<input type="checkbox" name="prefs" value="rock" checked> Rock<br>
<input type="checkbox" name="prefs" value="pop" checked> Pop<br>
<input type="checkbox" name="prefs" value="alternative"> Alternative<br>
<input type="checkbox" name="prefs" value="classical" checked> Classical<br>
<input type="submit" value="Submit" />
</form>
the data instance is generated and initialized as follows:
<xf:instance>
<data xmlns="">
<name>John Q. Public</name>
<region>
<city>Victoria</city>
<country>Canada</country>
</region>
<favorite>pop</favorite>
<prefs>rock pop classical</prefs>
</data>
</xf:instance>
Implementations that perform run-time document serialization must preserve the original
value attribute values in the document serialization.
Implementations of run-time document serialization must preserve
run-time values by writing the declared default data instance into the content of the form element
(i.e. using an <xf:instance> element indicated by an instance attribute on the form element).
This technique helps minimize alteration of the host document markup during serialization, and it
preserves repeated data.
3.3 The startsize Attribute
When the startsize attribute is used in combination with the name attribute,
the element bearing the attributes becomes a repeat form control. If the attribute value is not
a non-negative integer, then the value 1 is used.
If the name attribute matches preexisting data nodes, then the repeat form control is
bound to the data nodes without generating any new data instance nodes. Otherwise, the data instance
generation process for the repeat form control and the form controls it contains is repeated zero or more
time according to the number in the startsize attribute.
Once the data instances of the forms are initialized, the repeat form control treats its content as a template
and generates a copy of the template once for each node bound to the repeat form control. A template instance
is called a repeat object, and the data node for which a repeat object is created is called the
generator node. The form controls in each repeat object are bound to the nodes in the
data subtree rooted by the generator node.
Suppose the following table appeared as a child element of a form.
<table summary="List of items to purchase" name="order">
<thead>
<tr>
<th>Product Name</th>
<th>Unit Cost</th>
<th>Quantity</th>
<th>Product Total</th>
</tr>
</thead>
<tbody name="item" id="item" startsize="1">
<tr>
<td>
...
</td>
<td>
<label for="unitprice" class="within_table">Unit Price</label>
<input name="unitprice" type="text" value="0" ... />
</td>
<td>
<label for="quantity" class="within_table">Product Quantity</label>
<input name="quantity" type="text" value="1" ... />
</td>
<td>
...
</td>
</tr>
</tbody>
</table>
The result of data instance generation would be the following:
<xf:instance>
<data xmlns="">
...
<order>
<item>
...
<unitprice>0</unitprice>
<quantity>1</quantity>
...
</item>
</order>
...
</data>
</xf:instance>
3.4 The number Attribute
A hint to the processor about the maximum number of repeat objects to present
within a repeat form control before using a secondary presentation mechanism, such as
scrolling.
4 Runtime Operations on Form Controls
4.1 Getting and Setting the Value of a Form Control
Each form control has the possibility of rendering a formatted version of the textual content
stored in the data node bound to the form control. For example, a data value of 1234.567
could be presented in the form control as $1,234.57.
Each form control has an associated value property that contains the current textual content
being rendered by the form control. This property can be examined by script that seeks the formatted data
value of the form control, and a raw data value can be formatted by script and assigned to this property.
Each form control is augmented with methods getValue() and setValue(string).
The getValue() method returns the underlying raw data value, which is textual content of the data
node bound to the form control. The setValue() method is used to assign a raw data value
to the data node bound to the form control. The setValue() method assigns the raw data value to the
value property and then it behaves as if it has invoked an XForms setValue action to send
the raw data value to the XForms data instance. Thus, this operation respects the readonly setting of a data node,
and it invokes the XForms model update sequence (recalculate, revalidate, refresh).
In this example, the form control identified as X is set to the value "1234.567":
onClick="document.getElementById('X').setValue('1234.567') "Note:
Once a raw data value assignment has been made with the setValue() method,
the XForms model update sequence includes dispatching the xforms-value-changed
event to the form control bound to the data node changed by setValue(). An author
could write an event handler for this event to run script that invokes getValue(), performs
formatting operations on the raw data, and then assigns the formatted string to the value
property of the form control.
When end-user input into a form control is committed to the value property, a
change event also occurs. The XForms for HTML processor attaches a handler function to the change event
that invokes the setValue() method for the form control.
Note:
If an author uses the value property to handle formatted text on a form control that
is not readonly, then the author also has to deal with conversion of end-user input from formatted text
to raw data. Such an author must overload the base setValue() method of the form
control described above so that the author's script code can convert the user input to raw data and then
invoke the prototypical setValue() method.
4.2 Setting the Focus to a Form Control
All form controls are augmented with a method focus(). When invoked, the web page navigates to the form control for which the method has been invoked. In the case of a container form control, the focus() method of the first form control in its child form control list is invoked. In the case of a repeat form control, the focus() method is invoked on the first form control in the child form control list of the currently indexed repeat object (see 4.4 Dynamically Changing the Size of a Repeat Form Control for further details about repeat index management).
4.3 Finding Runtime Form Controls by ID
It is possible for a form control in a repeat object to have numerous counterparts in other repeat objects, all identifiable under the ID given to the template for the form control. The document.getElementById() method is insufficient for finding these repeated form controls.
The document and all repeat form controls are augmented with a method called getRuntimeElementById(), which receives a string containing an IDREF and returns either the identified element or null. The method searches within the scope of the object on which the method was invoked. In the case of a document, the document is searched. In the case of a repeat form control, the repeat object corresponding to the repeat index is searched. If the identified element is found within the ID space of the object, then it is returned. Otherwise, for each repeat form control in the scope of the invoking object, the getRuntimeElementById() method is invoked until a matching element is found or until all repeat form controls have been interrogated. If a match is found, it is returned. Otherwise null is returned.
4.4 Dynamically Changing the Size of a Repeat Form Control
A repeat form control has additional associated semantics so that it can be
dynamically increased or decreased in size.
Upon initialization, each repeat form control takes a snapshot of its initial content and the
corresponding data generated for one repeat object. These are to be used as templates for
data and user interface operations needed when increasing or decreasing the size of the
repeat form control.
Each repeat form control maintains an index of a repeat object that will be the
object of dynamic operations that increase or decrease the size of the repeat form control.
The initial index of a repeat control is 1.
When the user changes the focus to a form control in a repeat object, the index of the repeat form
control is automatically changed to indicate the repeat object that contains the focus.
If the number of repeat objects associated with the repeat form control is decreased to zero,
the repeat index becomes equal to zero.
Each repeat form control has an associated operation called increaseSize().
When invoked, this operation inserts a new copy of the template data and template user interface content
after the location indicated by the current index of the repeat form control. The index of the repeat
form control is then increased by 1. Notification of the completion of the
insertion of data is signaled by dispatching the xforms-insert event (see [XForms 1.1])
to the default data instance element, which can also be observed at the containing form element.
Each repeat form control has an associated operation called decreaseSize(boolean allowEmpty).
If the index of the repeat form control is equal to zero, the decrease operation has no effect.
When invoked, this operation deletes the data and user interface content corresponding to the
location indicated by the current index of the repeat form control. Notification of the completion of the
deletion of data is signaled by dispatching the xforms-delete event (see [XForms 1.1])
to the default data instance element, which can also be observed at the containing form element.
After the deletion phase of the decreaseSize() operation, if the
number of repeat objects still associated with the repeat form control is less than the index of the
repeat form control, then the index of the repeat form control is decreased by 1.
If the index of the repeat form control becomes equal to zero and the value of the parameter
allowEmpty is boolean false, then the increaseSize()
operation defined above is performed on the repeat form control.
In the example of 3.3 The startsize Attribute, the id attribute
allows the following code to invoke the increaseSize() operation:
onClick="document.getElementById('item').increaseSize()"Similarly, the decreaseSize() operation can be invoked as follows:
onClick="document.getElementById('item').decreaseSize(false)"When data is inserted or deleted by the increaseSize() or decreaseSize()
operation, the computational dependencies that comprise the calculation system and properties
described in 5 Declarative Execution Model for Data Instances are rebuilt to accommodate the newly inserted or
deleted data, then the expressions for calculated values and properties are reevaluated, and the results
are used to refresh the user interface. This sequence of operations is aligned with the behaviors of
[XForms 1.1] after performing an insert or delete action.
5 Declarative Execution Model for Data Instances
5.1 Declarative Validation
This section describes attributes for declarative validation of data. These attributes can be applied to
a form control and provide validity information for the data node associated with the form control.
| Attributes | Content Model | Description |
|---|
| datatype | xsd:QName | This attribute indicates a datatype to be used for validating the data associated with the form control that bears this attribute. Available values for this attribute are as defined for the type attribute in [XForms 1.1] (see the Datatypes section). An unprefixed attribute value is interpreted as a reference to a datatype in the XForms namespace. The default is xsd:string, except when provided by another form control of the same name. This attribute is not applicable to and must be ignored when used on container form controls. |
| required | Either an XPath expression or one of the following reserved words: true (also TRUE, required, or REQUIRED) or false (also FALSE). | This attribute indicates whether or not the end-user must provide a non-empty string. The default is false, except when provided by another form control of the same name. When the attribute is expressed, the result is true if the attribute value is one of the true keywords or if it is an XPath expression that evaluates to a boolean result of true. In HTML, if the attribute value is not specified, then the existence of the attribute is construed as a true result, and its absence is construed as a false result. When the required attribute value is an XPath expression, and it is evaluated, the result is converted to a boolean. Also, the XPath expression is dynamically reevaluated when any of the data values on which it depends are changed. This attribute is not applicable to and must be ignored when used on container form controls. |
| constraint | An XPath expression | This attribute provides an expression, the boolean result of which indicates whether or not the data node bound to the form control is valid. The default is true, except when provided by another form control of the same name. When the constraint expression is evaluated, the result is converted to a boolean. Also, the expression is dynamically reevaluated when any of the data values on which it depends are changed. This attribute is not applicable to and must be ignored when used on container form controls. |
When two or more form controls share a name, they are bound to the same node of data. All of the form controls bound to the same data node must either use the default for each of these attributes or express exactly the same attribute value for each of these attributes. Implementation behavior is undefined when this requirement is not satisfied. The true keywords are considered equivalent, as are the false keywords. For example, if one form control has a required of true, a second form control with the same name can have no required attribute or it could express a required of true or TRUE (or required or REQUIRED), but implementation behavior is undefined if the second form control expresses a required that contains either an expression or one of false and FALSE.
The data associated with a form control is valid if it meets the validity criteria set forth by the XForms model. Using only XForms for HTML attributes in this section, the data bound to a form control is valid if it meets the validity criteria of all three of the validation attributes in this section, and it is invalid if it fails to meet the criterion of any one of the three attributes. The criterion for an attribute is implicitly satisfied if the attribute is not specified. A form control is valid if it is bound to a valid data node and invalid otherwise.
The form controls shall receive validity notification events in a manner aligned with [XForms 1.1]. Specifically, the form control shall receive the event xforms-valid if the value of the data node to which the form control is bound changes and the data is valid, or if the data value does not change but the validity of the data changes to valid. The form control shall receive the event xforms-invalid if the value of the data node to which the form control is bound changes and the data is invalid, or if the data value does not change but the validity of the data changes to invalid. The change of a data value by any means, including by data entry into a form control, has the possible side effect of producing validity change events (xforms-valid and xforms-invalid events) on form controls bound to the data as well as form controls whose validity is dependent upon the changed data value. After a data value change, the effects on validity of all data nodes is assessed, and then the xforms-valid and xforms-invalid events are dispatched to the affected form controls.
The age and years of education are required integers, and the years of education
cannot exceed the age of a person.
<label for="age">Age: </label>
<input type="text" name="age" required datatype="integer"/>
<br />
<label for="education">Years of education: </label>
<input type="text" name="education" required="true" datatype="integer" constraint="age >= education" />
<br />
Implementations of form controls should select user interface elements most appropriate to the expressed datatype and the rendition device. For example, a form control bound to a data node with a datatype of date or xsd:date should be presented on a desktop computer screen as a calendar date selection control. Similarly, a check box should be presented on a computer screen for a form control bound to a data node with a datatype of boolean or xsd:boolean. Similarly, a form control bound to a data node with the datatype card-number should be able to both render and accept grouping separators for long credit card, debit card and identity card numbers.
5.2 Declarative Data Access with the readonly Attribute
This section describes an attribute for declarative access control of data (read only versus read/write).
| Attributes | Content Model | Description |
|---|
| readonly | Either an XPath expression or one of the following reserved words: true (also TRUE, readonly or READONLY) or false (also FALSE). | This attribute indicates whether or not access to the data node value associated with the form control is read only or read/write. The default is true if any ancestor data node is readonly or if the data node is calculated (see 5.3 Declarative Calculation). Otherwise, the default is false, except when provided by another form control of the same name. When the attribute is expressed, the result is true if the attribute value is one of the true keywords or an XPath expression that evaluates to a boolean result of true. In HTML, if the attribute value is not specified, then the existence of the attribute is construed as a true result, and its absence is construed as a false result. When the readonly attribute value is an XPath expression, and it is evaluated, the result is converted to a boolean. Also, the XPath expression is dynamically reevaluated when any of the data values on which it depends are changed. This attribute can be used on container form controls. |
When two or more form controls share a name, they are bound to the same node of data. All of the form controls bound to the same data node must either use the default for readonly or express the same logical attribute value. Implementation behavior is undefined when this requirement is not satisfied. For example, if one form control has a readonly of true, a second form control with the same name can have no readonly attribute or it could express a readonly with a value equal to one of the true keywords, but implementation behavior is undefined if the second form control expresses a readonly that contains either an XPath expression or one of the false keywords.
The form controls shall receive data access notification events in a manner aligned with [XForms 1.1]. Specifically, the form control shall receive the event xforms-readonly if the value of the data node to which the form control is bound changes and the data node is readonly, or if the data value does not change but the result of the readonlyexpression changes to true. The form control shall receive the event xforms-readwrite if the value of the data node to which the form control is bound changes and the data node is not readonly, or if the data value does not change but the result of the readonly expression changes to false. The change of a data value by any means, including by data entry into a form control, has the possible side effect of producing data access notification events (xforms-readonly and xforms-readwrite events) on form controls bound to the data as well as form controls whose data access property is dependent upon the changed data value. After a data value change, the effects on data access properties of all data nodes is assessed, and then the xforms-readonly and xforms-readwrite events are dispatched to the affected form controls.
Note:
The data access property of a data node can change due to reevaluation of a readonly attribute attached to the data node or to any any ancestor of the data node.
This example shows how a section of the document can be conditionally readonly. In this case, a hidden input is used to create a data node that can be used to store an indication of whether or not the current user is a manager, and that information is used to control whether the user can modify the manager section of the document.
<input type="hidden" name="isManager" value="false" />
<fieldset name="managerSection" readonly=" isManager='false' ">
...
</fieldset>
If a data node is readonly, then the implementation must suppress all mutations of the content and attributes of the data node except changes by the declarative calculation engine (see 5.3 Declarative Calculation). This restriction applies to insertion, deletion and modification of descendant nodes of any kind (e.g. text, element, and attribute nodes).
5.3 Declarative Calculation
This section describes an attribute for declarative data value calculations.
| Attributes | Content Model | Description |
|---|
| calculate | XPath expression | This attribute provides an expression that determines the value (string content) of the data node bound to the form control that bears this attribute. The expression is dynamically reevaluated when any of the data values on which it depends are changed, and the form control value is changed to match. This attribute is not applicable to and ignored when used on container form controls. |
When two or more form controls share a name, they are bound to the same node of data. All of the form controls bound to the same data node must either express no calculate attribute or, if the calculate attribute appears, it must contain the same expression as any other form control that expresses calculate and is bound to the same data node. Implementation behavior is undefined when this requirement is not satisfied.
During form initialization, a system of computational dependencies is constructed for the calculated data nodes, as described in [XForms 1.1]. This dependency system is rebuilt after structural modifications of the data instance, including after increaseSize() and decreaseSize() operations (see 4.4 Dynamically Changing the Size of a Repeat Form Control and after submission data instance replacement (see 6 Data Submissions). After data value modifications, such as by user interaction with a form control, the dependency system is used to determine which dependent calculate expressions need to be reevaluated, the results of which are reflected in the data and the user interface.
The form controls shall receive value change notification events in a manner aligned with [XForms 1.1]. Specifically, the form control shall receive the event xforms-value-changed if the value of the data node to which the form control is bound changes. This could occur for a number of reasons, including due to the action of the form control, due to reevaluation of a calculate, or due to a script modification of the data. After a data value change, the effects on all dependent calculate formulae are assessed, and then the xforms-value-changed events are dispatched to the affected form controls.
The classic compounded interest loan calculation:
<label for="principal">Amount to borrow: </label>
<input type="text" name="principal" required datatype="decimal" constraint="principal > 0" />
<br />
<label for="duration">Duration of loan in years: </label>
<input type="text" name="duration" required="required" datatype="positiveInteger" />
<br />
<label for="interest">Yearly interest rate (compounded monthly): </label>
<input type="text" name="interest" required="true" datatype="decimal" constraint="interest >= 0"/>
<br />
<input type="hidden" name="rate" calculate="interest div 1200.0" />
<label for="payment">Monthly Payment: </label>
<input type="text" name="payment"
calculate="if(principal > 0 and interest > 0,
principal * rate div (1.0 - power(1.0 + rate, -duration*12)), 0)" />
By default, if a data node is calculated, then it is also readonly. The readonly property
of a calculated form control can be set to false so that the calculated value can be overridden,
as shown in the following example.
This example shows a calculation that only changes the value of a form control if
it contains a certain threshold value (empty in this case).
<label for="qty">Quantity: </label>
<input type="text" name="qty" readonly="false" calculate="if(qty>=0, qty, 0)"/>
<br />
5.4 Declarative Relevance
This section describes an attribute for declarative definition of data relevance.
| Attributes | Content Model | Description |
|---|
| relevant | An XPath expression | This attribute indicates whether or not the data node associated with the form control is relevant. The default is false if any ancestor data node is non-relevant. Otherwise, the default is true, except when provided by another form control of the same name. When the attribute is expressed, the result is true if the XPath expression evaluates to a boolean result of true. When the relevant attribute value is evaluated, the result is converted to a boolean. Also, the XPath expression is dynamically reevaluated when any of the data values on which it depends are changed. This attribute can be used on container form controls. |
When two or more form controls share a name, they are bound to the same node of data. All of the form controls bound to the same data node must either use the default for relevant or express exactly the same attribute value. Implementation behavior is undefined when this requirement is not satisfied.
The form controls shall receive data relevance notification events in a manner aligned with [XForms 1.1]. Specifically, the form control shall receive the event xforms-enabled if the value of the data node to which the form control is bound changes and the data node is relevant, or if the data value does not change but the result of the relevantexpression changes to true. The form control shall receive the event xforms-disabled if the value of the data node to which the form control is bound changes and the data node is not relevant, or if the data value does not change but the result of the relevant expression changes to false. The change of a data value by any means, including by data entry into a form control, has the possible side effect of producing data relevance notification events (xforms-enabled and xforms-disabled events) on form controls bound to the data as well as form controls whose data relevance property is dependent upon the changed data value. After a data value change, the effects on data relevance properties of all data nodes is assessed, and then the xforms-enabled and xforms-disabled events are dispatched to the affected form controls.
Note:
The relevance of a data node can change due to reevaluation of a relevant attribute attached to the data node or to any ancestor of the data node.
A section of the document that is conditionally non-relevant (hidden or disabled, depending on styling).
<fieldset name="guardianSection" relevant="applicantAge < 18">
...
</fieldset>
5.5 Declarative XPath Expression Context
Some attributes of this section contain XPath expressions. These attributes are attached to form controls.
The evaluation context node is the one bound to the nearest ancestor form control, which is the
parent data node of the data node bound to the form control that bears the attribute containing
the XPath expression. The evaluation context size and position are also based on the size of the
nodeset that contains the evaluation context node and the position of the context node in that nodeset.
This allows the data nodes bound to form controls at the same logical level
(i.e. sibling form controls) to be referenced in the XPath expression using the name of the form control.
The data nodes at other logical levels are accessible by normal XPath means, for example by using
a / (slash) to access children of a node and .. (dot dot) to access the parent.
The function library includes all functions defined by XPath 1.0 and by [XForms 1.1].
In the purchase order example of Section 3.3 The startsize Attribute, the product of the
quantity and unitprice can be calculated for each table row by filling in the
fourth td as follows:
<td>
<input name="lineTotal" calculate="quantity * unitprice" />
<td>
A calculation over a table column is exemplified by the following purchase order subtotal calculation:
<input name="subtotal" calculate="sum(item/lineTotal)" />
6 Data Submissions
This section describes the attributes that control server communications. The classic URL encoded format
is available by default, but data submission in XML and JSON formats is also available. In addition, data submission
can be used to update the current page, not just to replace a web page. Lastly, attributes are available that
connect data validation and relevance to the preprocessing of data submission.
These attributes can be used on the form element to control the main form submission, and they can also be used on submit elements, such as an input tag with a type of submit, to control customized submissions within the form.
The element or tag that configures the submission shall receive XForms submission events, including xforms-submit, xforms-submit-serialize, xforms-submit-done and xforms-submit-error, in a manner aligned with [XForms 1.1].
The element or tag that configures the submission shall be augmented with a method
named processResult(), which performs the submission result processing as defined under the
xforms-submit event in [XForms 1.1].
For JSON submissions, the callback parameter of the JSON service must be set to this method of the submit form control
in order to ensure correct completion of submission processing.
| Attributes | Content Model | Description |
|---|
| serialization | application/www-url-encoded, application/xml, or application/javascript | This attribute indicates the serialization format of the data instance to be submitted to the server. The default is application/www-url-encoded. |
| source | XPath expression | This attribute indicates the portion of the form's data instance that is to be serialized for submission. By default, the entire data instance of the form is serialized for submission. If the attribute is given, then it is evaluated in the XPath context of the containing form, i.e. relative to the document element of the form's data instance. No data is selected for serialization unless the expression produces a nodeset. The first node of the resultant nodeset indicates the data instance subtree that is to be serialized for submission. |
| replace | all, none, instance, or text | This attribute indicates how the result of a submission will be handled. The default is all. If the setting is all, then the web page is replaced with the submission result. In the case of the setting none, the submission result is discarded. If the setting is instance or text, then some or all of a data instance inthe form is replaced with the submission result. The portion of the data to be replaced is controlled by the target attribute, or its default. If the setting is instance, then a target node from a data instance is replaced with the submission result. If the setting is text, then the content of the target node from a data instance is replaced with a text encoded form of the submission result. |
| target | XPath expression | This attribute indicates the portion of a data instance in the form that is to be replaced with the result of submission. By default, the entire data instance of the form is replaced (if the replace attribute setting is instance or text). If the attribute is given, then it is evaluated in the XPath context of the containing form, i.e. relative to the document element of the form's data instance. No data is selected for replacement unless the expression produces a nodeset. The first node of the resultant nodeset indicates the data instance node that is the target of the replacement. |
| action | xsd:anyURI | This attribute indicates the URL of the submission, either directly by the attribute value or indirectly by data reference if the URI scheme is xpath. If the form of the action attribute value is xpath:expression, then the expression is evaluated in the context of the containing form, and the string result of the expression is interpreted as the submission URL. Note that the expression could indicate a calculated data node bound to a hidden input element, thus providing flexibility in authoring the dynamic construction of the submission URL. The element or tag that bears this attribute shall be the target of XForms submission events related to the submission. |
| validate | xsd:boolean | This attribute indicates whether submission will be terminated with an xforms-submit-error event if any of the data nodes being submitted are invalid (see definition in 5.1 Declarative Validation). The default is true. |
| prune | xsd:boolean | This attribute indicates whether non-relevant data nodes will be pruned from the submission data before validation and serialization. The default is true. |
| method | get, post, put, delete, GET, POST, PUT, DELETE, or any other xsd:string | Indicates a protocol-specific submission operation to be performed. The intent of this attribute is to be aligned with submission operations of the HTTP protocol. |
| submission | xsd:IDREF | In lieu of using the submission attributes defined above, a form element or submit element can use this attribute to delegate control of submission to an identified XForms submission element. |
| Editorial note | |
The working group is particularly interested in feedback on the action attribute. XForms still supports using action, but authors are encouraged to use use the resource attribute instead for specifying the URI of a submission. Is this preferable in XForms for HTML? Specifically, does using action on a form control cause problems in any well-known web applications? |
| Editorial note | |
The working group is particularly interested in feedback on the source attribute. It is intended to be equivalent to the ref attribute on an XForms submission, which identifies the subtree of data being submitted. However, since ref can also be used on a form control to bind the form control to XForms instance data, an alternative attribute name is needed. The chosen name does not conflict with the src attribute and is consistent with the name of the target attribute. Are there good reasons for not using the name source for this attribute, and are there any better alternatives? |
| Editorial note | |
The working group is particularly interested in feedback on the target attribute. When used in combination with replacing instance data within the web page, this attribute indicates the portion of data to replace with the submission results. This seems consistent with the use of target to indicate a portion of a document to replace in the page refresh case. It is also consistent with the attribute of the same name in an XForms submission. Still, are there good reasons for not using the name target for this attribute, and are there any better alternatives? |
| Editorial note | |
The working group is particularly interested in feedback on the prune and validate attributes. These are simple boolean attributes that indicate whether or not certain submission data preprocessing steps occur. The prune attribute is synonymous with the relevant attribute on an XForms submission, but an alternate attribute name was needed because the relevant attribute on a form control expresses a formula for indicating whether or not the node of data bound to the form control is relevant to presentation in the user interface and submission, so the same attribute name cannot be used to indicate whether or not a submission initiated by a form control should perform pruning of non-relevant data nodes from the submission data. The validate attribute performs the same function as the attribute of the same name on an XForms submission, namely that it ensures validity constraints on the pruned data are met before proceeding with submission. Would it be better to use a single attribute for configuring all preprocessing, e.g. preprocess="validate: true; relevant: false;", rather than using separate attributes? |
The following markup posts XML for the data instance of the form:
<form serialization="application/xml" method="post" ... >
...
</form>
The following markup saves the XML for the data instance of the form to a server:
<form ... >
...
<input type="submit" serialization="application/xml" method="post" replace="none"
validate="false" prune="false" action="http://example.org/save" >
...
</form>The following markup enables a submit element to posts XML for a portion of the data instance
and uses the result to replace another portion of the data:
<form ... >
<fieldset name="employee">
<input type="text" name="name" ... >
...
</fieldset>
<input type="submit" serialization="application/xml" method="post" replace="instance"
source="employee/name" target="employee" action="http://example.org/lookup" >
...
</form>