Domino Rich Text In The Browser

Jake Howlett, 12 July 2004

Category: Forms; Keywords: rich text editor applet wysiwyg

For the first time in this site's 4 year history I am writing this - the 146th article - in wysiwyg HTML mode. In the past I have carefully hand-crafted each article. If I wanted to insert any HTML I would do so between carefully balanced sets of [square brackets].

This works failry well, but it becomes tiresome after a while. It's nice to be able to simply press a button and have text marked bold or italic or to press a button and insert an link or an image. That's why I now use HTMLArea, as you can see in this screenshot.

What I am going to talk about in this article is how to use this handy tool in your own applications. There's really not that much to it! The end result is that you don't have to use Domino's Rich Text Java Applet any longer. Hurrah!

What's the problem:

Since release 2.0 the Notes client has included fields that store Rich Text. Until release 4.5 everything worked fine. Then we started to create, read and edit documents in the web browser. This is where the problems began. How can users edit rich text from the web? The solution Lotus came up was the Java Editor Applet. Whilst this Applet works well, it's not to everybody's taste. In fact many, myself included, really don't like it at all! I've listed some of the reasons in a blog post recently. I'll leave it at that. I don't want to get in to a rant about how poor the applet is. Instead I will concentrate on how we can avoid it.

Let's see what happens when you create a simple form with a Rich Text field, add some formatted text in the client then try and access it in the browser. First the form itself which, in its simplest form, might look like this:

If we create a document using this form in the client we would see something like this:

When this document is saved, Notes stores this text in Rich Text format and remembers the style applied to each portion of the text. When we open the document in the browser, Domino converts all these styles in to the equivalent HTML and we see something that looks like this:

This is good. It's exactly what we'd expect to see. But what about if we try and edit the document? Then we see this:

Domino does allow us to edit the field but but where has all the styling gone!? If we went on to save this document from the web the field would lose all the formatting that was applied in the client. Obviously this is no good and that's why Lotus introduced the Java Editor Applet. If we enable the applet for this field, then edit mode looks like this:

This is a lot better. Not only can we apply new styles but we retain the original formatting. There's also the added benefit that these same styles we apply in the browser are then editable again in the Notes client, and vice-versa. Most of you may well be happy with this solution, but a lot of us aren't. For years we've all hunted for the ideal alternative solution for editing Rich Text on the web. Hopefully I've found it and this article explains how you can do the same.

What this article fails to achieve is a two-way, Notes-browser editor. The solution I am about to describe only works f or documents edited solely in the browser. Future articles will cover two-way editing in more detail.

More on Rich Text Woes:

It seems obvious that the field that holds the body of this article would be Rich Text. But is it? With a normal text field we can easily mimic a <textarea>, that holds 64kb of data. Here's 58KB of text to give you an idea how much that would be. The reason I made the "body" Rich Text is that it gives me flexibility to go beyond this.

For the four years I've been wrting articles I've had to place [<b>all</b>] HTML inside square brackets. Then when Domino sends the field to the browser it knows to send these bits as HTML. But, why can' t we simply tell Domino that the whole field is HTML in the first place!? Herein lies the problem. Unless Domino thinks you are allowed to use HTML, it won't store it that way, rather it will store it as plain text. There's no way to say "Look Domino, I am going to type HTML in to this field and I want you to return it to me as such!".

What happened recently was that a kind reader of this site, David Schmidt, posted some code that changes all this. We can now trick Domino in to thinking the field's content is HTML. Without this code, if you typed the following in to a simple Rich Text field:

<p>This is a sample <b>bit</b> of <s>rich</s> text</p>

You would see exactly that when you opened the document in read mode, angle brackets, markup and all. Instead of the following, which you might have expected to see:

This is a sample bit of rich text

It's as though Domino doesn't trust us to do it ourselves. But I suppose the argument works both ways. Maybe there would be a time when we would want to have the letter b appear between a set of angle brackets, like <b>, meaning we would need to type &lt;b&gt;. Unless Domino knows we are using HTML markup it can't assume otherwise.

Let's stop picking fault with Domino and concentrate on how we can work around its shortcomings. First I want to rule out one possible solution. This is to mark a Rich Text field as PassThru HTML, by surrounding it with square brackets and some "dummy" HTML, as in the shot below:

This method certainly works but it has its drawbacks. The main problem is that users can, inadvertently or not, enter text that will turn "HTML mode" off. This solution is one I've tried in the past and had problems with. I suggest you avoid this in favour of David Schmidt's solution and use code to flag the field as HTML.

Solving the Problem with Code:

David's solution uses a new Domino 6 method called GetUnFormattedText(). Assuming we have a form with a Rich Text field called Body on it, the code looks something like this:

Dim vRichStyle As NotesRichTextStyle
Dim vRTItem As Variant
Dim vHTMLCode As Variant
Set vRichStyle = vWebSession.CreateRichTextStyle
vRichStyle.PassThruHTML=True
Set vRTItem = vThisDocument.GetFirstItem( "Body" )
vHTMLCode= vRTItem.GetUnFormattedText()
Call vThisDocument.RemoveItem("Body")
Set vRTItem = vThisDocument.CreateRichTextItem( "Body" )
Call vRTitem.AppendStyle( vRic hStyle )
Call vRTitem.AppendText(vHTMLCode)

