11 Submit

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.

Issue (multipart-submit-options):

Note that while the multipart/form-data submission method described below is compatible with deployed RFC 2388 servers, it is not possible to write an XForms model that can submit expected data to most existing server-side applications. The Working Group is soliciting implementation and deployment experience to determine whether form submission as multipart/form-data should be backward compatible with deployed RFC 2388 server-side applications and whether a separate method based on multipart/related for submission of the XML instance and upload data should be provided.

Resolution:

None recorded.

11.1 The xforms-submit Event

Submission begins with the default processing 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 Model. From the start of the default processing of xforms-submit, until the completion of default processing for xforms-submit-done or xforms-submit-error, the default processing for event xforms-submit is to terminate immediately.

Otherwise, default processing for this event results in the following steps:

  1. A node from the instance data is selected, based on the attribute ref on element submission. This node and all relevant child nodes are considered for the remainder of the submit process.

  2. All selected instance data is revalidated, according to the rules at 4.3.5 The xforms-revalidate Event. Any invalid instance data stops submit processing after dispatching event xforms-submit-error.

  3. Selected instance data is serialized according to the rules stated at 11.2 Submission Options.

  4. Serialized instance data is submitted using the protocol indicated by the rules stated at 11.2 Submission Options.

  5. 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, when the value of the replace attribute on element submission is "instance", the response is parsed as XML and the internal instance data is replaced with the result, using the same processing as remote instance data retrieved through src, and the xforms-initialize event is dispatched to element model. Submit processing then concludes after dispatching xforms-submit-done.

    • For a success response including a body of a non-XML media type, 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.

11.2 Submission Options

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.

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 "get" application/x-www-form-urlencoded HTTP GET or equivalent
http https file "put" application/xml HTTP PUT 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.

11.3 Serialization as application/xml

This format permits the expression of the instance data as XML that is straightforward to process with off-the-shelf XML processing tools. In addition, this format is capable of submission of binary content.

The steps for serialization are as follows:

  1. 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.

Note that the 8.1.6 The upload Element upload element can bind to instance data nodes with the datatypes xsd:base64Binary, xsd:hexBinary, or xsd:anyURI (or datatypes derived from these). Such nodes are included in the serialized data according to the rules defined in [XML Schema part 2].

11.4 Serialization as multipart/form-data

This format is intended to facilitate the integration of XForms into environments that involve large amounts of binary data, and represents an extension of the [XHTML 1.0] form content type multipart/form-data. This format is especially suitable for the persistence of binary content.

This format follows the rules of all multipart MIME data streams for form data as outlined in [RFC 2388], as follows:

Example:

Example: multipart/form-data
MIME-Version: 1.0
Content-Type: multipart/form-data; boundary=AaB03x
--AaB03x
Content-Disposition: form-data; name="instanceData"
Content-Type: application/xml; charset=UTF-8
<?xml version="1.0?>
<root>
  <text>text</text>
  <binary>cid:attachment1@example.com</binary>
</root>
--AaB03x
  Content-Disposition: form-data; name="attachment1"; filename=image.png
  Content-Type: image/png
  Content-Transfer-Encoding: binary
  Content-ID: <attachment1@example.com>
...Binary data here...
--AaB03x-

11.5 Serialization as application/x-www-form-urlencoded

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:

  1. 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.

  2. Element nodes selected for inclusion are encoded as EltName=value{sep}, where = is a literal character,{sep} is the separator character from the separator attribute on submission, EltName represents the element local name, and value represents the contents of the text node. 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 hexadecimal notation for the octet value and % is a literal character. Line breaks are represented as "CR LF" pairs (i.e., %0D%0A).

  3. All such encodings are concatenated, maintaining document order.

Example:

Example: application/x-www-form-urlencoded
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.

11.6 The post, form-data-post, and urlencoded-post Submit Methods

These submit methods represent HTTP POST or the equivalent concept (such as a mail message). The serialized form data is delivered as the message body.

11.7 The put Submit Method

This submit method represents HTTP PUT or the equivalent concept (such as writing to a local file). The serialized form data is delivered as the message body.

11.8 The get Submit Method

This submit method represents HTTP GET or the equivalent concept. The serialized form data is delivered as part of the URI that is requested during the submit process.

This method is not suitable for submission of forms that are intended to change state or cause other actions to take place at the server. See [RFC 2616] for recommended uses of HTTP GET.

The URI is constructed as follows:

No message body is sent with the request.