NOTE: On <xforms:instance>, the attribute is statically-defined. On <xforms:submission>, it is an AVT and can therefore be dynamic.
HTTP headers forwarding
HTTP requests initiated by <xforms:submission> and <xforms:instance> can automatically forward incoming HTTP headers. Two properties are looked at in order:
- The local, XForms-specific oxf.xforms.forward-submission-headers property
- The global Orbeon Forms oxf.http.forward-headers property (used only as a default if the XForms property is not set)
Both properties contain a space-separated list of header names to forward:
<property
as="xs:string"
name="oxf.xforms.forward-submission-headers"
value="Orbeon-Client Authorization SM_USER"/>
oxf.xforms.forward-submission-headers can also be set on a per-page basis on your first model element:
<xforms:model
xxforms:forward-submission-headers="Orbeon-Client Authorization SM_USER">
...
</xforms:model>
Whenever an HTTP request must be performed, the XForms engine looks at this list of header names and it forwards the header value if the following conditions are met:
- There is an incoming header with that name, i.e. either the HTTP request causing the XForms page to load or the XForms Ajax request to run contains that header.
- There is no author-specifed header with the same name in an
<xforms:header> element within <xforms:submission>.
Forwarding the Authorization or other authentication-related headers can be useful to propagate authentication credentials to other services.
NOTE: The Authorization header is treated specially: if a username is specified on the submission with xxforms:username, then this header is never forward.
SECURITY NOTE: Forwarding authentication-related headers may cause a security risks when communicated with non-trusted servers. Use carefully!
Loading indicator
When an <xforms:submission> with replace="all" is executed, in general, the browser will load another page. While this happens, the loading indicator, by default shown in red at the top right of the window, is displayed. However, when the browser is served not a web page but say a ZIP file, the browser might ask you in you want to download it, and then stay in the current page. When this happens, the loading indicator does not go away.
In those cases where you know that the target page does not replace the current page, you can prevent the loading indicator from being displayed by adding the xxforms:show-progress="false"attribute:
<xforms:submission xxforms:show-progress="false"/>
Similarly the xxforms:show-progress="false" attribute can be used with the xforms:load action:
<xforms:load xxforms:show-progress="false"/>
Specifying an HTML target window or frame with the xxforms:target attribute
You can use the xxforms:target attribute on both <xforms:submission> and xforms:load. It behaves just like the HTML target attribute. When used on <xforms:submission>, it only makes sense to use this attribute when you have replace="all".
Replacing other instances with the xxforms:instance attribute
On an <xforms:submission> element with replace="instance", the optional instance attribute specifies a destination instance for the result. That attribute is processed like the instance()function, which means that the instance specified must be in the current model.
The xxforms:instance extension attribute can be use instead of the standard instance attribute. It works like instance, except that the instance is searched globally among all models.xxforms:instance is to the instance attribute what the xxforms:instance() function is to the standard instance() function.
<xforms:submission id="my-submission" method="post" resource="http://example.org/"
replace="instance" xxforms:instance="my-instance"/>
Enabling XInclude processing with the xxforms:xinclude attribute
On an <xforms:submission> element with replace="instance", the optional xxforms:xinclude attribute specifies whether XInclude processing should be performed on the XML document returned, before storing it into the destination instance. The default is false.
<xforms:submission id="my-submission" method="post" resource="http://example.org/"
replace="instance" xxforms:xinclude="true"/>
Preventing recalculation before a submission
[SINCE: 2010-06-16]
XForms 1.1 provides two attributes to control pre-submission tasks:
validate: "indicates whether or not the data validation checks of the submission are performed".relevant: "indicates whether or not the relevance pruning of the submission is performed"
Orbeon Forms adds the following attribute:
xxforms:calculate: indicates whether or not recalculation must take place
The default value is "false" if the value of serialization is "none" and "true" otherwise.
The purpose of the attribute is to improve performance when multiple submission are called serially. The form author can this way completely prevent the rebuild, recalculate and revalidate flags from being checked before submitting data:
<xforms:submission ref="instance()" method="post"
validate="false" relevant="false" xxforms:calculate="false" .../>
WARNING: This attribute must be used with caution, as using it might mean you submit information that is out of date.
Here is how Orbeon Forms performs the rebuild, recalculate and revalidate operations before a submission:
- Perform rebuild if:
- the deferred flag for
rebuild is set
- and the data to submit belongs to an instance (as opposed to a non-instance XML node)
- and either of the effective value of the validate, relevant or xxforms:calculate attributes is true
- Perform recalculate if:
- the deferred flag for
recalculate is set
- and the data to submit belongs to an instance (as opposed to a non-instance XML node)
- and either of the effective value of the relevant or xxforms:calculate attributes is true
- Perform revalidate if:
- the deferred flag for
revalidate is set
- and the data to submit belongs to an instance (as opposed to a non-instance XML node)
- and the final effective of the validate attribute is true
The "effective value" for the validate, relevant and xxforms:calculate attributes is the value after considering:
- each attribute's default value
- resolution of AVTs
Submitting non-XML content
Submitting text content
<xforms:instance id="instance">
<text>
This contains some text. The<b>string value</b>of the document will be sent
</text>
</xforms:instance>
...
<xforms:submission id="save-submission" ref="instance()" method="post" serialization="text/plain" replace="none"
resource="http://example.com/foo.text"/>
...
Submitting HTML or XHTML content
<xforms:instance id="instance">
<xforms:submission id="save-submission" ref="instance()" method="post" serialization="text/html" replace="none"
resource="http://example.com/foo.html"/>
Submitting binary content
XForms 1.1 does not explicitly support submitting binary content, but does not prohibit it either. Orbeon Forms supports sending the content of a binary resource specified by a URI. Such resources are easily obtained with <xforms:upload>, for example. To perform a binary submission:
- The
post or put method is required. - You must use application/octet-stream as
serialization attribute. - The node referred to by the submission must be of type
xs:anyURI. - [SINCE 2012-05-30] Relative URLs are supported and resolved as service URLs against the
<xforms:submission> element.
<xforms:instance id="attachment">
file:/Users/jdoe/Applications/apache-tomcat-5.5.20/temp/xforms_upload_30877.tmp
<xforms:bind nodeset="instance('attachment')" type="xs:anyURI"/>
<xforms:submission id="save-submission" ref="instance('attachment')" method="put" serialization="application/octet-stream"
replace="none" resource="http://example.com/foo.bin"/>
Alternatively, you can set the type information using the xsi:type attribute:
<xforms:instance id="attachment">
<attachment xsi:type="xs:anyURI">
file:/Users/jdoe/Applications/apache-tomcat-5.5.20/temp/xforms_upload_30877.tmp
Local submissions
Rationale
XForms pages can make heavy use of services through the use of <xforms:submission>.
A service is primarily identified by a URL.
-
Sometimes a service is remote (on a machine other than the machine on which Orbeon Forms is
installed), in which case the URL is necessarily an absolute URL starting with
http:// or https://.
-
But often services are implemented within Orbeon Forms itself, not only on the same server
but within the same web application. In the case of such local submission, Orbeon Forms
provides a special optimized mode which has the following benefits:
-
No actual HTTP connection is initiated, so performance is likely to be better.
-
There is no need to deal with absolute URLs such as
http://localhost:8080, especially when proxies or firewalls are in
place.
For more information, see also the configuration properties related to submissions.
Enabling local submissions
Orbeon Forms performs a local submission if:
-
The URL specified is not a absolute, i.e. does not start with http:// or
https://.
-
The submission is not asynchronous. (This restriction may be lifted in the future.)
-
In a servlet environment:
-
The submission has replace="all" (which is the default if no
replace attribute is specified) and the
oxf.xforms.local-submission-forward property is set to
true (which is the default).
-
The submission has replace="instance", replace="text" or
replace="none" and the
oxf.xforms.local-submission-include property is set to
true (the default is false).
-
In a portlet environment:
NOTE: The portlet logic above is likely to be revised in the future. Also note that in the case of
optimized submissions within portlets, requests are made directly to the Orbeon Forms
portlet and do not use servlet forward/include.
Context resolution
In a servlet environment, paths are resolved as follows:
-
If f:url-norewrite is not set to true, the resource is resolved
against the current servlet context.
-
If f:url-norewrite is set to true, the resource is resolved
against the servlet container root. This allows accessing other web applications within the
same servlet container.
Say your application is under context /orbeon, and you have a second web application
under context /foo:
<!-- This submission calls /orbeon/bar -->
<xforms:submission replace="all" method="post" resource="/bar"/>
<!-- This submission calls /foo/bar -->
<xforms:submission replace="all" method="post" resource="/foo/bar" f:url-norewrite="true"/>
Limitations of includes
With:
replace="instance"replace="text"replace="none"
optimized submission are implemented using the servlet container's include mechanism, which does not automatically build path information for the included resource.
In this case, Orbeon Forms is therefore unable to provide proper "servlet path" and "path info"
information. Orbeon Forms handles this situation in the following way:
-
A blank ("") "servlet path" is provided.
-
The "path info" contains the entire path provided, instead of the path following the servlet
path.
This may cause some application which rely on the "servlet path" information to behave incorrectly.
For example, consider the eXist REST servlet:
-
It is mounted as /exist/rest within Orbeon Forms.
-
eXist (quite properly) expects any path following /exist/rest to be a path
into the database, e.g. /exist/rest/db/orbeon produces a path called
/db/orbeon.
-
If Orbeon Forms calls the eXist REST servlet with a blank servlet path and a path info
containing /exist/rest/db/orbeon, eXist obviously obtains an incorrect database
path.
NOTE: In short you must be careful when using local includes. The good news is that if you are using
servlets which do not depend on path information as explained above, or if you have control over the
implementation of the services you are calling, then you can most likely work around this limitation.
Local forwards are not subject to that limitation.
The "echo:" URL scheme
[SINCE: 2011-03-29]
Submissions support a special "echo:" URL scheme which returns the data that was submitted. This is useful for tests.
NOTE: Previously, the undocumented "test:" scheme had the same effect. It is still supported for backward compatibility.
Example:
<xf:submission
id="my-submission"
ref="instance()"
method="post" action="echo:" replace="instance" instance="result"/>
