In the Notes/Domino 8.5.2 release, CKEditor
has been integrated into XPages and it is now used as the default rendering for the XPages Rich Text Control. CKEditor is a WYSIWYG editor and it provides a wide range of features for creating and editing rich text content. As well as the basic styling options for text, it is also possible to add tables, links and emoticons to your rich text content. CKEditor has also been enhanced within XPages to allow you to embed images directly within your Domino documents.
CKEditor 18.104.22.168 is included in both the Notes Client and the Domino server in the 8.5.2 release. The install files can be found in /domino/html/ckeditor and /domino/html/ckeditor respectively.
This document will highlight some of the main features of the editor and discuss how it can be configured in different ways to suit your needs.
Firstly, the editor comes with 3 predefined toolbars - Slim, Medium and Large as shown in figure 1. These toolbars provide varying levels of functionality which may be useful in different scenarios e.g full document editing, blog posts, comments etc.
(See attached file: toolbars.gif)
Figure 1: 3 Available Toolbars for CKEditor in XPages
The Medium toolbar is used by default in XPages but you can easily configure the Rich Text Control to use either the Slim or Large toolbars as follows:
In Domino Designer, select the Rich Text Control in the Design View. Click the Dojo tab on the Properties panel and add a Dojo attribute named toolbarType with a value of Slim, Medium (default), or Large as shown in Figure 2.
Figure 2: Configuring the ToolbarType for CKEditor in XPages
CKEditor includes many features that are new to XPages in 8.5.2. Table 1 highlights some of these.
Table 1: Rich Text Editing Features New to XPages in 8.5.2
|Maximize||Allows you to expand the editor area to the full browser window. This is particularly useful when creating and editing large documents.|
|Link||Provides a 'URL Link' dialog which allows you to Insert URLs into the document body. You can also provide alternative text to display within the document and specify whether the link should open in a new window or not.|
|Insert Image||Provides a dialog which allows you to browse your file system to select the image you wish to insert into your document. Alternatively you can enter a URL to a remote image on the 'Image Information' tab.|
|Insert Table||Provides a dialog which allows you to insert a table into the document. You can specify various table properties such as number of rows, number of columns, width, height etc.|
|Insert Emoticons||Provides a dialog which provides a number of emoticons which you can select to insert into your document.|
|Paste||Provides a range of pasting options including 'Paste' which provides Ctrl+v paste functionality, 'Paste as plain text' which removes formatting from the pasted content, 'Paste Special' which supports pasting of rich text content from desktop editing programs that copy HTML content to the clipboard and 'Paste Notes Document Link' which allows you to paste a document link from Notes into the CKEditor. |
var myToolbar = "[['Font','FontSize'], \n"
+"['Preview', 'Bold','TextColor','BGColor'], \n"
Figure 3: User Defined CKEditor Toolbar in XPages
The CKEditor install in Notes/Domino 8.5.2 does provide some extra plugins that are not available in any of the default toolbars in XPages. You can enable these extra plugins through the toolbar Dojo attribute as described above, however please note that they are not officially supported in XPages. For example, in the usecase above, the 'preview' plugin is enabled, therefore we can add 'Preview' to the toolbar. Other additional plugins provided by CKEditor include 'templates' (toolbar option: 'Templates') which allows you to define HTML templates for rich text documents, 'selection' (toolbar option: 'SelectAll') which allows you to provide a 'Select All' feature and 'print' (toolbar option: 'Print') which allows users to print the document from directly within the editor,
If you do wish to use any of these additional plugins, you first need to make sure that the plugin is loaded. You can inspect the config.plugins property of your CKEditor instance in the DOM to see what plugins are available (using Firebug for example). If the plugin you require is not loaded, you can load it using the extraPlugins Dojo attribute. Add a Dojo attribute to the Rich Text Control called extraPlugins. The value of this should be a comma separated list of any extra plugins you wish to load.
Examples of other configuration options you can set on CKEditor include language which defines the user interface language to use, contentsLangDirection which defines the direction in which the text is entered into the editor area and enterMode which defines the behaviour of the enter key. Figure 4 shows a sample Rich Text Control in Domino Designer which have these properties set.
Figure 4: CKEditor Configuration Options in XPages
In addition, CKEditor in Notes/Domino 8.5.2 comes with 3 available skins specified in /domino/html/ckeditor/skins. XPages supports the lotus skin. The other 2 skins are included as samples and may not be maintained or available in future CKEditor releases. If you would like to create your own skin, you can do so by defining it in the same format as the ones provided. See documentation on CKEditor Skins for further details on this.
You can then apply your new skin to CKEditor in XPages by adding a skin Dojo attribute. Note - there is currently an open issue in CKEditor which requires all skins to be in the /data/domino/html/ckeditor/skins directory. This issue has been reported and it should be possible to use custom paths for skins in future releases.
For further details of the CKEditor.config properties and their possible values, please see the CKEditor API.