Form Runner Liferay Full Portlet
- Supported Liferay versions
- Deploying into Liferay
- Creating a new landing page for the portlet
Please make sure to check the Form Runner Liferay Proxy Portlet Guide as well, as that is the recommended way to deploy Orbeon Forms into Liferay, and Form Runner Embedding for a comparison of portlet deployments.
This is an Orbeon Forms PE feature.
Supported Liferay versions
Deploying into Liferay
The Orbeon Forms WAR can be directly deployed into the Liferay portal. By default, the Form Runner demo forms and XForms examples are immediately available within the portlet:
The following steps assume that:
- Liferay is deployed on port 8080
- the Orbeon Forms WAR is deployed under the name "orbeon" (which is the default if the WAR file is called orbeon.war)
Deploy orbeon.war: Start Liferay. When it is fully started move the
orbeon.warinto the Liferay deploy directory (e.g.
~/liferay/deploy). At this point, you should see message indicating that Orbeon is being deployed. Monitor the Liferay output as well as the
logs/orbeon.logfor possible errors.
Enable dynamic resource reloading (optional): Remove the file
webapps/orbeon/META-INF/context.xmland restart Liferay. For more information on what this does, see note 2 below.
Configuration for Form Runner (optional): You can skip this step if you do not intend to use Form Runner or Form Builder in a portlet. Otherwise, create a file
WEB-INF/resources/config/properties-local.xmlwhich declares the following properties (and other properties you might want to override):
<properties xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:oxf="http://www.orbeon.com/oxf/processors"> <!-- Configure authentication properties through headers --> <property as="xs:string" name="oxf.fr.authentication.method" value="header"/> <!-- If you want the Liferay user email used for Form Runner authentication --> <property as="xs:string" name="oxf.fr.authentication.header.username" value="Orbeon-Liferay-User-Email"/> <!-- If you want Liferay roles used --> <property as="xs:string" name="oxf.fr.authentication.header.roles" value="Orbeon-Liferay-User-Roles"/> </properties>
The host name (
localhost), port (
8080), and context path (
orbeon) must be updated to match your local configuration.
Add the Orbeon Forms portlet: Log into the portal, go to the Add menu and create a new page, for example Orbeon Page. Then go to the Applications tab and click or drag "Orbeon Forms Portlet" to the page. The Orbeon Forms home page will show.
When Liferay deploys Orbeon Forms, it changes some of the descriptors and adds a
META-INF/context.xml which is not
present in the distribution of Orbeon Forms. This file contains:
<context antijarlocking="true" antiresourcelocking="true">
which causes Tomcat to, on startup, make a copy of the Orbeon web application into its temp directory and use that
copy instead of the files under
webapps/orbeon. That copy is removed when the server shuts down, and will be
done again the next time the server is started. This makes starting Liferay slower, but more importantly this means
that changes you make to files under
webapps/orbeon after the server started will never be picked up. So any
modification to the resources (
WEB-INF/resources) of your application will require a restart of Liferay.
This can be quite time consuming and annoying, hence our recommendation to remove the
generated by Liferay.
Accessing Liferay users and roles
Using the xxf:get-request-header() function
When running in Liferay, you can access some specific user and roles information from XForms.
Getting the current user's email:
Getting the current user's full name:
Getting the current user's role names:
This returns a sequence of strings, with one string per role.
('Administrator', 'Power user', 'User')
Alternatively, you can use the standard
Orbeon-Roles headers. See also Access Control.
[SINCE Orbeon Forms 4.10]
The portlet is configured to use two portlet filters in
The first filter,
AddLiferayUserHeadersFilter, extracts Liferay user information and sets it as headers ("properties" in portlet API parlance). This sets the following properties/headers:
The second filter,
AddOrbeonAuthHeadersFilter, handles either container or header-based auth, and then sets the following headers/properties:
These in turn are used internally by Orbeon to handle other aspects of authentication/authorization.
For large pages, we have found that the Liferay strip filter can take an extremely long time to process a response.
You can disable that filter in your
portal-ext.properties is a standard Liferay configuration file you place under the Liferay Home directory.
Creating a new landing page for the portlet
By default, the portlet shows a list of Orbeon Forms sample forms and apps.
To change this, you need to:
- Create a new landing page in XHTML format.
- Change the default Orbeon theme so that no custom Orbeon CSS is added.
A simple way do implement this is as follows:
First, replace this line in
<page path="/" model="apps/home/page-flow.xml"/>
<page path="/" view="home.xhtml"/>
Second, create a new file,
WEB-INF/resources/home.xhtml, with content such as:
<html xmlns="http://www.w3.org/1999/xhtml"> <head> <title>Form Runner Home</title> </head> <body> <a href="/fr/">Link to the Form Runner home page</a> <a href="/fr/acme/form1/summary">Link to summary page of form acme/form1</a> <a href="/fr/acme/form2/new">Link to new page of form acme/form2</a> </body> </html>
This is the landing page itself, and it can contain any XHTML you like. Typically would include links to specific Form Runner paths as shown in the example above.
Finally, to change the Orbeon portlet theme to the plain theme, set this property:
<property as="xs:anyURI" name="oxf.epilogue.theme.embeddable" value="oxf:/config/theme-embeddable.xsl"/>