Orbeon Forms User Guide

Page Flow Epilogue

1. Introduction to the Page Flow Epilogue

The Orbeon Forms page flow epilogue is an XPL pipeline executed by the Page Flow Controller (PFC) in order to perform tasks common to all the pages in an Orbeon Forms application. Such tasks include:

  • Look and feel. Adding a common look and feel to all the XHTML pages in an application.

  • Page layout. Adding a page header, footer, or navigation bar.

  • Linking common files. Adding common links to external CSS stylesheets or scripts.

  • Document-aware formatting. Formatting the document differently depending on the type of document produced by a page view, for example XHTML or XSL-FO.

  • Client-aware formatting. Producing XHTML or plain HTML depending on the user agent requesting the page, or different versions of HTML depending on different clients.

  • Server-side XForms processing. The Orbeon Forms server-side XForms engine is hooked up in the epilogue.

  • URL rewriting. Rewriting URLs so that XHTML pages are written independently from their final location.

  • Servlet and portlet support. Formatting pages differently for deployment as a portlet.

  • User-defined configuration. Finally, because the epilogue is a configurable XPL pipeline, there is no limit to the tasks it can acomplish!

Thanks to the page flow epilogue, it is not necessary to duplicate common behavior in all the page views of a given Orbeon Forms application.

2. Basics

2.1. Configuration

The epilogue pipeline is specified with the <epilogue> element in your page flow. By default, the standard epilogue located under oxf:/config/epilogue.xpl is used.

2.2. Execution

The epilogue is executed by the PFC only after a page view executes. This means that for a given execution of a page, the following conditions must be met for the epilogue to execute:

  • The <page> elements has a view attribute.

  • No page result element with a page attribute executes (because in that case, a redirection to another page occurs, and neither model nor view of the current page executes).

2.3. Inputs and Outputs

Type Name Purpose
Input data

When executed, the epilogue XPL pipeline has a data input containing the XML document produced by the page view which just executed. In particular, if the page view is:

  • A static XML file: the data input directly receives the unmodified content of that file.

  • An XSLT template: the data input receives the default output of the XSLT template.

  • An XPL pipeline: the data input receives the content of the data output of that pipeline.

Input instance

The epilogue XPL pipeline receives on its instance input the XML submission performed on the page, if any. The epilogue usually does not use this input.

Input xforms-model

The epilogue XPL pipeline also receives on its xforms-model input the legacy XForms model as specified on the <page> element's xforms attribute. This input is for the private use of the legacy server-side XForms engine in Orbeon Forms. You usually do not have to deal with it.

Output -

The epilogue XPL pipeline does not have any output: the result of the XPL pipeline must be produced using a serializer, usually the HTTP serializer, which serializes the resulting data directly to an HTTP client such as a web browser.

3. The Standard Epilogue: epilogue.xpl

The standard epilogue is found under oxf:/config/epilogue.xpl. It performs the following tasks:

  • XForms processing: it applies server-side XForms processing if needed. If your application does not use the Orbeon Forms built-in XForms engine at all, you can bypass XForms processing.

  • Container type selection: it dispatches to two sub-epilogues, oxf:/config/epilogue-servlet.xpl and oxf:/config/epilogue-portlet.xpl, depending on whether the page is running in a servlet or portlet environment. If your application does not use portlets at all, you can bypass this choice.

4. The Servlet Epilogue: epilogue-servlet.xpl

4.1. Introduction

oxf:/config/epilogue-servlet.xpl is the epilogue file you are the most likely to configure.

4.2. Inputs and Outputs

Type Name Purpose
Input xformed-data

This XPL pipeline receives on this input the XML document produced by the page view and then transformed by server-side XForms processing. This means that if the page view produces an XHTML + XForms document, the document received by epilogue-servlet.xpl on its xformed-data is already transformed by the server-sided XForms engine into XHTML.

Input data

This XPL pipeline also receives on its data input the raw XML document produced by the page view. This is the same XML document received by epilogue.xpl.

