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.

11.1 The xforms-submit Event

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:

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

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

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

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. (See 3.3.3 The submission Element for additional submission attributes that affect serialization.)

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.

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.

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

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

11.4 Serialization as multipart/related

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

11.5 Serialization as multipart/form-data

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:

Example:

multipart/form-data
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--

11.6 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, 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).

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

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.7 The post, multipart-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.8 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.9 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.