xforms:submission

Specifies which data to submit, and how to submit it.

Submissions are defined by a set of attributes on an <xforms:submission> tag. This allows you to control the submission, setting where it goes, how it is formatted, and so on. The <xforms:submission> tag must be placed inside the <xforms:model> tag, but outside of the data instances contained in the model.

Syntax

  <xforms:submission id="name" single_node_binding 
      method="method" mediatype="media" action="URL" 
      resource="URL" includenamespaceprefixes="prefixes" 
      replace="replace" instance="instanceID" targetref="targetXPath"
      serialization="serializeMethod" relevant="relevance" 
      validate="validation" separator="separator" xfdl:updatemodel="update">
    <xforms:resource value="XPathForURL">dynamicURL</xforms:resource>
    <xforms:method value="XPathForMethod">method</xforms:method>
    <xforms:header nodeset="XPathForHeader" combine="combineRule">
      <name value="">NameOfHeader</name>
      <value value="">ValueOfHeader</value>
      ...
    </xforms:header>
  </xforms:submission>

Table 1. xforms:submission parameters
Parameter	Type	Description
name	string	An arbitrary name that you assign to the submission. All names assigned to id attributes must be globally unique within the form.
single_node_binding	string	Sets the root node for the submission. This node and all of its children are submitted. The node must be part of the same model in which the xforms:submission appears. This binding is optional. If the submission does not contain a single node binding, then the default instance of the default data model is sent. For more information about single node bindings, see Single node binding.
method	string	Sets the HTTP method that is used for the submission. Set to one of the following: post — serializes the data in the XForms model as XML. get — serializes the data in the XForms model using URL encoding (x-www-form-urlencoded). put — serializes the data in the XForms model as XML. No response is expected (this is generally used with a file URL). delete — serializes the data in the XForms model using URL encoding (x-www-form-urlencoded). The method must be specified by either the method attribute of the submission, or by the method element. If specified in both places, the method element overrides the method attribute.
media	MIME type	Optional. Overrides the default MIME type for the submission. If this is not set, the submission defaults to application/xml
URL	URL	Optional. The URL to which the data is submitted. This must be a complete URL, and may use any of the following schemes: http, https, or file. Note that the action attribute is deprecated in XForms 1.1 in favour of the resource attribute.
prefixes	string	A space separated list of namespace prefixes. The definitions for these namespaces are included with the root node when the data is submitted. If no prefixes are listed, all prefixes inherited by the root node are included. To include only the default namespace, use #default.
replace	string	Determines how the return data is handled. Set to one of the following: all — replaces the entire form with the returned data. instance — replaces the entire instance. text — replaces the content of the target node. none — ignore the returned data.
instanceID	string	Optional. The ID of the instance to replace. If not provided, defaults to the instance that contained the submission data.
targetXPath	string	Optional. An XPath expression that indicates the target node for data replacement. If the replace parameter is instance, the entire target node is replaced by the submission result. If the replace parameter is text, then the content of the target node is replaced by the submission result. The targetref is ignored for all other values of the replace parameter.
serializeMethod	string	Optional. Controls how and whether to serialize instance data. If present, must be none.
relevance	string	Optional. Controls whether or not non-relevant instance data is submitted. If present, must be one of: true — non-relevant instance data is excluded from the submission false — non-relevant instance data is included in the submission The default is false if serializeMethod is none, otherwise the default is true.
validation	string	Optional. Controls whether or not instance data is validated before submission. If present, must be one of: true — instance data is validated false — instance data is not validated The default is false if serializeMethod is none, otherwise the default is true.
separator	string	Optional. Specifies the separator between key/value pairs in the submission URL. If present, must be `";"` or `"&"`. The default is `"&"`.
update	string	Optional. Specifies when you want the XForms model to be updated after a submission. Possible values are true, false, and defer. true — This is the default. The relevant model update is performed immediately following the data replacement false — No changes are made to the model as a result of the submission defer — Defers updates until the top-level calling action is completed.
XPathForMethod	expression	Optional. An XPath expression that constructs the submission method from one or more instance data nodes. The method must be one of post, get, put, or delete. The method must be specified by either the method attribute of the submission, or by the method element. If specified in both places, the method element overrides the method attribute.
XPathForURL	expression	Optional. An XPath expression that constructs the submission URL using the content from one or more instance data nodes. The URL in this element must be complete and must use one of the following schemes: http, https, or file. If used, the URL found in the specified element is used. If no URL is found, then the URL provided by the resource attribute of the submission element is used. Note: You cannot submit the file to any of the following locations: the “Program Files” directory. the system drive or `Windows system` directories. temporary directories. a folder outside of the directory subtree that contains the originating file.
dynamicURL	string	Optional. A URL for the submission. The URL must be complete and must use one of the following schemes: http, https, or file. If used, the URL found in the specified element is used. If no URL is found, then the URL provided by the value attribute of the resource element is used. Note: You cannot submit the file to any of the following locations: the “Program Files” directory. the system drive or `Windows system` directories. temporary directories. a folder outside of the directory subtree that contains the originating file.
XPathForHeader	expression	Optional. An XPath expression that returns one or more nodes. A header entry is generated for each node that is returned.
combineRule	string	Optional. Controls how the headers that are defined by this element are combined with other headers. If present, must be one of append, prepend, or replace. The default is append.
NameOfHeader	string	Required. Specifies the name of the header that is presented to the submission protocol.
ValueOfHeader	string	Required.

