Orbeon Forms User Guide

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:

<filter><filter-name>ops-main-filter</filter-name><filter-class>org.orbeon.oxf.servlet.OPSServletFilter</filter-class><init-param><param-name>oxf.main-processor.name</param-name><param-value>{http://www.orbeon.com/oxf/processors}pipeline</param-value></init-param><init-param><param-name>oxf.main-processor.input.config</param-name><param-value>oxf:/config/filter.xpl</param-value></init-param><init-param><param-name>oxf.error-processor.name</param-name><param-value>{http://www.orbeon.com/oxf/processors}pipeline</param-value></init-param><init-param><param-name>oxf.error-processor.input.config</param-name><param-value>oxf:/config/error.xpl</param-value></init-param></filter><filter-mapping><filter-name>ops-main-filter</filter-name><url-pattern>/xforms-jsp/*</url-pattern></filter-mapping>

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:

<% response.setContentType("application/xhtml+xml"); %><xhtml:html xmlns:ev="http://www.w3.org/2001/xml-events" xmlns:xhtml="http://www.w3.org/1999/xhtml"><xhtml:head><xhtml:title>Guess The Number</xhtml:title><xforms:model><xforms:instance>...</xforms:instance></xforms:model></xhtml:head><xhtml:body><xhtml:h1>My Page</xhtml:h1><xforms:input ref="..."/>...</xhtml:body></xhtml:html>

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:

<xforms:submission id="do-query" method="post" replace="instance" ref="instance('query')" instance="photos" action="/xforms-jsp/flickr-search/service-search.jsp"/>