<?xml version="1.0" encoding="UTF-8"?>
<book><bookinfo><productname>eXist-db – Open Source Native XML Database</productname><title>XForms Introduction</title><author><firstname>James</firstname><surname>Fuller</surname><affiliation><address format="linespecific"><email>jim.fuller at webcomposite.com</email></address></affiliation></author><author><firstname>Wolfgang M.</firstname><surname>Meier</surname></author></bookinfo><chapter><section><title>XForms Support in eXist-db</title><para>eXist-db has broad support for the W3C XForms standard. It offers both a
                client-side (<ulink url="http://www.agencexml.com">XSLTForms</ulink>) and a
                server-side (<ulink url="http://www.betterform.de">betterFORM</ulink>)
                implementation and thus is ideally equipped to build complete applications that use
                XML from front to back. </para><para> However, eXist-db will also work with other XForms processors, such as Orbeon or
                Chiba (the ancestor of betterFORM).</para><para>As eXist-db has 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.</para></section><section><title>Using betterFORM inside of eXist-db</title><para> betterFORM is a server-side W3C XForms 1.1 implementation written in Java that is
                closely integrated within eXist. 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 plugins. betterFORM can also be obtained
                    <ulink url="https://github.com/betterFORM/betterFORM">via Github</ulink> and
                run separately as a standard webapp. It is published under the BSD license. </para><para> 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. </para><para>
                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.
            </para><section><title>Getting started</title><para>betterFORM is activated once you have installed eXist-db on your machine. By
                    default betterFORM is configured to run XForms exclusively from the
                    database.</para><para>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.</para><para>betterFORM can also be configured to listen only for a certain collection in
                    the database or to fetch documents from the filesystem (from a directory below
                    the webapp directory) by changing the filter mapping in
                    webapp/WEB-INF/web.xml.</para><example><title>Configure filtermapping in web.xml</title><programlisting><markup>
&lt;filter-mapping&gt;
    &lt;filter-name&gt;XFormsFilter&lt;/filter-name&gt;
    &lt;url-pattern&gt;/apps/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;
&lt;filter-mapping&gt;
    &lt;filter-name&gt;XFormsFilter&lt;/filter-name&gt;
    &lt;servlet-name&gt;XFormsPostServlet&lt;/servlet-name&gt;
