A page flow is usually defined in a file called page-flow.xml stored at the root of your Orbeon Forms resources. This XML file has a root element called <config>, which has to be within the http://www.orbeon.com/oxf/controller namespace. All the XML elements in a page flow have to be in that namespace unless stated otherwise. You start a page flow document as follows:

You can configure the location of the page flow configuration file in the web application's web.xml file. See Packaging and Deployment for more information. In most cases, it is not necessary to change the default name and location.

Most web applications consist of a set of pages, identified to clients (web browsers) by a certain URL, for example:

http://www.orbeon.org/myapp/report/detail?first=12&count=10#middle

In most cases the URL can be split as follows:

• http://www.orbeon.org/ identifies the web or application server hosting the application.

• /myapp may optionally identify the particular web application running on that server. Whils this part of the URL path is not mandatory, its use is encouraged on Java application servers, where it is called the context path.

• /report/detail identifies the particular page within the web application. Such a path may be "flat", or hierarchical, separated with "/" (slashes).

• ?first=12&count=10 specifies an optional query string which identifies zero or more parameters passed to that page. Each parameter has a value. This example has two parameters: the first one is called first with value 12, and the second one is called count with value 10.

• #middle is an optional fragment identifier identifying a section of the resulting page. Usually, this part of the URL is not handled by the web application, instead the web browser uses it to scroll to a section of the resulting page identified by this identifier (here middle).

For a particular web application, what usually matters in order to identify a particular page is the path within the URL under the context path, here /report/detail. Therefore, in an Orbeon Forms page flow, each page is identified with a unique path information. You declare a minimal page like this:

Other pages may be declared as follows:

A <page> element can have an optional id attribute useful for navigating between pages.

Creating a static page with Orbeon Forms is quite easy: just add a view attribute on a <page> element which points to an XHTML file:

Here, using the oxf: protocol means that the file is searched through the Orbeon Forms resource manager sandbox. It is also possible to use relative paths, for example:

The path is relative to the location of the page flow configuration file where the <page> element is contained. Here is an example of the content of report-detail-view.xhtml:

It is recommended to to use XHTML and to put all the elements in the XHTML namespace, http://www.w3.org/1999/xhtml. This can be done by using default namespace declaration on the root element (xmlns="http://www.w3.org/1999/xhtml) or by mapping the namespace to a prefix such as xhtml and to use that prefix throughout the document, as shown above. The file must contain well-formed XML: just using a legacy HTML file won't work without some adjustments, usually minor.

Instead of using a static XHTML page, you can also use an XSLT template to generate a dynamic page. This allows using XSLT constructs mixed with XHTML constructs, for example:

When XSLT templates are used, it is recommended to use the .xsl extension:

In the MVC architecture, the page logic is implemented by a page model, and the page layout by a page view. The MVC architecture promotes the separation of model, view and controller:

• The page model is responsible for calling or implementing the business logic. It is in charge of gathering the information to be displayed by the page view.

• The page view is in charge of presenting to the user the information gathered by the page model. The page view usually produces XHTML and XForms, but it can also produce other results such as XSL-FO, RSS, etc. Handling of the output of the view is done in the page flow epilogue, which by default knows how to handle XHTML, XForms, XSL-FO, and custom XML document.

• The controller is responsible for dispatching a request from a client such as a web browser to the appropriate page model and view and connecting the model with the view. In Orbeon Forms, the controller is the PFC itself, which is configured with a page flow.

For instance, a news page can use a page model to retrieve the list of headlines and then pass this information as an XML document to a page view. The view produces an XHTML page by creating a table with the content of the headlines, adding a logo at the top of the page, a copyright notice at the bottom, etc.

Each PFC <page> element therefore supports attributes defining what page model and page view must be used:

• The model attribute is a URL refering to an XPL pipeline (optionally an XSLT stylesheet or a static XML file) implementing the model.

• The view attribute is a URL refering to an XSLT stylesheet (optionally an XPL pipeline or a static XML file) implementing the view.

The model passes data to the view as an XML document, as follows:

