Extending Dojo Rich Text Editor's Toolbar

Notes/Domino 8.5 installs version 1.1.1 of the Dojo Toolkit1, which provides JavaScript based tooling to the browser.  One UI widget it provides is the Rich Text editor, which is used by the XPages Rich Text core control, and is an option in the 'classic' web server, when 'JavaScript' is the designated web editor for a rich text item.

Dojo's Rich Text Editor2 is a collection of functions that act on its HTML contents - many of those functions are individually packaged as 'plugins'.  Most often the functionality provided by a plugin is activated by a 'button' installed on the editor's toolbar.  The basic Dojo Rich Text Editor is the dijit.Editor class, and by default generates this toolbar:

The toolbar buttons provide access to the following functions:

Undo, Redo |
Cut, Copy, Paste |
Bold, Italic, Underline, Strikethrough |
Numbered List, Bullet List, Indent, Outdent |
Align Left, Align Right, Align Center, Justify

The Rich Text Editor in Domino 8.5 is the ibm.domino.widget.layout.DominoRichText class, which has this toolbar:

As you can see, it uses the dijit.Editor buttons and adds new buttons to provide access to the following functions:

Foreground Color, Background Color, Font, Size

 
The data\domino\js\dojo-1.1.1\dijit\_editor\plugins directory contain the plugin files for those four, and fortuitously has some others that currently are not used:

"formatBlock" - assigns css defined formats
"createLink" - constructs an anchor tag with a user supplied URL
"insertImage" - constructs an image tag with a user supplied URL

This article discusses some techniques to add those remaining plugins, and is based on material I developed for a recent talk3.  Here is the toolbar we want to generate:


 Notice the addition of buttons for the Format Block, Create Link,  and Insert Image functions.


DominoRichText.js
In order to extend the DominoRichText class we need to find it - it is in a file named DominoRichText.js, which gets shipped in 3 forms:

1) as a regular text file in the DDE (Domino Designer in Eclipse) install - for example, see C:\Program Files\IBM\Lotus\Notes\Data\domino\js\dojo-1.1.1\ibm\domino\widget\layout
2) as a layer file in the Domino server install - for example, see C:\Program Files\IBM\Lotus\Domino\data\domino\js\dojo-1.1.1\ibm\domino\widget\layout
3) as a gzip'd layer file in the Domino server install - in the same location as #2, but the file is named DominoRichText.js.gz.

#1 needs no explanation - applications under development, when served from DDE's Web Preview server, use it.  The preview server requires that the application be in DDE's local data directory.   A nice, plain source file comes in handy when developing with tools like Firebug in the Firefox browse.

#2 is the result of a 'build' step that minifies the files (strips out unused characters, like white space and comments) and then resolves all dependencies and packages them into just one 'layer' files - so you will see that the DominoRichText.js file contains the code from the dijit.Editor file.  You will also note that it's very difficult to read.

#3 is #2 gzip'd - the Domino 8.5 Web server will use this if the browser will accept it, and if the regular file is not newer than the .gz file.  The performance benefits of the build process can be seen by profiling a simple page.  To completely show a page with 2 plain text fields an d 1 rich text field takes 56 requests, and downloads 257K, when using the source files (#1) - and 1 4 requests to download 86K with gzip'd layer files (#3).   You can employ the same Dojo build processes on your controls too, but that is a large enough topic to need its own article.

Let's take a look inside DominoRichText.js from the DDE install.  It starts with the dojo.provide() statement, which registers with the dojo runtime that this class is available. 

dojo.provide("ibm.domino.widget.layout.DominoRichText");

Next, using dojo.require() statements, is the dependency list - the classes that must be available before this class is functional.

dojo.require("dijit.Editor");
...

The dojo.declare statement names this class, and shows the dijit.Editor class to be its base class, then provides a list of the members and functions in the DominoRichText class.  In the init() function, we can see how the four buttons get added to the toolbar - by calling 'addPlugin' for each of the plugins listed in the _pluginList member:

dojo.declare("ibm.domino.widget.layout.DominoRichText", dijit.Editor,
{
    _pluginList : [ "foreColor", "hiliteColor", "fontName", "fontSize" ],

    ...

    init : function drt_i()
    {
        dojo.forEach(this._pluginList, this.addPlugin, this);
    },
   
    ...

There are a number of techniques we can use to extend the toolbar using the 'extraPlugins' attribute supplied by the dijit.Editor class.  One way is to set the attribute in the html textarea tag used by the rich text editor, which works only if the dojo parser is enabled (djConfig="parseOnLoad: true").  The parser is slightly less efficient than doing it yourself programmatically, and the Dojo 'extraPlugins' attribute is not part of any HTML specification, so an HTML validator would flag it as invalid HTML
So for this article we'll stick with techniques that work the way the Domino's own DominoRichText class does it - programmatically (djConfig="parseOnLoad: false").

One other loose end we need to track:  the createLink and insertImage are dependent on UI that comes from dijit._editor.plugins.LinkDialog.


XPages
Let's create a JavaScript class in data\domino\js\dojo-1.1.1\test\widget\layout\TestRichText.js to encapsulate the LinkDialog dependency - using the dojo.require() statement.   Here's the file contents:

Save that to the TestRichText.js file.

Now we need to have the XPage which uses our rich text control instruct Dojo runtime to load our class into the browser - with a dojo.requires('test.widget.layout.TestRichText') statement.  This is done using our XPage's Properties tab, and selecting 'All Properties'.  We are interested in the 'resources' property - clicking on the plus image lets us identify our resource as a Dojo Module, and we give it our class as a value:



Then we need to put a rich text control on our XPage, exactly as if it were an ordinary rich text control, and on its Properties tab, select 'All Properties' and set the dojoType with a value of our class:


2 steps in DDE, save and run, and there's the toolbar with the new buttons!



Classic Web Server
The classic Domino web server will use the Dojo Rich Text Editor when the rich text item's web editor is set to 'JavaScript'.  It does this using some boilerplate html defined in data\domino\template\dojo-1.1.1\dom_richtext.htm.  The settings in dom_richtext.htm are server-wide, and apply to all instances of the Dojo Rich text editor, so consider carefully before releasing any changes into production.

The red text should be added to the dom_richtext.htm file, and the http task restarted:

and also

}, dojo.byId('tb&DOMINO_CTRL_FLDNAME;'));

That's also pretty easy!  We could have used our TestRichText.js file in place of the references to DominoRichText above - that would have worked as well - but it would force this to remain a server-wide setting.

What if we want the new toolbar buttons to appear only on certain forms?  Using DDE, we will need to tell each rich text item we want to display the new buttons about the 'extraPlugins' attribute.  To do that, put the value we were passing through the constructor (in red) above into the field's 'Other' property, as shown below.



Then we need to change the constructor call in dom_richtext.htm boilerplate, so it will look for the info box setting.  (in red again):

    var rte=new ibm.domino.widget.layout.DominoRichText({&DOMINO_CTRL_INFOBOX_OTHER;}, dojo.byId('tb&DOMINO_CTRL_FLDNAME;'));

Restart http, and only those rich text items we choose will display the new toolbar settings.


Now you are ready to write your own Dojo Editor plugins and use them on your Domino 8.5 servers!

References
1) http://dojotoolkit.org
2) http://docs.dojocampus.org/dijit/Editor#plugins
3) http://www.entwicklercamp.de/