Output -

This XPL pipeline does not have any output: the result of the XPL pipeline must be produced using a serializer, usually the HTTP serializer, which serializes the resulting data directly to an HTTP client such as a web browser.

4.3. Processing Logic

epilogue-servlet.xpl performs different tasks depending on the input XML document.

  • XHTML: for XHTML documents, identified with a root element of xhtml:html (in the XHTML namespace), two options are proposed:

    • Option 1: conversion from XHTML to HTML.

      1. The theme is applied.

      2. URLs are rewritten.

      3. XHTML is converted to HTML by moving the XHTML elements to no namespace and by removing their prefixes, if any.

      4. The result is converted to plain HTML according to the XSLT 2.0 and XQuery 1.0 Serialization HTML output method.

      5. The resulting HTML document is sent to the client through HTTP.

    • Option 2: browser detection with native XHTML output option. This option is commented out so that the default is just to send plain HTML to the client.

      1. The theme is applied.

      2. URLs are rewritten.

      3. If the client tells the server, with an accept header, that it accepts XHTML documents:

        1. XHTML elements are stripped from their prefixes, if any, but they are left in the XHTML namespace. This makes the XHTML more compatible with certain non-XHTML-aware user agents.

        2. The result is converted to serialized XHTML according to the XSLT 2.0 and XQuery 1.0 Serialization XHTML output method.

      4. Otherwise:

        1. XHTML is converted to HTML by moving the XHTML elements to no namespace and by removing their prefixes, if any.

        2. The result is converted to plain HTML according to the XSLT 2.0 and XQuery 1.0 Serialization HTML output method.

      5. The resulting document is sent to the client through HTTP.

    Note

    You can easily construct variations on those options, such as sending XHTML only to certain user agents, or always sending XHTML.

  • Pseudo-HTML: for pseudo-HTML documents, identified with a root element of html (in lowercase and in no namespace):

    1. URLs are rewritten.

    2. The result is converted to plain HTML according to the XSLT 2.0 and XQuery 1.0 Serialization HTML output method.

    3. The resulting HTML document is sent to the client through HTTP.

    Note

    No theme stylesheet is applied in this case. You are encouraged to write XHTML and use a single theme which matches against XHTML elements only, leaving possible conversion to HTML for subsequent steps. It is however possible to apply a theme stylesheet in this case as well by inserting a call to the XSLT processor in this case as well.

    It should also be noted that URL rewriting only applies to lowercase HTML elements. URL rewriting for pseudo-HTML documents is deprecated.

  • XSL-FO: if the document is an XSL-FO document, identified with a root element of fo:root (in the XSL-FO namespace):

    1. The XSL-FO converter is called. It generates a binary PDF document.

    2. The resulting PDF document is sent to the client through HTTP.

  • Binary and text documents: if the document root is document and has an xsi:type attribute:

    1. The encapsulated binary or text document is sent as per the semantic described in Non-XML Documents.

  • Plain XML: in all other cases:

    1. The result is converted to plain XML according to the XSLT 2.0 and XQuery 1.0 Serialization XML output method.

    2. The plain XML document is sent to the client through HTTP.

You are free to:

  • Modify the support for the document formats handled by default.

  • Add support for his own document formats by adding p:when branches to the p:choose statement.

5. The Portlet Epilogue: epilogue-portlet.xpl

5.1. Introduction

oxf:/config/epilogue-portlet.xpl is the epilogue file used for the examples portal. You usually do not have to worry about this XPL pipeline unless you add new examples, or unless you deploy as a JSR-168 portlet.

5.2. Inputs and Outputs

epilogue-portlet.xpl has the same inputs as the epilogue-servlet.xpl epilogue.

5.3. Processing Logic

