Introduction

This article will explain how to integrate TinyMCE, a web-based rich text editor, into Domino. Ultimate goal is to have it working reliably in all modern browsers, and well integrated into your Domino backend. This exercise has been performed by Jake before, but needs a little updating:

• The demo database of Jake's article contains a 2 year old version of TinyMCE thats has some bugs that make it hard to get it to play nicely with the modern browsers.
• This article adds instructions on how to integrate images stored in Domino into the image selection panel of TinyMCE.
• This article will focus on an optimized integration path where you we will configure TinyMCE to include exactly the functionality we want, and where we only use the files of the TinyMCE package that we truly need.

Before I start, let me state that this article would not be possible without the help of Ben Poole. You can consider this article as our combined service to the community.

For the sake of inspiration, here is a little teaser of what an integrated TinyMCE editor looks like:

Getting started

There are two ways to integrate TinyMCE into your Domino application. One way is to store the TinyMCE source files on your server, in the domino\html directory. From then on, you can refer to these files from multiple applications. The other way is to integrate the TinyMCE source files into your database design. This article will focus on integrating the source files into the database design. The main advantage of this method is that your application will be modular and deployable to any server. The major drawback of course is that if any TinyMCE upgrades are released, you may have to apply them to multiple applications manually.

Throughout the rest of this article I will refer to my Blogo application. Blogo 1.50 has TinyMCE integrated exactly the way described in the rest of this article. So, go ahead, download Blogo 1.50, and open it in Designer.

The source files

TinyMCE consists of a lot of html, js and css files. In the Blogo design, these are stored as File design elements. Not every file of TinyMCE is included, only the ones we need to use TinyMCE's advanced theme. Two extra remarks apply:

Firefox does not recognize the css File design elements as true css files. Therefore, these File design elements have their mime type explicitly set to "text/css". This is done on the second tab of the File Resource properties box.

To enable the integration of images stored in Notes documents in the TinyMCE editor, the file "editor/themes/advanced/editor_template.js" has to be modified. The line containing "image.htm?src=" has to be replaced with "image.htm?open&src=".

This is already done in the Blogo File design elements, so if you are integrating TinyMCE in your own design, you can simply copy all these File design elements to your own design. It will save you a lot of work.

Text areas

TinyMCE basically transforms your html textarea elements into a TinyMCE editor. There are different modes to select which textarea should be turned into a TinyMCE editor. The one demonstrated appears to me as the most flexible and modular way. It tags text area elements with a HTML attribute, to indicate that it needs to be a rich text editor.

If you open up the subform "Page Edit Form" in the Blogo design, somewhere around the bottom the following line demonstrates the attribute:

<textarea rows="20" cols="70" wrap="virtual" name="pgContent" id="pgContent" class="mceEditor" style="width:100%;"></textarea>

Three elements are crucial in this line of code. First, the rows, cols, and width attributes indicate the size of the TinyMCE editor. The name attribute will link it to a rich text field with the same name. This creates the connection between the editor and the field to store the rich text content in. The class="mceEditor" part indicates that this is a TinyMCE textarea. By simply setting an attribute on a textarea we can loosely couple the TinyMCE init script, for maximum flexibility.

Note that in Blogo, the html coming from the TinyMCE editor is stored in a text field (in the Page Fields subform), not a rich text field. The reason is that Blogo does not do Notes client-based rich text editing, only web-based rich text editing. Your own implementation may vary, but integration is still straightforward if you consider the html required for the textarea, as explained above. Jake's original artice contains an agent that tranforms the TinyMCE html content into a rich text field.

The init script

The TinyMCE init script is the most important aspect of the integration process. It loads the TinyMCE editor for the selected text areas, and configues the features available in the editor. In Blogo, the initiation script is decoupled from any form you apply it to. In essence, this means that to enable the TinyMCE editor on your form, two simple steps apply:

1. Mark the text areas on your form that need to be a TinyMCE editor using the class attribute
2. Insert the "Rich Text Editor" subform at the top of your form.

