XForms Introduction

(2Q19)


eXist-db offers support for the W3C XForms standard. It offers both a client-side (XSLTForms) and a server-side (betterFORM) implementation. With this it is fully equipped to build complete applications that use XML from front to back. However, eXist-db will also work with other XForms processors, such as Orbeon or betterFORM.

As eXist-db also has native support for RESTful interactions, saving XML data is as easy as using a HTTP PUT submission. For more complex tasks, you can submit your XForms instances to an XQuery, post-process them and get the results back into your form. Several examples are referred to below.

Using betterFORM inside of eXist-db

betterFORM is a server-side W3C XForms 1.1 implementation written in Java. It covers 99% of the XForms recommendation and has been extensively tested against the official XForms 1.1 Test Suite. All modern browsers are supported without the need for plug-ins. betterFORM can also be obtained via Github and run separately as a standard webapp. It is published under the BSD license. It is fully integrated in eXist.

With betterFORM, XHTML/XForms documents are transcoded on the server into plain (X)HTML + JavaScript. The resulting page uses an AJAX layer to keep client and server in sync and to provide an attractive user interface without the need of writing a single line of script code.

XForms processing with betterFORM is handled by a servlet filter (XFormsFilter) which nicely integrates with the URL Rewriting feature of eXist. You can use XQuery to generate your XForms markup and process it in a single request.

Getting started

Important:

Warning: the following information is subject to change for eXist-db 5.0 when betterFORM will likely not be available by default any more

betterFORM is activated once you have installed eXist-db on your machine. By default betterFORM is configured to run XForms exclusively from the database.

To execute an XHTML/XForms document it is sufficient to store it into your database (using WebDAV or the admin client) and access it via the REST interface.

betterFORM can also be configured to listen for a certain collection in the database only or to fetch documents from the filesystem (from a directory below the webapp directory). This can be done by changing the filter mapping in etc/webapp/WEB-INF/web.xml:

<filter-mapping>
    <filter-name>XFormsFilter</filter-name>
    <url-pattern>/apps/*</url-pattern>
</filter-mapping>
<filter-mapping>
    <filter-name>XFormsFilter</filter-name>
    <servlet-name>XFormsPostServlet</servlet-name>
</filter-mapping>
<filter-mapping>
    <filter-name>XQueryURLRewrite</filter-name>
    <url-pattern>/*</url-pattern>
</filter-mapping>

betterFORM Add-ons

To ease the work with betterFORM it is highly recommended to install the betterFORM dashboard along with the FeatureExplorer and the demo application.

FeatureExplorer is the live documentation of betterFORM. It is itself an XForms document that offers a navigation menu with links to many sample XForms that show working examples along with relevant links to the XForms Spec. A live CSS reference helps with styling forms by showing all available CSS classes.

Using XSLTForms inside of eXist

eXist directly supports XForms via Alain Couthures' XSLTForms processor. XSLTForms implements the XForms standard within the browser and is therefore easy to integrate. XSLTForms transforms the XForms XML into an XHTML page with JavaScript that can process XForms.

Using XSLTForms inside of eXist

XSLTForms consists of two components:

  • the XSLT stylesheet xsltforms.xsl, which transforms the XForms markup into HTML and JavaScript understood by the browser

  • a JavaScript library, xsltforms.js

The XSLT stylesheet can either be applied server-side or within the client (the browser). To let the browser do the job, all you have to do is prepend an XSL processing instruction to your XForms document, pointing to the xsltforms/xsltforms.xsl stylesheet:

Please have a look at hello.xml for a very basic example using client-side transformation.

When applying the stylesheet server-side, you need to make sure serialization parameters are set correctly. For example, you can apply the stylesheet within an XQueryURLRewrite controller pipeline:

<dispatch xmlns="http://exist.sourceforge.net/NS/exist">
  <view>
    <forward servlet="XSLTServlet">
      (: Apply xsltforms.xsl stylesheet :)
      <set-attribute name="xslt.stylesheet" value="xsltforms/xsltforms.xsl"/>
      <set-attribute name="xslt.output.omit-xml-declaration" value="yes"/>
      <set-attribute name="xslt.output.indent" value="no"/>
      <set-attribute name="xslt.output.media-type" value="text/html"/>
      <set-attribute name="xslt.output.method" value="xhtml"/>
      <set-attribute name="xslt.baseuri" value="xsltforms/"/>
      <set-attribute name="xslt.xsltforms_home" value="webapp/xforms/xsltforms/"/>
    </forward>
  </view>
  <cache-control cache="yes"/>
</dispatch>

It is important to set the indent serialization parameter to no, otherwise you'll get JavaScript errors when viewing the page. Also, if you apply the stylesheet server-side, make sure you remove the processing instruction from the source file, or the browser will try to run the stylesheet as well (which most likely leads to errors).

Known Issues

When you load an XForms document through eXist's REST interface, when the REST server finds an xsl-stylesheet processing instruction in the document, it tries to apply the referenced stylesheet server-side. Unfortunately, the default serialization settings of the REST interface set indent="yes", which leads to problems with the XForms JavaScript library.

As a workaround, you can append a request parameter ?_indent=no to the REST URI. However, the recommended approach would be to use XQueryURLRewrite to properly handle those requests and apply the stylesheet.

Disabling betterFORM

Under certain conditions, for instance when XSLTforms is used, the betterFORM engine needs to be disabled. This can be done in two ways:

  • Per request, by setting an HTTP attribute: 

    request:set-attribute("betterform.filter.ignoreResponseBody", "true")

  • System global, by editing $EXIST_HOME/etc/webapp/WEB-INF/betterform-config.xml: <property name="filter.ignoreResponseBody" value="false">

    Change the value of the property filter.ignoreResponseBody to true and restart eXist-db.

  • By removing the configuration for XFormsFilter in $EXIST_HOME/etc/webapp/WEB-INF/web.xml. By commenting the filter-mapping XForms processing will be disabled. However note that betterFORM still get loaded on the classpath.

  • To fully remove betterFORM from your eXist-db binary, you have to comment the line include.feature.betterform = true in $EXIST_HOME/extensions/build.properties and rebuild the code.

Additional XForms Resources

A collection of further xforms resources to provide help.

XForms examples running in eXist

Mailing Lists

XForms Specification

Useful other links