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

• 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].

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:

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

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.

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

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:

GivenName=Ren%C3%A9

<PersonName title="Mr">
  <GivenName>René</GivenName>
</PersonName>

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:

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