• XPL model. The model document must be generated by the XPL pipeline on an output named data.

• XSLT model. The model document is the default output of the XSLT transformation.

• Static XML model. The model document is the static XML document specified.

• XPL view. The model document is available on an input named data.

• XSLT view. The model document is available as the default input of the XSLT transformation.

• Static XML view. In this case, no model document is available to the view.

A model XPL pipeline and an XSLT view can be declared as follows for the /report/detail page:

Here, the location of the model and view definitions mirrors the path of the page, and file names repeat the directory path, so that files can be searched easier. It is up to the developer to choose a naming convention, but it is recommended to follow a consistent naming structure. Other possibilities include:

or:

A typical XSLT view can extract model data passed to it automatically by the PFC on its default input, for example, if the model generates a document containing the following:

Then an XSLT view can display the content of the <name> element as follows:

A page built out of a model and a view can retrieve information from a data source and format it. However, this is not enough to make a page which can use parameters submitted by a client to configure what data is being presented, or how it is presented.

The Orbeon Forms PFC uses the concept of XML submission to provide page configurability. To the model and view of a given page, an XML submission is simply an XML document whose content is available as an XPL pipeline or an XSLT input called instance.

There are different ways to produce an XML submission:

• Internal XForms submission. The built-in Orbeon Forms XForms engine uses an HTTP POST XForms submission to submit an XForms instance.

• External submission. An external application or a client-side XForms engine uses HTTP POST to submit an XML document directly to a page.

• PFC page navigation. The PFC, based on a user configuration, produces an XML document to submit internally to a given page.

• Default submission. Each page can refer to a default submission document containing an XML document automatically submitted to the page if no other submission is done.

The most common case of XML submission in Orbeon Forms is submission from the built-in XForms engine. Assume you have a page defined as follows:

If you wish to submit an XForms instance to this page from within report-detail-view.xsl, create an XForms submission as follows:

This ensures that when this XForms submission is activated, an XML document containing the submitted XForms instance will be made available to the page model and view.

You can also directly submit to another page by specifying a different action, for example:

In general it is recommended to leave the control of the flow between pages to PFC actions, as documented below.

An external XML submission must refer to the URL of the page accepting the submission. It is up to the developer to provide this URL to the external application, for example http://www.orbeon.org/myapp/xmlrpc if you have a page declaring the path /xmlrpc:

In case there is no external or internal XML submission, it is possible to specify a static default XML submission document. This is particularly useful to extract information from a page URL, as documented below. You specify a default submission with the default-submission attribute as follows:

The mechanisms described above explain how a page receives an XML submission, but not how to actually access the submitted XML document. You do this in one of the following ways:

• XPL model. The model accesses the XML submission document from its instance input.

• XSLT model. The model accesses the XML submission document using the doc('input:instance') function.

• Static XML model. The model cannot access the XML submission document.

• XPL view. The view accesses the XML submission document from its instance input.

• XSLT view. The view accesses the XML submission document using the doc('input:instance') function.

• Static XML view. The view cannot access the XML submission document.

If no submission has taken place, the XML submission document is an Orbeon Forms "null" document, as follows:

XML submission using HTTP POST convenient in many cases, however there are other ways page developers would like to configure the way a page behaves:

• Using URL parameters. URL parameters are specified in a query string after a question mark in the URL, explained above.

• Using URL path elements. URL paths can be hierarchical, and the elements of the paths can have a user-defined meaning.

A PFC page can easily extract data from the URL using the <setvalue> element nested within the <page> element. To do so, an XML submission must take place on the page. This can be achieved by using the default submission if no other submission is taking place. The default submission document must contain placeholders for for the values to extract from the URL. Given an URL query string of first=12&count=10 with two parameters, first and count, a default sumission document can look as follows:

The following page extracts the two URL parameters:

The <setvalue> element uses the ref attribute, which contains an XPath 2.0 expression identifying exactly one element or attribute in the XML document. The text value of the element or attribute is then set with the value of the URL parameter specified. If there is no parameter with a matching name, the element or attribute is not modified. This allows using default values, for example:

In such a case, if no count parameter is specified on the URL, the default value will be available.

With a query string of first=12&count=10, the resulting XML document will be:

With a query string of first=12, the resulting XML document will be:

If there are multiple URL parameters with the same name, they will be stored in the element or attribute separated by spaces.

It is also possible to extract data from the URL path. To do so, use a matcher attribute on the page as documented below. You can then extract regular expression groups using the <setvalue> element with the matcher-group attribute:

The matcher-group attribute contains a positive integer identifying the number of the regular expression group to extract. With a path of /blog/jdoe/456, the first group contains the value jdoe, and the second group the value 456.

The site logic or page flow describes the conditions that trigger the navigation from one page to the other. It also describes how arguments are passed from one page to the other. In a simple web application simulating an ATM, as illustrated by the ATM example the navigation logic could look like the one described in the diagram on the right. In this diagram, the square boxes represent pages and diamond-shaped boxes represent actions performed by the end-user.

With the PFC, page flow is expressed declaratively and externally to the pages. Consequently, pages can be designed independently from each other. The benefits of a clear separation between site logic and page logic and layout include:

• Simplicity: the site logic is declared in one place and in a declarative way. You don't need to write custom logic to perform redirects between pages or pass arguments from page to page.

• Maintainability: having different developers implementing independent page is much easier. Since the relationship between pages is clearly stated in the page flow, it also becomes much easier to modify a page in an existing application without affecting other pages.

4.2.1. An Example

4.2.2. The <page> element

4.2.3. The <action> element

4.2.4. The <result> element

See the following examples to understand how <page>, <action>, and <result> can be used in a page flow:

• The simple ATM example.

• The Wizard With PFC example.

Also see the Orbeon Forms Tutorial.

You can control what method is used to perform an internal XML submission described within a <result> element. Consider this page flow:

Going from page "a" to page "b" can be done with either a "forward" or a "redirect" method:

The benefit of the "redirect" method is that after being redirected to page b, the end-user will see a URL starting with /b in the browser's address bar. He will also be able to bookmark that page and to come back to it later. However, a drawback is that the request for page b is sent by the browser with a GET method. Since browsers impose limits on the maximum amount of information that can be sent in a GET (URL length), this method might not work if the amount of information that needs to be passed to page b from page a is too large. This typically happens when working with fairly large XML submissions. In those cases, you must use the "forward" method, which does not limit the amount of information passed from page to page. The "forward" method also reduces the number of roundtrips with the server.

You can configure the method:

1. At the application level, in properties.xml with:

   <property as="xs:string" processor-name="oxf:page-flow" name="instance-passing" value="forward|redirect"/>

2. At the page flow level with the instance-passing attribute on the page flow root element:

   <config instance-passing="forward|redirect">...</config>

3. In the page flow at the "result" level, with the instance-passing attribute on the <result> element:

   <page id="a" path-info="/a" model="..." view="..."><action when="..."><result page="b" instance-passing="forward|redirect"/></action></page>

A configuration at the application level (properties.xml) can be overridden by a configuration at the page flow level (instance-passing on the root element), which can in its turn be overridden by a configuration at the result level (instance-passing on the <result> element).

The value of the path-info attribute can be either a simple pattern or a custom pattern.

Groups of files can be matched using a single <files> element with the Perl5 matcher:

A matcher can also be specified on a <page> element:

When using a matcher that allows for groups, the part of the path matched by those groups can be extracted as documented above with the <setvalue> element. Note that the only matcher bundled with Orbeon Forms that accepts groups is the Perl5 matcher, referenced with oxf:perl5-matcher.

The result of matches can be referred to directly in the model and view attributes using the notation ${group-number}:

In this case, if the path contains: /forms/my-form/page/12:

• The model file read will be oxf:/forms/my-form/model.xpl

• The view file oxf:/forms/my-form/view-12.xhtml

Parametrizing model and view attributes this way often allows greatly reducing the size of page flows that contain many similar pages.

