OPS User Guide
- Getting Started
- Core Technologies Reference
- XForms
- Page Flow
- XML Pipelines (XPL)
- OPS Technologies Reference
- Processors Reference
- API Reference
- Integration
|
Page Flow Epilogue
1. Introduction to the Page Flow Epilogue
The OPS 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 OPS
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 OPS 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 OPS 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 OPS. 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 OPS 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.
Note
With OPS 3.0, only the servlet environment is officially supported. The
portlet environment is however used for the examples portal. Please also
refer to this FAQ entry.
This means that for your OPS applications,
epilogue-servlet.xpl is usually the relevant file to
consider.
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:
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):
-
URLs are rewritten.
-
The result is converted to plain HTML according to the XSLT 2.0
and XQuery 1.0 Serialization HTML output method.
-
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):
-
The XSL-FO converter is called. It generates a binary PDF
document.
-
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:
-
The encapsulated binary or text document is sent as per the
semantic described in Non-XML
Documents.
-
Plain XML: in all other cases:
-
The result is converted to plain XML according to the XSLT 2.0
and XQuery 1.0 Serialization XML output method.
-
The plain XML document is sent to the client through HTTP.
You are free to:
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):
-
The standard theme is applied but an XHTML fragment enclosed in a
xhtml:div element is produced instead of a
full-fledged XHTML document.
-
URLs are rewritten.
-
The resulting XHTML document is sent to the portlet container as an XHTML fragment.
-
Plain XML: in all other cases:
-
The XML document is included in a simple XHTML document and formatted into XHTML.
-
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 OPS 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 standard theme includes some default OPS CSS stylesheets and scripts
used by the XForms engine.
7. The Standard Theme
The standard OPS theme is found under the oxf:/config/theme directory.
The entry point of the theme is the theme.xsl stylesheet, called from
the epilogue XPL pipelines.
As documented above, the standard theme is called only for views that generate XHTML
documents. The standard theme does not run, for example, on pseudo-HTML, XSL-FO, or
plain XML documents.
The standard theme does the following:
-
It copies, 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 particualar Javascript script on a page
by page basis, instead of including the script in all the pages of your
application.
-
It adds, under xhtml:head , links to OPS CSS stylesheets and
scripts necessary for the server-side XForms engine, in particular the
following CSS stylesheets:
-
orbeon.css: definitions proprietary to the default theme.
These definitions are likely to be overridden by the user as they
create their own theme.
-
xforms.css: definitions related to XForms controls. These
definitions may be changed by users if they are not happy with the
defaults.
-
It generates, 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 OPS examples). Finally, it looks for the first xhtml:h1
element in the body of the XHTML document.
-
It handles the f:tabs element used by some OPS examples.
-
It processes the source xhtml:body element. This mostly results
in copying the content of the source xhtml:body , with the
following exceptions:
-
Styling is applied to some XHTML forms elements.
-
Attribute in the XHTML namespace are copied but in no namespace.
-
Some special handling is performed for the body of included portlets
so that URLs do not get rewritten in this case. This is useful only
for the examples portal.
-
Any element within the
http://orbeon.org/oxf/xml/formatting namespace, usually
prefixed with f: , is handled by the included
formatting.xsl stylesheet. This stylesheet contains
some useful formatting templates, in particular to format XML and
display tabs. None of the templates in this stylesheet is required
for your OPS application.
The categories above are implemented with sets of xsl:template
elements. Those are clearly delimited in theme.xsl .
You can configure the standard theme at your leisure for your own application. You
typically get started by modifying theme.xsl .
|