Easy, right? Let's have a deep look at the initation script in the "Rich Text Editor" subform:

01. <script type="text/javascript" src="editor/tiny_mce.js"></script>
02. <script language="javascript" type="text/javascript">
03. tinyMCE.init({
04.    mode : "specific_textareas",
05.    editor_selector : "mceEditor",
06.    theme : "advanced",
07.    plugins : "table",
08.    apply_source_formatting : "true",
09.    theme_advanced_container_toolbar1_align : "left",
10.    theme_advanced_container_toolbar2_align : "left",
11.    theme_advanced_layout_manager : "RowLayout",
12.    theme_advanced_containers : "toolbar1,toolbar2,mceEditor",
13.    theme_advanced_container_toolbar1 :
14.             "bold,italic,underline,strikethrough,charmap,separator,"+
15.             "justifyleft,justifycenter,justifyright,justifyfull,"+
16.             "separator,bullist,numlist,indent,outdent,separator,"+
17.             "link,unlink,anchor,hr",
18.    theme_advanced_container_toolbar2 :
19.            "tablecontrols,separator,image,removeformat,code",
20.    theme_advanced_path : "false",
21.    remove_script_host : "true",
22.    document_base_url : "<Computed Value>",
23.    relative_urls : "true",
24.    external_image_list_url : "/<Computed Value>/pagRTEImages.js"
25.  })
26.  </script>

Since this script is so crucial for a proper integration, let's go over it line by line:

L01: Include the main TinyMCE javascript library. In Blogo, I make use of the base href tag to make use of relative paths throughout the entire design. The value of the base href tag is set to "http://server/dbpath/". If you do not use a base href tag, you should make sure that the path to the tiny_mce.js File design element is correct, whether it is absolute or relative.

L02: Start a javascript that must be executed as soon as it is loaded.

L03: Initiate the TinyMCE init call. This will only work if the path defined in line 1 is correct.

L04: This line is to indicate which text areas should be transformed to rich text editors. We do not want this for all text areas on our form, only the ones we marked as such.

L05: Indicate that all textarea elements with the attribute class="mceEditor" should be transformed to rich text editors.

L06: TinyMCE has a number of modes. The advanced mode is the one where we have maximum control over the features, so we will use that one.

L07: TinyMCE has a set of plugins to extend the functionality of the basic editor. The table features is not part of the basic functionality, therefore we load it as a plugin.

L08: TinyMCE allows you to switch to html editing mode. This setting will make sure that the HTML code is nicely formatted, making it more readable and easier to edit.

L09-L10: We will defined two rows of buttons in the editor, these two lines make sure that buttons are aligned to the left. By default, they are centered.

L11: This line puts TinyMCE in a mode where we have maximum control over the rows, buttons, order of buttons, etc.

L12: Here we specify that we have three rows: a button row, a second button row, and the TinyMCE editor pane. By naming the rows, we have control over them in the subsequent lines.

L13-L19: These lines define exactly what buttons to insert into which row of the editor. The order of buttons specified here will be respected in the end result. As you can see, you can also insert seperators to group related buttons. You may want different buttons in your own implementation. If so, please refer to the TinyMCE button/controls list.

L20: By default, TinyMCE insert a path element below the editor. The path element displays the hierarchy of html elements based on your cursor position in the editor. I wish not to bother non-technical users with this, so I disabled it.

L21: This parameter makes sure that TinyMCE does not automatically insert the server name into your relative URLs.

L22: The document base URL parameter is crucial to make your paths work. In Blogo it is set to a computed value with the following formula:

tmpProtocol:= "http" + @If(HTTPS="ON"; "s"; "");
tmpProtocol + "://" + Server_Name + "/" + @WebDBName  + "/"

You would assume that the base href tag accomplishes the same effect. The reason to still do this is that we want our TinyMCE editor to work when we create a new document and when we edit an existing document. As you can imagine the URL hierarchy in both scenarios is different:

server/dbpath/myform?openform

versus:

server/dbpath/view/docid?editdocument

Notice the extra level in the second URL. This is why we need to set the document base URL of TinyMCE.

L23: Set TinyMCE to use relative URLs. together with the two previous lines, this gives us the control over our paths that we want.

L24: By default, TinyMCE will assume that when you try to insert an image in your editor, it must pick them from the web server's file system. Since we want the list to be populated by Notes image attachments, we will set the image picklist to a Page design element, which is explained in the next section. Note that the computed value in this line is set to @WebDbName.

L25-26: End of init call and script.

Domino image integration.

As stated before, we would like TinyMCE to be able to insert images that are stored as attachments inside documents. How you implement this can be specific to your situation, but it should be easy after I explain how this is done in Blogo. 

First, as stated in line 24 of the init script, we direct the source of our images to a Page called "pagRTEImages.js". The purpose of this page is to produce a javascript array of images that TinyMCE will use in the insert image dialog box. The content type of the page is set to html. When you open it, you can see that a javascript array is setup with two elements: an embedded view and a default value (---). The format that TinyMCE expects for the image array is demonstrated in the following example:

var tinyMCEImageList = new Array(
// Name, URL
["Logo 1", "logo.jpg"],
["Logo 2 Over", "logo_over.jpg"]
);

As you can see, it is an associative array where the index is the image description and the value is the image path. The embedded view takes care of outputting this format for the image list. The view design is highly specific for your situation as your view selection and field names will differ from the ones used in Blogo. Still, the "vwResourcesRETPickList" view should give you a good start.
The first column of the view is sorted and hidden. This ensures that the array that we will output is sorted as well. The second column produces the array in the format mentioned above. In this column Blogo filters the attachments, it only allows image attachments to make it into the array. Another feature is that Blogo simulates a file system by using nested image descriptions. Three extra tips:

• The embedded view has its content type set to html, and the lines to display to 1000
• Make sure that the column formula that outputs the javascript array ends with a colon, to seperate the array elements
• Debug the format of your javascript by directly opening the Page in your browser

If all went well, you should now be able to insert Domino images into your rich text content:

Saving the rich text content

Now that we have the rich text capabilities working in the front-end, we need to make sure that upon a document save (submit), the content of the editor is saved into the Notes field. In essence, your editor is still just a textarea element,  and by setting the name attribute to the name of your Notes field, the save should work. Still, TinyMCE offers a way to enforce the content of the editor to be pushed to the underlying text area, after which Domino will do the rest. In the bottom of the "Page Edit" subform, the TinyMCE triggersave method is called:

if ( QuerySave(this.form) ){ tinyMCE.triggerSave(false,false);this.form.submit()}

Your implementation may vary, perhaps you make the call in the onsubmit event of your form. 

Conclusion

Integrating TinyMCE into your Domino application is a big usability improvement. I wrote this article in TinyMCE, and it took me about half the time it would cost if I would type it in HTML. Using this article, hopefully you will find it easy to integrate TinyMCE into your application.

Note that this article did not try to demonstrate the full feature set of TinyMCE. TinyMCE has a wealth of extra functions and ways to customize them. Consider the excellent documentation and forum for more information.

I've been skeptic about web rich text editors for years, considering their cross-browser problems and inconsistent and unreliable behavior. I have delayed implementing them in my own applications. I can now happily confirm that to me, those days are over. I fully trust this editor and I've had zero problems using it, across browsers. I hope this article convinces you to take the same step, if you have not already done so.

BOOKMARK THIS CONTENT

	Bookmark at:

RATE THIS CONTENT (OPTIONAL)

	Was this document useful to you?
	Rating:	Awesome  Good  Average  Poor  Useless

CREATE A NEW COMMENT

	Name:
	Email:
	Website:
	Content:	HTML is not allowed. Hyperlinks will automatically be converted.