JSR-168 Portlets
- 1. Introduction
- 1.1. Servlet and Portlet Deployment
- 1.2. What is a Portal?
- 1.3. What Is a Portlet?
- 2. Orbeon Forms and Portlets
- 3. Liferay Deployment
- 4. IBM WebSphere Portal 6 Deployment
- 5. Configuration
- 6. Portlet Output
- 7. Preferences
- 8. Security
- 9. Deployment
- 10. Limitations of Orbeon Forms 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:
-
Either enable Auto Deploy in the Liferay Admin portlet and drop
ops.war
into the Deploy Directory, or uploadops.war
directly from the Liferay Admin portlet: -
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:
-
You should see the Orbeon Form Portlet appear in the menu. Select "Add" to add the portlet to the page:
-
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:
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:
The generator outputs a document containing name / values in the following format:
For example:
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.