Page Flow Epilogue

Contents

  1. 1 Introduction to the Page Flow Epilogue
  2. 2 Basics
    1. 2.1 Configuration and properties
    2. 2.2 Execution
    3. 2.3 Inputs and outputs
  3. 3 The standard epilogue: epilogue.xpl
  4. 4 The servlet epilogue: epilogue-servlet.xpl
    1. 4.1 Introduction
    2. 4.2 Inputs and outputs
    3. 4.3 Processing logic
    4. 4.4 Document type
  5. 5 The portlet epilogue: epilogue-portlet.xpl
    1. 5.1 Introduction
    2. 5.2 Inputs and outputs
    3. 5.3 Processing logic
  6. 6 XForms processing
  7. 7 Theming

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.

Basics

Configuration and properties

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.

The epilogue can be used to configured with a series of properties.

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).

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.

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.

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.

The servlet epilogue: epilogue-servlet.xpl

Introduction

oxf:/config/epilogue-servlet.xpl is the epilogue file you are the most likely to configure. This file is packaged inside orbeon-resources-private.jar. To modify it, extract it from orbeon-resources-private.jar and copy it to WEB-INF/resources/config. Your version of the file in WEB-INF/resources/config will take precedence over the one in orbeon-resources-private.jar.


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.


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:
  • Pseudo-HTML: for pseudo-HTML documents, identified with a root element of html (in lowercase and in no namespace):
  • XSL-FO: if the document is an XSL-FO document, identified with a root element of fo:root (in the XSL-FO namespace):
  • Binary and text documents: if the document root is document and has an xsi:type attribute:
  • Plain XML: in all other cases:

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.

Document type

By default, Orbeon Forms use the following document type for HTML sent to the client: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">. As a result, browsers will be in strict or almost-strict mode, which ensures greater compatility between browsers. However, should you want to change this document, you can do so by editing the epilogue-servlet.xpl (for more on how to edit this file see the introduction above). Look for <public-doctype>-//W3C//DTD HTML 4.01//EN</public-doctype> inside an oxf:identity processor (skip the other occurrences inside oxf:html-converter processors).

The portlet epilogue: epilogue-portlet.xpl

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.

Inputs and outputs

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

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):
  • Plain XML: in all other cases:

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.

XForms processing

The Orbeon Forms built-in XForms engine allows you to write not only raw XHTML, but also supports XForms 1.1. 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 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.

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:
  • When XForms is used, theme stylesheets indirectly add, under xhtml:head, a link to the Orbeon Forms XForms resources, including:
  • 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 theme at your leisure for your own application. You typically get started by copying theme-plain.xsl to a new file and changing the oxf.epilogue.theme property to refer to that file.

Comments