The last article I wrote - Domino Rich Text In The Browser - introduced the idea of edting WYSIWYG HTML in the browser without needing to use any Java applets. The text was stored as PassThru HTML, giving the appearance of native Rich Text. It wasn't quite the Holy Grail of being able to edit native Rich Text in both the client and a browser without losing any formatting. However, if your users don't use the client, it's a nice solution and worthy of a read.

This article is going to take it a few steps further, getting a little more advanced. First we will look at how to personalise and customise the editor. Then how to extend the functionality of the editor by using some additional plug-in modules. Then we'll look at how to extend it by adding our own functionality. To finish off I'll make another sample database available that includes these extra features not included in the last article.

Personalising The Editor:

Adding new features is all very well, but sometimes less is more. What if you don't need all the icons that come with the default editor? Well, it's easy to use as little or as many of them as you like. Let's see how.

Remember for the default editor we added it to a form using the following simple JavaScript, called from the page's onload event:

function initEditor() {
var editor = new HTMLArea("Body");
editor.generate();
}

Well, when we want to personalise it we simply add a few extra lines that create a config object, as below:

function initEditor() {
var config = new HTMLArea.Config();
config.statusBar=false;

var editor = new HTMLArea("Body", config);
editor.generate();
}


This simple example creates an editor with no status bar. Notice how we created the config object, made a change to it and then passed it to the new HTMLArea object via its constructor method.

You can do alsorts of stuff with this config object. If you want to over-ride the default toolbar you create a new one like so:

config.toolbar = [
[ "bold", "italic", "underline", "strikethrough", "space","separator","subscript", "superscript", "separator", "insertimage","htmlmode" ]
];

This gives the user a limited number of features. One of those missing is the ability to change the font face and size. To change the default font of the editor you can use this line:

The page you end up with would look something like this.

How much you personalise the editor is down to you. For more information and help read the reference page.

Adding To The Editor:

As with all great software the HTMLArea editor is built in such a way that it is easily extended. It's easy to add more features to it, module by module. You can either download these modules or write your own.

The editor download includes the following plugins:

• Spell Checker
• Table Operations
• Context Menus

Enabling them is easy. But first we have to make sure we have all the required files. If you've downloaded a copy of the HTMLArea 3 zip, you will see it contains a subfolder called plugins. This contains the files needed for them to operate and they need to be kept in this same folder structure to work properly. To do this in Domino we add them as File Resource elements, as below:

Notice how I changed the names of the elements to match the folder structure of the original files. This fools the editor in to believing they are where they should be.

With all the required files in place we can then enable the plugins in the editor. This is really easy and just needs a couple more lines of code:

HTMLArea.loadPlugin("ContextMenu");

function initEditor() {
var editor = new HTMLArea("Body");
editor.registerPlugin(ContextMenu);
editor.generate();
}

Simple, isn't it. You can add more plugins in the same way. That's how I created this form from the demo database.

It's all very well making the most of what you're given, but you sometimes need that little extra something. When this happens you need to write your own features. This part isn't as well documented, but a little hacking reverse engineering can get you a long way.

To test the theory out I decided to create a button that would be useful in its own right. Its function is very similar to the Insert Link icon, but it lets us insert a link to a Notes document from within the database.

Because the functionality is so similar to the existing link button, all I had to do was pick apart that feature and recreate something very similar. The first thing I had to do was register a new button with the editor, like so:

config.registerButton({
id : "createdoclink",
tooltip : "Insert Notes DocLink",
image : _full_path + "images/ed_doclink.gif",
textMode : false,
action : function(editor,id) { editor._cr eateDocLink()} }
);

config.toolbar =
["bold", "italic", "underline", "strikethrough", "space","separator","subscript", "superscript", "separator", "insertimage", "createdoclink","htmlmode"
];

Here we've created a new button called "createdoclink" and then included it in the toolbar, between the image icon and the html-mode icon. The result looks something like this.

When you click this button it called a method of the editor object called _createDocLink(). We told it to do this in the config lines above. Now we need to add this new method to the editor object. Because it's so similar to the function called by the link icon I just made a copy of this function and pasted it in to a new JS file called custom.js.

Note:It's in a separate file so that it doesn't get over-written by any upgrades you do in the future.

The function is very similar apart from the following line, where I made a change:

this._popupDialog("../link?openview&count=10",

The original function opened this HTML file. The new function opens this view instead. The view is a part of a $$ViewTemplate, on to which I pasted all the HTML from the original link dialog. I then created a view that simply shows all other documents and, when clicked, adds their URLs to the dialog's fields, ready for use in the editor.

To make sure that the _createDocLink() method is available we need to import the custom JavaScript in the form's HTML Head Content:

I've described this in brief because it's not really that complicated and to describe it in full, step-by-step, would take far too long. You can see how it all fits together in the custom form in the sample database.

Summary:

What I've covered here are the basics of making the most of the HTMLArea editor. If you want to do something different then this should at least point you in the right direction to get started. Hope you enjoy it and find it useful.

Woops. Nearly forgot the sample database ;-)