Available in

form global

Example

This example shows a small XForms data model that contains the name, age, and birth date of a person. The model contains an xforms:submission that uses the HTTP post method to submit the entire instance to a script running on a server.

<?xml version="1.0"?>
<XFDL xmlns="http://www.ibm.com/xmlns/prod/XFDL/8.0"
  xmlns:xfdl="http://www.ibm.com/xmlns/prod/XFDL/8.0"
  xmlns:xforms="http://www.w3.org/2002/xforms">
  <globalpage sid="global">
     <global sid="global">
        <xformsmodels xmlns="">
           <xforms:model>
              <xforms:instance>
                 <person>
                    <name></name>
                    <age></age>
                    <birthdate></birthdate>
                 </person>
              </xforms:instance>
              <xforms:bind nodeset="age" type="xsd:integer"/>
              <xforms:bind nodeset="birthdate" type="xsd:date"/>
              <xforms:submission id="submitTest" method="post"
                 resource="http://www.example.com/cgi-bin/people"
                 includenamespaceprefixes=""/>
           </xforms:model>
        </xformsmodels>
     </global>
  </globalpage>

Usage details

There are two ways to trigger a submission:
- Create a submission button using the xforms:submit option. For more information, refer to xforms:submit.
- Create a submission button using an xforms:trigger and one or more xforms:send actions. For more information, refer to XForms actions.
The <xforms:submission> portion of the xformsmodels option can trigger XForms actions using the xforms-submit, xforms-submit-done, and xforms-submit-error events. For more information, refer to XForms event handlers.
Action handlers for xforms-submit-done and xforms-submit-error are supported only for replace=instance and replace=none type submissions
For SOAP submissions, use a method of post and the following MIME type in the mediatype attribute:
```
application/soap+xml; action=Some Action;[charset=x]
```
where you provide the name of the action and optionally supply a character set.
If the root element of the submitted data is in the SOAP 1.1 namespace (http://schemas.xmlsoap.org/soap/envelope/) then the content-type used is text/xml rather than the given mediatype, the charset parameter is preserved, and the SOAP Action header is added with a value of Some Action.
You can create an XForms version of Smartfill by creating submissions that save and load instance data to a file on the user's computer. To create a "save user data" submission, you must include a submission id, a resource that points to the xml file that will contain the data, a "put" method to place the data in the file, a reference to the instance containing the data, and an instance replace of none. For example:
```
<xforms:submission id="saveName" resource="file:savedata1.xml" method="put"
                   ref="name" replace="none"/>
```
To create a "load user data" submission, you must include a submission id, a resource that points to the xml file that contains the user data, a “get” method to load the data into the data model, a reference to the instance that will contain the user data, and replace the entire instance. Furthermore, to ensure that the new data is displayed in the form, you must create an xforms:setvalue action. For example:
```
<xforms:submission id="loadName" resource="file:savedata1.xml" instance="name"
                   method="get" replace="instance">
   <xforms:setvalue ref="name" value="instance('name')" ev:event="xforms-submit-done"/>
</xforms:submission>
```