When a result element directs flow to a page that uses matchers and <setvalue> elements, the PFC attemps to rebuild the destination path accordingly. Consider the following example:

In this example, accessing the source page directly causes navigation to the destination page. Using the following information:

• The internal XML submission

• The destination page's matcher groups

• The <setvalue> elements

The PFC reconstructs the path to /user/orbeon/blog/12345. This path is used to request the destination page. In this case, the view attribute evaluates to blogs/orbeon/blog-12345.xhtml.

A page flow file is comprised of three sections:

• The <files> elements list files that must be served directly to the client, such as images or CSS files.

• The <page> elements declare pages and for each one specify identifier, path, model, view, and XML submission.

• The <epilogue> and <not-found-handler> elements define additional behavior that apply to all the pages.

Some files are not dynamically generated and are served to the client as-is. This is typically the case for images such as GIF, JPEG, CSS files, etc..

You tell the PFC what files to serve directly with one or more <files> elements in the page flow. The example below shows the configuration used by the Orbeon Forms examples:

With <files path-info="*.gif"/>, if a request reaches the PFC with the path images/logo.gif, the file oxf:/images/logo.gif is sent in response to that request.

The <files> element supports the path-info and matcher attributes like the <page> element. It also supports a mime-type attribute telling the PFC what media type must be sent to the client with the files. The PFC uses defaults for well-known extension, as defined by the Resource Server processor. In doubt, you can specify the mime-type attribute.

You often want a common look and feel across pages. Instead of duplicating the code implementing this look and feel in every page view, you can define it in a central location called the page flow epilogue. The <epilogue> element specifies the XPL pipeline which implements the page flow epilogue.

This is an example of <epilogue> element, pointing to the default epilogue XPL pipeline:

The page flow epilogue is discussed in more details in the Page Flow Epilogue documentation.

The <not-found-handler> element is used to specify the identifier of a page to call when no <page> element in the page flow is matched by the current request. There can be only one <not-found-handler> per page flow.

This is an example of <not-found-handler> element and the associated <page> element:

By default, oxf:/config/not-found.xhtml displays a simple XHTML page telling the user that the page requested cannot be found.

Simple pages with no back-end code can be implemented with a single XPL pipeline, XSLT template or static page. A view XPL pipeline must have a data output. The XML generated by the view then goes to the epilogue.

If a page is not sent back to the user agent, there is no need for a view. This is typically the case when a redirect needs to be issued, a binary file is produced, or when a page simply implements an XML service.

This is a variant of the view only scenario, where an XML submission is used. In this case, the view receives the XML submission as the instance input.

This is a variant of the model only scenario, where an XML submission is used.

This is the classic case. An XPL pipeline implements the page model and an XSLT template implements the page view where data produced by the model is consumed by the view.

This is the equivalent of the previous model where an XML submission is used. In this case an instance input is made available to the model and the view.

This is a variant of the previous case where the model declares an instance output. This allows the model to modify the submitted XML instance. This is typically useful when the view displays some values from the XML submission document but these values are not exactly the same as those entered by the user. For example, a page with a text field where the user types an airport code. If the user enters a known city such as San Francisco, the application may automatically add the corresponding airport code (SFO in this case).

The following example illustrates how to perform a simple redirection with the PFC. Assume you want some path, /a, to be redirect to another path, /b. You can do this as follows:

Note that you do not have to use redirect, but that doing so will cause the user agent to display the path to page /b in its URL bar. The instance-passing attribute is also unnecessary if redirect is already the default instance passing mode.

The PFC allows you to very easily receive an XML document submitted, for example with an HTTP POST, and to generate an XML response. This can be useful to implement XML services such as XML-RPC, SOAP, or any XML-over-HTTP service. The following PFC configuration defines a simple XML service:

Notice that there is no view attribute: all the processing for this page is done in the page model.

The following content for xml-rpc.xpl implements an XML service returning as a response the POST-ed XML document:

Notice the optional schema-href attributes which allow validating the request and the response against schemas.