Orbeon Forms User Guide

JSR-168 Portlets

1. Introduction

1.1. Servlet and Portlet Deployment

Orbeon Forms is typically used to create Web applications. In this case, Orbeon Forms relies on standard Java Servlet technology, and the Web application's web.xml file is configured to use the OrbeonForms Sqervlet or Orbeon Forms Servlet Filter. Orbeon Forms conforms to the Java Servlet API and handles a Web client's entire real estate on the browser.

Orbeon Forms also provides the Orbeon Forms Portlet, which supports the implementation of standard Java portlets that can be deployed within any portal or portlet container compatible with the Java Portlet specification. This specification is also known as JSR-168.

1.2. What is a Portal?

A portal is a Web application that provides several features such as:

  • Content Aggregation. A single Web page within the application aggregates the output or user interface of several data sources or applications.

  • Personalization. Users or administrators of the portal can customize the user interface. This often means not only customizing the look and feel, but also selecting a certain set of available functionalities within the application.

  • Single Sign-On. The user logs in only once to access several applications in the portal.

1.3. What Is a Portlet?

According to the Java Portlet Specification, a portlet is a "Java technology based Web component, managed by a portlet container that processes requests and generates dynamic content. Portlets are used by portals as pluggable user interface components that provide a presentation layer to Information Systems". An implementation agnostic definition can be found in the Web Services for Remote Portals (WSRP) White Paper of 22 September 2002 "Portlets are user-facing, interactive Web application components rendering markup fragments to be aggregated and displayed by the portal."

In other words, a portlet is usually a Web application that can be embedded within a portal, and shares Web page real estate with other portlets. Traditionally portlets available in public portals have provided simple features such as stock quotes, news feeds, weather reports, etc. In particular thanks to the Java Portlet specification, there is no limit to the extent of the features provided by a portlet, and it is expected that complex interactive portlets will become more and more widespread.

2. Orbeon Forms and Portlets

Orbeon Forms hides the complexity of the Portlet API to allow most Orbeon Forms applications to work unmodified within portlet containers and to follow best practices allowed by the Web Application Controller. In particular, the Portlet API requires:

  • Separation of faceless actions from rendering. Orbeon Forms allows actions to generate output while still adhering to the Java Portlet specification. Developers are obviously free to only write faceless actions. In the Page Flow Controller, such actions end with a <result page="some-page-id"> directive.

  • Getting rid of the familiar concept of URL path. Orbeon Forms abstracts this behavior and provides Orbeon Forms Portlet developers with the notion of a path, implicitly in the Web Application Controller, or explicitly with the Request Generator, while still adhering to the Java Portlet specification.

  • Getting rid of the familiar concept of URL redirection. Instead, portlet actions can set parameters to use in subsequent portlet rendering. Orbeon Forms abstracts this behavior and provides, indirectly in the Page Flow Controller, or explicitly with the Redirect Processor, the notion of redirecting to another page within the portlet.

  • Calling APIs to generate URLs. Orbeon Forms handles this by providing automatic URL rewriting.

  • Generating Markup Fragments. The default Orbeon Forms epilogue automatically extracts a fragment from a Orbeon Forms <d:document>. This allows pages to remain unmodified for both servlet and portlet deployment. The default epilogue also makes sure that no HTML or XML DOCTYPE is generated at the beginning of a fragment. The default epilogue can easily be modified.

3. Liferay Deployment

The Orbeon Forms WAR can be directly deployed into the Liferay portal. Follow the following steps with Liferay 4.2.1:

  1. Either enable Auto Deploy in the Liferay Admin portlet and drop ops.war into the Deploy Directory, or upload ops.war directly from the Liferay Admin portlet:

  2. Create a new Liferay page called "Orbeon" and open that page. Move your mouse to the upper right corner and use the big "+" icon to add content:

  3. You should see the Orbeon Form Portlet appear in the menu. Select "Add" to add the portlet to the page:

  4. The portlet displays a welcome page with links to Orbeon Forms examples (here shown maximized):

This is the "Flickr Resize" example running in the portlet:

4. IBM WebSphere Portal 6 Deployment

It has been reported that Orbeon Forms deploys into IBM WebSphere Portal 6.

[TODO: Exact configuration steps.]

5. Configuration

Configuration of portlets is done in a standard file called portlet.xml that sits in the same directory (WEB-INF) as your web.xml. The portlet-class element must always be org.orbeon.oxf.portlet.OPSPortlet for Orbeon Forms Portlets (you can also configure non-Orbeon Forms Portlets within the same portlet.xml). The main processor URI and optional inputs are specified with the oxf.main-processor.uri and oxf.main-processor.input.* initialization parameters. For example:

