Table of Contents | Prev | Next | Bottom |
Quick Table of Contents |
---|
11 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 Method |
XForms is designed to gather instance data, serialize it into an external representation, and submit it with a protocol. XForms defines a set of options for serialization and submission. The following sections define the processing of instance data for submission, and the behavior for the serialization and submission options.
Submission begins with the default action for a xforms-submit
event.
Target: submission
Bubbles: Yes
Cancelable: Yes
Context Info: None
Under no circumstances may more than a single concurrent submit process be under way for a particular XForms submission. From the start of the default action of xforms-submit
, until the completion of the default action for xforms-submit-done
or xforms-submit-error
, the default action for subsequent xforms-submit
events is to do nothing.
Otherwise, default action for this event results in the following steps:
A node from the instance data is selected, based on attributes on the submission
element. The indicated node and all nodes for which it is an ancestor are considered for the remainder of the submit process. Any node which is considered not relevant as defined in 6.1.4 The relevant Property is removed.
All selected instance data nodes are checked for validity
according to the definition in
4.3.5 The xforms-revalidate Event
(no notification events are marked for
dispatching due to this operation).
Any selected instance data
node that is required but empty or found to
be invalid stops submission
processing after dispatching event xforms-submit-error
.
Selected instance data is serialized according to the rules stated at 11.2 Submission Options.
Serialized instance data is submitted using the protocol indicated by the rules stated at 11.2 Submission Options.
The response returned from the submission is applied as follows:
For a success response including a body, when the value of the replace
attribute on element submission
is "all
", the event xforms-submit-done
is dispatched, and submit processing concludes with entire containing document being replaced with the returned body.
For a success response including a body of an XML media type (as defined by the content type specifiers in [RFC 3023]), when the value of the replace
attribute on element submission
is "instance
", the response is parsed as XML. An xforms-link-exception (4.5.2 The xforms-link-exception Event) occurs if the parse fails. If the parse succeeds, then all of the internal instance data of the instance indicated by the instance
attribute setting is replaced with the result. Once the XML instance data has been replaced, the rebuild, recalculate, revalidate and refresh operations are performed on the model, without dispatching events to invoke those four operations. Submit processing then concludes after dispatching xforms-submit-done
.
For a success response including a body of a non-XML media type (i.e. with a content type not matching any of the specifiers in [RFC 3023]), when the value of the replace
attribute on element submission
is "instance
", nothing in the document is replaced and submit processing concludes after dispatching xforms-submit-error
.
For a success response including a body, when the value of the replace
attribute on element submission
is "none
", submit processing concludes after dispatching xforms-submit-done
.
For a success response not including a body, submit processing concludes after dispatching xforms-submit-done
.
Behaviors of other possible values for attribute replace
are not defined in this specification.
For an error response nothing in the document is replaced, and submit processing concludes after dispatching xforms-submit-error
.
The XForms Model specifies a submission
element containing the following attributes that affect serialization and submission. This section summarizes the behaviors for the allowable values of these attributes, and introduces the following sections that define the behavior for serialization and submission. (See 3.3.3 The submission Element for additional submission
attributes that affect serialization.)
action
(xsd:anyURI)
method
(xsd:string, enumerated below)
For the URI scheme of action
, XForms normatively defines a binding to HTTP/1.1 [RFC 2616].
Note:
Other bindings, in particular to the URI scheme "mailto:" may, and the schemes "https:" and "file:" should, be supported. Bindings to these schemes are not normatively defined in XForms. Implementations that choose to provide a binding to these schemes should pay particular attention to privacy and security concerns. Within the "http:" and "https:" schemes, form creators are encouraged to follow the finding of the W3C Technical Architecture Group on when to use the GET method: [TAG Finding 7]
The method
attribute determines the serialization format, and the URI scheme used in the action
attribute determines the submit protocol, according to the following table:
URI scheme | method |
Serialization | Submission |
---|---|---|---|
http https mailto | "post" | application/xml |
HTTP POST or equivalent |
http https file | "get" | application/x-www-form-urlencoded |
HTTP GET or equivalent |
http https file | "put" | application/xml |
HTTP PUT or equivalent |
http https mailto | "multipart-post" | multipart/related |
HTTP POST or equivalent |
http https mailto | "form-data-post" | multipart/form-data |
HTTP POST or equivalent |
http https mailto | "urlencoded-post" (Deprecated) | application/x-www-form-urlencoded |
HTTP POST or equivalent |
(any) | any other QNAME with no prefix | N/A | N/A |
(any) | any QNAME with a prefix | implementation-defined | implementation-defined |
Note:
Foreign-namespaced attributes are allowed on element submission
, but no behavior is defined by XForms 1.0.
This format permits the expression of the instance data as XML that is straightforward to process with off-the-shelf XML processing tools. In addition, this format is capable of submission of binary content.
The steps for serialization are as follows:
An XML document is produced following the rules of the XML output method defined in [XSLT 1.0] section 16 and 16.1, using the values supplied as attributes of the submission
element.
Handling of namespace nodes: The default behavior is that every namespace node is serialized according to the rules of the XML output method, so that at least one namespace declaration appears in the serialized XML for each in-scope namespace. Additional inherited namespaces are declared on the root element of the serialized XML. If, however, attribute includenamespaceprefixes
on element submission
is present, then all namespace declarations not visibly utilized in the instance data (as defined in [Exc-C14N]) and the default namespace if it is empty are excluded from the root element serialization, unless the corresponding namespace prefix is listed in the includenamespaceprefixes
attribute. The special value #default
represents the default namespace.
Mediatype: By default, the mediatype of the serialized XML instance is application/xml
, but can be changed to a compatible type using element submission
attribute mediatype
. Authors should ensure that the type specified is compatible with application/xml
.
This format is intended for integration of XForms into environments that involve large amounts of binary data where the inclusion of the data as xsd:base64Binary
or xsd:hexBinary
is undesirable.
In this format, XML instance data is serialized as one part of the [RFC 2387] multipart/related
message, using the rules as described in 11.3 Serialization as application/xml. Binary content from xsd:anyURI
instance nodes populated by the upload
(see 8.1.6 The upload Element) control is serialized in separate parts of the [RFC 2387] multipart/related
message.
This format follows the rules of multipart/related
MIME data streams for in [RFC 2387], with specific requirements of this serialization listed below:
multipart/related
message header requirements:
Must contain a type
parameter of the mediatype of the serialized XML instance.
Must contain a start
parameter referring to the Content-ID first body part (root).
First body part (root) requirements:
Must have Content-Type
parameter of the type specified by the submission
mediatype
attribute.
Content is serialized by the rules at 11.3 Serialization as application/xml.
Subsequent part requirements:
One part for each node with a datatype of xsd:anyURI
populated by upload
with:
A Content-Type
header that represents the type of the attachment if known, otherwise application/octet-stream
.
A Content-Transfer-Encoding
header.
A Content-ID
header whose value matches the URI in the associated instance data node.
The binary content associated with the URI, serialized according to the Content-Transfer-Encoding
heading.
Content-Type: multipart/related; boundary=f93dcbA3; type=application/xml; start="<980119.X53GGT@example.com>" Content-Length: xxx --f93dcbA3 Content-Type: application/xml; charset=UTF-8 Content-ID: <980119.X53GGT@example.com> <?xml version="1.0"?> <uploadDocument> <title>My Proposal</title> <author>E. X. Ample</author> <summary>A proposal for a new project.</summary> <notes image="cid:980119.X17AXM@example.com">(see handwritten region)</notes> <keywords>project proposal funding</keywords> <readonly>false</readonly> <filename>image.png</filename> <content>cid:980119.X25MNC@example.com</content> </uploadDocument> --f93dcbA3 Content-Type: image/png Content-Transfer-Encoding: binary Content-ID: <980119.X25MNC@example.com> ...Binary data here... --f93dcbA3 Content-Type: image/png Content-Transfer-Encoding: binary Content-ID: <980119.X17AXM@example.com> ...Binary data here... --f93dcbA3--
This format is for legacy compatibility to permit the use of XForms clients with [RFC 2388] servers. This method is suitable for the persistence of binary content. Contextual path information, attribute values, namespaces and namespace prefixes are not preserved. As a result, different elements might serialize to the same name.
Note:
Existing HTML user agents fail to encode special characters (such as double quotes) and non-ASCII characters in the Content-Disposition: form-data
name
and filename
parameters. Since this serialization method is supported for legacy applications only, new applications should use application/xml
or multipart/related
.
This format follows the rules for multipart/form-data
MIME data streams in [RFC 2388], with specific requirements of this serialization listed below:
Each element node is visited in document order.
Each element that has exactly one text node child is selected for inclusion.
Element nodes selected for inclusion are as encoded as Content-Disposition: form-data
MIME parts as defined in [RFC 2387], with the name
parameter being the element local name.
Element nodes of any datatype populated by upload
are serialized as the specified content and additionally have a Content-Disposition
filename
parameter, if available.
The Content-Type
must be text/plain
except for xsd:base64Binary
, xsd:hexBinary
, and derived types, in which case the header represents the media type of the attachment if known, otherwise application/octet-stream
. If a character set is applicable, the Content-Type
may have a charset
parameter.
Example:
Content-Type: multipart/form-data; boundary=AaB03x Content-Length: xxx --AaB03x Content-Disposition: form-data; name="document"; filename="b.txt" Content-Type: text/plain; charset=iso-8859-1 This is a file. It has two lines. --AaB03x Content-Disposition: form-data; name="title" A File --AaB03x Content-Disposition: form-data; name="summary" This is my file file test --AaB03x--
This serialization format is designed to allow the use of a form to gather the data necessary to produce a URI that names a resource and for accessing that resource with an HTTP GET operation.
This format represents an extension of the [XHTML 1.0] form content type application/x-www-form-urlencoded
with specific rules for encoding non-ASCII and reserved characters.
This format is not suitable for the persistence of binary content. Therefore, it is recommended that forms capable of containing binary content use another serialization method.
The steps for serialization are as follows:
Each element node is visited in document order. Each element that has one text node child is selected for inclusion. Note that attribute information is not preserved.
Element nodes selected for inclusion are encoded as EltName=value
, where =
is a literal character, EltName
represents the element local name, and value
represents the contents of the text node. The separator character {sep} from the separator
attribute on submission
is used between pairs of encoded name/value pairs, e.g. EltName1=value1{sep}EltName2=value2{sep}EltName3=value3
. Note that contextual path information is not preserved, nor are namespaces or namespace prefixes. As a result, different elements might serialize to the same name.
The encoding of EltName
and value
are as follows: space characters are replaced by +
, and then non-ASCII and reserved characters (as defined by [RFC 2396] as amended by subsequent documents in the IETF track) are escaped by replacing the character with one or more octets of the UTF-8 representation of the character, with each octet in turn replaced by %HH
, where HH
represents the uppercase hexadecimal notation for the octet value and %
is a literal character. Line breaks are represented as "CR LF" pairs (i.e., %0D%0A
).
All such encodings are concatenated, maintaining document order.
Example:
GivenName=Ren%C3%A9
This format consists of simple name-value pairs.
<PersonName title="Mr"> <GivenName>René</GivenName> </PersonName>
Here is the instance data for the above example. Note that very little of the data is preserved. Authors desiring greater data integrity should select a different serialization format.
These submit methods represent HTTP POST or the equivalent concept (such as a mail message). The serialized form data is delivered as the message body.
This submit method represents HTTP PUT or the equivalent concept (such as writing to a local file). The serialized form data is delivered as the message body.
This submit method represents HTTP GET or the equivalent concept. The serialized form data is delivered as part of the URI that is requested during the submit process.
This method is not suitable for submission of forms that are intended to change state or cause other actions to take place at the server. See [RFC 2616] for recommended uses of HTTP GET.
The URI is constructed as follows:
The submit URI from the action
attribute is examined. If it does not already contain a ?
(question mark) character, one is appended. If it does already contain a question mark character, then a separator character from the attribute separator
is appended.
The serialized form data is appended to the URI.
No message body is sent with the request.
Table of Contents | Top |