epilogue-portlet.xpl performs different tasks depending on the input XML document.

  • XHTML: for XHTML documents, identified with a root element of xhtml:html (in the XHTML namespace):

    1. The theme is applied but an XHTML fragment enclosed in a xhtml:div element is produced instead of a full-fledged XHTML document.

    2. URLs are rewritten.

    3. The resulting XHTML document is sent to the portlet container as an XHTML fragment.

  • Plain XML: in all other cases:

    1. The XML document is included in a simple XHTML document and formatted into XHTML.

    2. The resulting XHTML document then goes through the same steps as a regular XHTML document..

You are free to:

  • Modify the support for the document formats handled by default.

  • Add support for his own document formats by adding p:when branches to the p:choose statement. In a portlet environment, it is important to remember that a portlet can usually only output a markup fragment such as HTML or XML, but no associated resources such as images, PDF files, etc.

6. XForms Processing

The Orbeon Forms built-in XForms engine allows you to write not only raw XHTML, but also supports XForms 1.0. To achieve this, the XForms engine rewrites XHTML + XForms into XHTML + JavaScript + CSS. This transformation also occurs in the epilogue, as mentioned above.

While it is not necessary to know in details the work performed by the XForms engine, it is important to know that:

  • XForms processing is triggered when either a legacy XForms model is found on the xforms-model input of the epilogue, or when an XForms model is found under /xhtml:html/xhtml:head.

  • The result of XForms processing is that all the elements in the XForms namespace are removed, including the XForms models you may have under xhtml:head.

  • Instead of XForms elements, you will find XHTML elements. Those elements may use some CSS classes defined in xforms.css.

  • The theme includes some default Orbeon Forms CSS stylesheets and copies over JavaScript and CSS resources produced by the XForms engine.

7. Theming

As documented above, the theme stylesheet is called only for views that generate XHTML documents. The theme does not run, for example, on pseudo-HTML, XSL-FO, or plain XML documents. However, you can still produce HTML documents and use a theme stylesheet, since the epilogue is able to convert XHTML to HTML.

Orbeon Forms comes with two stylesheets: theme-plain.xsl and theme-examples.xsl. theme-plain.xsl only makes minor adjustments to your page view. You can simplify it further, or expand it. theme-examples.xsl is the theme for the built-in Orbeon Forms example applications. It decorates pages views with a list of available example applications, and provides a mechanism for viewing application source code.

Orbeon Forms theme resources are found under the oxf:/config/theme directory. They are referred to, directly or indirectly (through CSS) from the theme-*.xsl stylesheets called from the epilogue XPL pipelines. The following should be noted:

  • Theme stylesheets copy, under xhtml:head, the xhtml:meta, xhtml:link, xhtml:style, and xhtml:script elements from the source XHTML document. This allows you for example to link to a particular JavaScript script on a page by page basis, instead of including the script in all the pages of your application.

  • Theme stylesheets add, under xhtml:head, a link to the Orbeon Forms CSS stylesheet:

    • orbeon.css. This contains definitions proprietary to the default theme. You will probably not use this CSS stylesheet in your own theme stylesheet.

  • When XForms is used, theme stylesheets indirectly add, under xhtml:head, a link to the Orbeon Forms XForms resources, including:

    • xforms.css. These are definitions related to XForms controls. These definitions may be changed by users if they are not happy with the defaults.

    • xforms-widgets.css. These are definitions related to XForms pseudo-controls created by the xforms-widgets.xsl stylesheet. These definitions may be changed by users if they are not happy with the defaults.

    • Other XForms CSS and JavaScript resources. These are usually added by the XForms engine as needed.

  • Theme stylesheets generate, under xhtml:head, an xhtml:title element, first by looking in the XHTML document if present. If not found, it looks for a f:example-header element (this element is used by some Orbeon Forms examples). Finally, it looks for the first xhtml:h1 element in the body of the XHTML document.

  • Theme stylesheets processes the source xhtml:body element. This mostly results in copying the content of the source xhtml:body, with the exception that attribute in the XHTML namespace are copied but in no namespace.

You can configure the standard theme at your leisure for your own application. You typically get started by modifying theme-plain.xsl and/or referring to your own stylesheet from the epilogue pipeline.