The code does a couple of things. First it creates a new RichTextStyle object and flags it as being PassThru HTML. It then gets the unformatted text from our Body field, stores it separately, before removing the original Body field, which would have stored the text in the wrong format. It then creates a new field, also called Body. This new field has the PassThru HTML style applied to it and then has the stored unformatted text inserted. The result is that the text we entered is stored as HTML, exactly as we entered it. Whatever we enter in to this field - that is what Domino will return to the browser.

This code goes in the WebQuerySave agent that runs each time the document is submitted. I've been testing this simple bit of code for some time now and have seen no problems with it at all. The largest document I created held over 160KB of text without a problem.

Now that we have a suitable workaround we can start looking at the alternative methods of editing formatted text in the browser.

My Favourite Editor:

Of all the free web editors available I think the best by far is HTMLArea, althought which you decide to use is obviously down to you. With the code above it doesn't really matter which you use, but, for the rest of this article, I will be assuming you want to use HTMLArea. The demo database you can download is also based around it.

There are various features of HTMLArea that make it my favourite choice. Here are a few of them:

Hopefully, you will like it too. If you want to have a quick look at it, here's an example page. If you find another editor that you prefer, please let us all know.

Including HTMLArea in our Database:

First thing to do is download yourself a copy of version 3 of HTMLArea from the creator's download page. If you extract all the files you'll see there's quite a few of them, arranged in a folder hierarchy, like below:

The easiest way to use HTMLArea with our Domino databases would be to simply add all these files to their own folder, within the Domino\HTML directory, on the server. However, I will assume we can't do this and have to include the files in our actual database de sign.

The easiest way to do this would be to simply add all the files to Domino 6's File Resources section. The best approach though is to keep them organised by type. As you can see from the root folder above there's one CSS file and four JavaScript files. The CSS file can be imported as a Style Sheet Resource. The contents of the JavaScript files can be pasted in to JavaScript Library Resource elements. Then we can add all the images from the "images" folder as Image Resources. But, we need to maintain the above folder structure, so that the HTMLArea code can find all the required pieces. To do this we mimic a folder structure by renaming the Resource elements, prefixing them with the folder name and as many /s as required. We end up with Resources with names that look something like below:

We do the same with the HTML files in the "popups" folder, adding them as File Resources before renaming them, as below:

It takes some time but it's possible to get all the pieces of HTML Area inside our database. To save your time you can download the sample database and use that as a starting point.

Using HTMLArea in our Forms:

As I mentioned earlier, HTMLArea works with standard <textarea> elements. This is good because that's what Domino uses to represent a Rich Text field in the browser. On our form we simply add a normal Rich Text field. In the browser we add the HTMLArea code and this turns the standard field in to a fully-functioning wysiwyg HTML editor.

Assuming you have a Rich Text field on your form, all we need to do is add the HTMLArea code and trigger the onload event that turns the field in to a fully-fledged editor. This is actually a lot simpler than it sounds!

First thing to do is include the JavaScript file that contains the main HTMLArea code, which lives in HTMLArea.js. This is as easy as adding it to the HTML Head Content section of our form, like below:

When the form opens in edit-mode all the required JavaScript is loaded. All we need to do now is tell the code what to do and add some configuration information. First we need some JavaScript code to configure the editor and then a function to load it. In its simplest form, this looks something like:

var _editor_url = "/apps/htmlarea.nsf/";
var _editor_lang = "en";
function initEditor() {
var editor = new HTMLArea("Body");
editor.generate();
}

Now we can place this initEditor() function in the form's onLoad event. Each time the form is opened the initEditor function creates a new HTMLArea editor object and applies it to our Body field.

There's a little more to it that this, but that's the basics. All you need is four or five lines of code.

One of the problems is that we only want this onLoad event to trigger the function in edit mode. To get round this, in the demo database, I created another variable called _edit_mode that is either true or false and is set using the @IsDocBeingEdited function. With this variable we know whether or not we need to enable the editor. Withou t this step we would get errors in read mode as th ere's no field called Body on which to work.

So, there you have it. To use HTMLArea in its most basic format that's all you need to do. Here's an example of what this might look like. Nice isn't it!?

Taking it Further:

As I mentioned earlier, HTMLArea is open for customisation. There are also more things we can do with it without the need for extensive coding. However, this article is long enough already and I don't want to give it all to you at once. In future articles we will look at how we can customise and tailor it to our needs. Here's an example customised form that lets us link to internal database documents.

We will also look at how we can use HTMLArea for web editing and still allow users to edit the same text in the client. So far in this article I have been talking only about editing in the web. As with most of the approaches described on codestore I am only dealing with the browser. I can see that this is something that really needs to work in both clients though and so I shall cover the workaround in another article ASAP.

Summary:

The ability to store Rich Text in Notes is great. The only problem is that this has never translated well to the browser side of things. As with everything Domino does, it does it its own way. We are pretty well powerless to do anything about it. Whereas with other technologies it's down to the developer to engineer how pages are delivered and content stored, Domino knows only one way. What we need is ways round it and this is what this article describes - a way to beat Domino at its own game.

Some of you may not have seen the need for this replacement editor in the first place. Maybe you're happy with the Java applet. What you need to consider is how long you can keep supporting these applets for. Microsoft seem adamant they will not keep on supporting Java in IE and the Domino applets seem unable to work with my current install of Mozilla. What we need is a cross-browser solution and that's what I've offered here. I hope you enjoy it!