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/form-data 11.5 Serialization as application/x-www-form-urlencoded 11.6 The post, form-data-post, and urlencoded-post Submit Methods 11.7 The put Submit Method 11.8 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.
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.
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:
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.
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
.
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,
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
.
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.
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 | "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.
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.
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].
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:
The first part is XML, serialized by the rules at 11.3 Serialization as
application/xml, with the contents of any nodes of
datatypes xsd:base64binary
or
xsd:hexBinary
(or any datatype derived from those)
replaced with an implementation-defined URI.
A Content-Disposition
header of "form-data", with a
name
parameter of "instanceData"
A Content-Type
header of "application/xml", with an
optional charset
parameter
One subsequent part for each node associated with a datatype of
xsd:base64Binary
or xsd:hexBinary
(or
derived datatype) with:
A Content-Disposition
header of "form-data", with
an implementation-defined name
parameter and a
filename
parameter storing the local file name, if
available
A Content-Type
header that represents the media
type of the attachment if known, otherwise
application/octet-stream
A Content-Transfer-Encoding
header of "binary"
A Content-ID
header with an implementation-defined
value matching the URI in the associated instance data node.
Example:
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-
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{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
).
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 |