&lt;/filter-mapping&gt;
&lt;filter-mapping&gt;
    &lt;filter-name&gt;XQueryURLRewrite&lt;/filter-name&gt;
    &lt;url-pattern&gt;/*&lt;/url-pattern&gt;
&lt;/filter-mapping&gt;                                                
</markup></programlisting></example></section><section><title>betterFORM Add-ons</title><para>To ease the work with betterFORM it is highly recommended to install the betterFORM dashboard 
                    along with the FeatureExplorer and the demo application. <!-- Before the betterFORM add-ons can be 
                    used, the examples (eXist-db-shipped files) must be installed via the 
                    <ulink url="admin/admin.xql?panel=setup">Admin panel</ulink>--></para><itemizedlist><listitem><para><ulink url="{bf-XForms}/"><emphasis role="bold">Dashboard</emphasis></ulink> 
                            is a simple browser to your database. It allows you to navigate the collections and shows all 
                            the containing files. It has a source code view and allows you to upload a file into the 
                            database and to create collections.</para></listitem><listitem><para><ulink url="{bf-XForms}/reference/FeatureExplorer.xhtml"><emphasis role="bold">FeatureExplorer</emphasis></ulink> 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.</para></listitem>
                    <!--listitem>
                        <para>
                            <ulink url="rest/db/betterform/apps/timetracker/index.xql">
                                <emphasis role="bold">Timetracker</emphasis>
                            </ulink> is a small but complete demo application. It
                            shows a basic <emphasis role="bold">XRX application</emphasis> and can give some 
                            hints for writing your own single-page applications with eXist and betterFORM.</para>
                    </listitem--></itemizedlist>
                <!--para>See the <ulink url="xforms/examples.xml">XForms examples</ulink> page for more betterFORM demo &
                reference forms.</para--></section></section>
        
        
        
        <!-- XSLT FORMS SECTION --><section><title>Using XSLTForms inside of eXist</title><para>eXist directly supports XForms via Alain Couthures' <ulink url="http://www.agencexml.com">XSLTForms</ulink> processor. XSLTForms implements the XForms 
                standard within the browser and is thus easy to integrate. XSLTForms transforms the XForms XML 
                into an XHTML page with JavaScript that can process XForms.</para><section><title>Using XSLTForms inside of eXist</title><para>XSLTForms mainly consists of two components:</para><itemizedlist><listitem><para>the XSLT stylesheet <filename>xsltforms.xsl</filename>, which transforms
                            the XForms markup into HTML and JavaScript understood by the browser</para></listitem><listitem><para>a JavaScript library, <filename>xsltforms.js</filename></para></listitem></itemizedlist><para>The XSLT stylesheet can either be applied <emphasis role="bold">server-side</emphasis> or within the <emphasis role="bold">client</emphasis>,
                    i.e. the browser. To let the browser do the job, all you have to do is to prepend an
                    XSL processing instruction to your XForms document, pointing to the <filename>xsltforms/xsltforms.xsl</filename> stylesheet:</para><example><title>Activate XSLTForms by using XSL processing instruction</title><programlisting><markup>
&lt;?xml-stylesheet href="xsltforms/xsltforms.xsl" type="text/xsl"?&gt;
&lt;html xmlns="http://www.w3.org/1999/xhtml" xmlns:xf="http://www.w3.org/2002/xforms"&gt;
    ...
&lt;/html&gt;
</markup></programlisting></example><para>Please have a look at <ulink url="{xsltforms-demo}/modules/form.xq?form=hello.xhtml">hello.xml</ulink> for a very basic
                    example using client-side transformation.</para><para>When applying the stylesheet server-side, you need to make sure serialization
                    parameters are correctly set. For example, you can apply the stylesheet within an
                    <ulink url="urlrewrite.xml">XQueryURLRewrite</ulink> controller pipeline:</para><example><title>Applying the stylesheet server-side via controller.xql</title><programlisting><markup>
&lt;dispatch xmlns="http://exist.sourceforge.net/NS/exist"&gt;
    &lt;view&gt;
        &lt;forward servlet="XSLTServlet"&gt;
            (: Apply xsltforms.xsl stylesheet :)
        	&lt;set-attribute name="xslt.stylesheet"
        		value="xsltforms/xsltforms.xsl"/&gt;
            &lt;set-attribute name="xslt.output.omit-xml-declaration" value="yes"/&gt;
            &lt;set-attribute name="xslt.output.indent" value="no"/&gt;
            &lt;set-attribute name="xslt.output.media-type" value="text/html"/&gt;
            &lt;set-attribute name="xslt.output.method" value="xhtml"/&gt;
            &lt;set-attribute name="xslt.baseuri" value="xsltforms/"/&gt;
            &lt;set-attribute name="xslt.xsltforms_home" value="webapp/xforms/xsltforms/"/&gt;
        &lt;/forward&gt;
    &lt;/view&gt;
&lt;cache-control cache="yes"/&gt;
&lt;/dispatch&gt;</markup></programlisting></example><para>It is important to set the <option>indent</option> 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).</para></section><section><title>Known Issues</title><para>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 <option>indent="yes"</option>, which leads to problems
                    with the XForms JavaScript library.</para><para>As a workaround, you can append a request parameter <option>?_indent=no</option>
                    to the REST URI. However, the recommended approach would be to use XQueryURLRewrite
                    to properly handle those requests and apply the stylesheet.</para></section></section><section><title>Disabling betterFORM</title><para>Under certain conditions, e.g. when XSLTforms is used,
            the betterFORM engine needs to be disabled. This can be done in two ways:
            
            <itemizedlist><listitem><para>Per request by setting a HTTP attribute: 
                        <synopsis language="xquery">request:set-attribute("betterform.filter.ignoreResponseBody", "true")</synopsis></para></listitem><listitem><para>System global by editing <filename>$EXIST_HOME/webapp/WEB-INF/betterform-config.xml</filename>: 
                        <synopsis language="xml">&lt;property name="filter.ignoreResponseBody" value="false"&gt;</synopsis>
                    change the property <option>filter.ignoreResponseBody</option> to value <option>true</option> and restart
                        eXist-db.
                    </para></listitem></itemizedlist></para></section><section><title>Additional XForms Resources</title><section><title>XForms examples running in eXist</title><itemizedlist><listitem><para>XSLT
                            <ulink url="{xsltforms-demo}/">Examples</ulink></para></listitem><listitem><para>betterFORM 
                            <ulink url="{bf-XForms}/">Examples</ulink></para></listitem></itemizedlist></section><section><title>Mailing Lists</title><itemizedlist><listitem><para><ulink url="https://lists.sourceforge.net/lists/listinfo/xsltforms-support">
                                XSLTForms mailing list</ulink></para></listitem><listitem><para><ulink url="https://lists.sourceforge.net/lists/listinfo/betterform-users">
                                betterFORM Users mailing list</ulink></para></listitem><listitem><para><ulink url="https://lists.sourceforge.net/lists/listinfo/betterform-developer">
                                betterFORM Developers mailing list</ulink></para></listitem></itemizedlist></section><section><title>XForms Specification</title><itemizedlist><listitem><para><ulink url="http://www.w3.org/TR/xforms/">XForms v1.1 
                                (W3C Recommendation)</ulink></para></listitem></itemizedlist></section><section><title>Useful</title><itemizedlist><listitem><para><ulink url="http://betterform.wordpress.com">betterFORM Blog</ulink></para></listitem><listitem><para><ulink url="https://betterform.de/trac">betterFORM Issue Tracking</ulink></para></listitem><listitem><para><ulink url="http://betterform.de">betterFORM homepage</ulink></para></listitem><listitem><para><ulink url="https://github.com/betterFORM/betterFORM">betterFORM@github</ulink> - source code available here</para></listitem><listitem><para><ulink url="http://betterform.de/reports/Firefox-3.0-Mac-OS-X-10.6-ConformanceReport1.1.html">betterFORM coverage</ulink>  of W3C XForms 1.1 Test Suite</para></listitem><listitem><para><ulink url="http://en.wikibooks.org/wiki/XForms">XForms Wikibook</ulink> is a useful place to learn XForms</para></listitem><listitem><para><ulink url="http://en.wikibooks.org/wiki/XRX">XRX Wikibook</ulink> about XML application building</para></listitem><listitem><para><ulink url="http://en.wikibooks.org/wiki/XSLTForms">XSLTForms Wikibook</ulink> provides specific information on XSLTForms</para></listitem><listitem><para><ulink url="http://www.agencexml.com/xforms-tests/testsuite/XForms1.1/Edition1/driverPages/html/">XSLTForms coverage</ulink> of W3C test suite</para></listitem></itemizedlist></section></section></chapter></book>