<portlet-app><portlet><portlet-name>OrbeonFormsPortlet</portlet-name><portlet-class>org.orbeon.oxf.portlet.OPSPortlet</portlet-class><supports><mime-type>text/html</mime-type><portlet-mode>edit</portlet-mode></supports><init-param><name>oxf.main-processor.name</name><value>{http://www.orbeon.com/oxf/processors}pipeline</value></init-param><init-param><name>oxf.main-processor.input.config</name><value>oxf:/config/prologue-portlet.xpl</value></init-param><init-param><name>oxf.error-processor.name</name><value>{http://www.orbeon.com/oxf/processors}pipeline</value></init-param><init-param><name>oxf.error-processor.input.config</name><value>oxf:/config/error.xpl</value></init-param><supports><mime-type>text/html</mime-type><mime-type>application/xml</mime-type></supports><portlet-info><title>Orbeon Forms Portlet</title></portlet-info></portlet></portlet-app>

It is possible to configure several Orbeon Forms Portlets within the same portlet.xml, with the same or a different configuration. The portlet-name element however must be different for each portlet, as per the Java Portlet specification. For more examples, please consult the example portlet.xml file in the Orbeon Forms examples.

6. Portlet Output

The type of the portlet output is determined by the serializer. With the default Orbeon Forms epilogue in config/epilogue-portlet.xpl, the HTML serializer is used.

7. Preferences

Portlet preferences can be retrieved with the oxf:portlet-preferences-generator processor.

To retrieve the preferences of your current portlet, use the following code:

<p:processor name="oxf:portlet-preferences"><p:output name="data" id="portlet-preferences"/></p:processor>

The generator outputs a document containing name / values in the following format:

<portlet-preferences><preference><name>name1</name><value>value1</value></preference><preference><name>name2</name><value>value1</value><value>value2</value><value>value3</value></preference></portlet-preferences>

For example:

<portlet-preferences><preference><name>max-items</name><value>10</value></preference><preference><name>url</name><value>http://xml.newsisfree.com/feeds/42/1842.xml</value></preference></portlet-preferences>

Portlet preferences can be saved with the oxf:portlet-preferences-serializer processor. [TODO]

8. Security

Portlet security can be configured in portlet.xml as per the Portlet specification. The Request Security processor provides security information like in the case of Servlets.

9. Deployment

A Orbeon Forms portlet application is deployed like a regular Web application. You have to make sure that, in addition to the web.xml, you have a valid portlet.xml configuration file as well.

You can deploy the application in any portlet container supporting the version of the specification mentioned above.

It is possible to deploy Orbeon Forms Servlets, Servlet Filters, Servlet Context Listeners, and Portlets within the same application:

For more information, see Packaging and Deployment. Note that the use of the Page Flow Controller is optional but its use is typical.

10. Limitations of Orbeon Forms Portlets

The Orbeon Forms Portlet developer should be aware of the following limitations:

  • Redirection. In the Page Flow Controller, pages that are the target of a portlet render URL cannot end with a redirection. This in particular applies to the default portlet page ("/"). Developers have to make sure that a page exists for "/" that produces content and does not end in a redirect. Other pages can end with redirects by making sure that they are targeted by action URLs (by default, only the target of HTML or XHTML form submissions generate action URLs).
  • Portlet Mode and Window State hints. It is currently not possible to set a portlet mode or window state hint in a URL.
  • Content Type Hints. It is not possible for an Orbeon Forms Portlet to know which content types are supported by the portal.
  • Preferences. It is currently not possible to modify portlet preferences or store them from within a portlet.
  • XML Fragments. The Orbeon Forms Portlet currently must generate XML fragments containing a root node. This is rarely an issue, as a fragment can for example be embedded within an XHTML <div> element.
  • Struts integration. Currently, Struts does not natively support operations within a Java portlet.
  • JavaServer Faces integration. JSF currently does not natively support operations within a Java portlet.

In addition, and this is by design of the API, Java portlets cannot directly serve resources such as images, CSS stylesheets, standalone JavaScript files, etc. Those resources have to be served by a Servlet. Portlets therefore cannot directly serve resources using:

  • The Chart processor
  • The Image server
  • The Resource server
  • The PDF serializer
  • The Excel serializer
  • Or any processor serving resources

Orbeon Forms Portlets can however refer to resources served by the Orbeon Forms Servlet.