5.5 Domino Rich Text

< Day Day Up >

Domino Rich Text fields can contain formatted text, collapsible sections, embedded objects, file attachments, and pictures. Rich text is widely used in Domino applications, so it is important to be able to display it in a Portlet.

In Chapter 1, "Introduction to portalizing Domino applications" we introduced the concept of Portlet patterns. We outlined that in a Portal environment there are two main ways to display content:

Following the Display pattern by opening content in a new browser window.
Embedding content inside of the Portlet. This can be achieved with the Integrated Portlet pattern.

In this section we discuss both optionswith respect to Domino rich text display.

Using the Portlet Display pattern

Following the Display pattern and opening content in a new browser window has the following requirements for the Domino application:

You need a Web-enabled form.

You also need to consider that:

Content is displayed outside of the Portlet
The browser directly communicates with the Domino HTTP server. This might involve firewall issues.

Using iFrames

An alternative to opening a new browser window is the use of an iFrame Portlet. This approach still follows the Display pattern, but has a more seamless integration with the Portal. But you need to be aware of the following limitations of iFrame Portlets:

iFrame Portlets are not real Portlets.
They do not support Portlet cooperation.
They can't use Portal themes.
iFrame Portlets can't keep their state. Consider the workplace example that was introduced in "Case study objective: Sales Workplace" on page 50. There we have two Portlets. One is displaying a customer search Portlet and the other the customer details. If we search for a customer and select the link, the details Portlet displays the customer details information. If we now change the place to do some other work and later come back to our Sales Workplace, the details Portlet does not display anything anymore. It is displaying its default page, which is blank. This example shows the state problem that iFrame Portlets have: they are acting outside of the Portal context and therefore can not keep the state of the user's actions.

Embedding content into a Portlet

In this section we discuss integration methods that follow the Integrated pattern.

What options do we have to embed rich text inside of a Portlet?

One option is to display rich text as plain text only. This is useful, for example, for displaying abstracts. To accomplish this we can use:

The Item's getText method in Java
The richtext tag from the Domino JSP tag library

Note

The Domino 6 Tag library has a <Domino:richtext> tag to display rich text, but formatting is displayed only if the rich text was created using the RichText Java applet or the Microsoft rich text control.

In this case the rich text is saved as MIME (Multipurpose Internet Mail Extensions) inside of a Rich Text field. Programmatically you can access these items as Item, RichTextItem, or MIMEEntity objects.

Using the richtext tag to display rich text that was created with a Notes client will show plain text only. That means all formatting, images, sections, and URLs are lost.

To keep all the formatting and features of Domino Rich Text we have to take a different approach. Domino Rich Text is a very complex structure that can be programmatically accessed by using the Domino backend classes for Java.

Nevertheless the only way to convert Rich Text into HTML is to use the Domino HTTP task.

Displaying rich text using HTTP

The following steps outline how you can get the HTML representation of the Domino Rich Text. This approach has to be implemented in Java. Figure 5-12 illustrates the process.

click to expand
Figure 5-12: Embedding Domino rich text inside of a Portlet

Open a URL connection to retrieve the HTML for an entire Domino document.
Parse the HTML for the rich text field that you want to display.

To find the HTML that corresponds to the rich text field, it is best practice to indicate the start and end of the field by adding an HTML comment around the field on the Domino form.
Pass the resulting HTML to the JSP page for display.

After you have implemented this solution you will find that the formatting of the text is now displayed correctly, but that all Images are broken. The reason for this is that the HTML you retrieved from the Domino HTTP included relative URL references only. Since you are now displaying the captured HTML relative to the Portal server's HTTP task, the URLs can't be resolved.

You can solve this problem in either of the following ways:

The IBM HTTP plug-in can be used as a reverse proxy to Domino 6 servers. For this communication to occur, the appropriate WebSphere Application Server 4.0.3 or later plug-in must be installed on the front-end server. These plug-ins recognize HTTP requests for Domino applications and pass them along to the Domino server. Other HTTP requests are handled by the front-end server itself.
Parse the Domino HTML and make all URL references absolute to the Domino HTTP server. Using regular expressions can help to implement this process.

Either of these techniques will solve the image URL problem and display the images correctly.

URL rewriting

The second option (URL rewriting) has the disadvantage that the user's browser will need to be able to communicate with the Portal server HTTP and the Domino server HTTP as well. This communication pattern might be prevented by firewall rules, as illustrated in Figure 5-13.

click to expand
Figure 5-13: Potential firewall issues

Since the image reference is referring back to the Domino server's HTTP task, the browser needs to be able to access the Domino HTTP server to display the image.

This also implies that the user needs to have access rights to the Domino server and database in which the image resides.

The URL challenge

But we still have an even bigger challenge ahead of us. Specifically, all the URLs in the HTML produced by Domino HTTP server are not Portal compliant. That means that if a user clicks on a link inside of the Rich Text, the called URL will take over the entire browser URL. As a result, the Portal interface is lost.

The workaround for this problem is illustrated in Figure 5-14.

click to expand
Figure 5-14: Rich Text display with reverse proxy and URL re-writing

Implement a reverse proxy in Java that handles, for example, the display of resources with relative URLs.
Parse the captured HTML using regular expressions and rewrite URLs into Action URIs.
By implementing an action listener, you can then respond to the Action URIs and allow the user to navigate links in the HTML. This ensures that all following pages will be displayed inside the Portlet as well.

The discussion shows that Domino rich text integration into Portlets is a complex and potentially challenging procedure.

IBM is currently working on a solution that will allow easy Domino rich text integration. Third party vendors like CONET have also implemented solutions for seamless rich text embedding in their products.

< Day Day Up >