Using XForms with JSP
1. Introduction
Most of the example applications shipped with Orbeon Forms use the page flow controller and are implemented using other components provided by Orbeon Forms. It is also possible to use the XForms engine without using the page flow controller. The Orbeon Forms web archive (WAR file) comes with example applications implemented in JSP files that reply on the XForms engine and we describe here how you can use just the XForms engine. We illustrate our case using JSPs, but this largely applies to servlets or third party web frameworks implemented as a servlet.
2. Deployment
In the Orbeon Forms web archive (WAR file), all the JSPs are located in a
directory called xforms-jsp
. Under this directory, you will find one
directory per example, for instance: xforms-jsp/guess-the-number
or
xforms-jsp/flickr-search
. Instead of generating plain HTML, JSP files
will generate XHTML + XForms, which is then transformed by Orbeon Forms in
HTML that the browser can understand. This is done with the help of a filter
declared in the web.xml. In the Orbeon Forms web.xml, it is declared as
follows:
The most important part is the url-pattern
defined under
<filter-mapping>
. It reads: /xforms-jsp/*
. This means
that all the data generated by URLs starting with /xforms-jsp/
will be
post-processed by Orbeon Forms. As defined in the web.xml, this
post-processing consists in running the pipeline
oxf:/config/filter.xpl
. This pipleine applies the epilogue on the data
generated by your JSP. The epilogue will transform XHTML + XForms into HTML and in
some cases apply a theme.
3. Generating XHTML and XForms in JSP
The JSP generates XHTML + XForms, like a view linked from the page flow. To be
recognized as XHTML, you need to set the appropriate content type in your JSP by
calling response.setContentType("application/xhtml+xml")
. A JSP will
typically look like:
4. Implementing XForms Services with JSP
The backend of your forms is implemented in what we loosely call "services", that is
URLs that can be used with an <xforms:submission>
. Most of the time,
XML is being posted to the service and XML is returned by the service. Since
services take XML as input and generate XML, XPL is an ideal tool to implement
services. However, your JSP has to set the appropriate content type for the
response: response.setContentType("application/xml")
. Using the dom4j
API, you can create an object that represents the input document with:
Document queryDocument = xmlReader.read(request.getInputStream())
. You
then use this object to gather data about the query sent to your service.
In XForms you reference the service implemented with JSP in the action attribute of
<xforms:submission>
, as usual. For instance: