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 22.214.171.124 is included in both the Notes Client and the Domino server in the 8.5.2 release. The install files can be found in <Notes data dir>/domino/html/ckeditor and <Domino data dir>/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
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.
Figure 1: 3 Available Toolbars for CKEditor in XPages
toolbar is used by default in XPages but you can easily configure the Rich Text Control to use either the Slim
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
(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. |
property of the Rich Text Control primarily maps to the CKEDITOR.config properties as specified in the CKEditor API
. This means that CKEditor can be configured in a number of different ways within your XPages applications.
For example, instead of using the predefined toolbars mentioned earlier, you can also define your own toolbar for CKEditor. To define your own toolbar, add a Dojo attribute to the Rich Text Control called toolbar.
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
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.