Applies to Pega Platform versions 7.1.8 through 8.4
The Pega Platform Rich Text Editor (RTE) is an implementation of CKEditor. Troubleshooting RTE issues in the Pega Platform requires an understanding of some basic concepts and design decisions. The information in this article informed the solutions of commonly reported problems.
Copy-Paste issues with Microsoft Word and Excel
Operating system and browser support for Copy-Paste with Microsoft Word and Excel
Operating system and browser support for Copy-Paste of images
RTE ESC+Tab control for ADA Section 508 compliance
RTE does not display in pop-up windows
RTE in read-only mode without toolbar increases line break space
Font size reverts to initial size in RTE
Custom plugin to auto generate the RTE
Custom plugin for Pega client-side event handlers
OperatorID specifies the language locale
Spell checker Supplemental Dictionaries
Types of Rich Text Editors
Classic Rich Text Editor
When you add a Rich Text Editor (RTE) control to a section, the Presentation tab of the RTE Cell Property panel shows Classic, which is the default RTE type selected. Classic RTE is rendered in an iframe and by default supports all the CKEditor plugins and the Pega RTE plugins. Classic RTE is heavy-weighted because it uses a separate iframe within the parent window to render. Classic RTE is recommended if you are using all features of the RTE, including plugins.
Lightweight Rich Text Editor
Change the RTE to Lightweight by changing the RTE Type in the Presentation tab of the RTE Cell Property panel. Lightweight RTE, also known as the Inline Editor, can help to control memory leaks because the RTE is rendered in <div> rather than <iframe> elements. The Lightweight RTE supports the CKEditor plugins, but it does not support some of the Pega RTE plugins, which depend on the <iframe> element. Be aware of this limitation when choosing Lightweight RTE. Lightweight RTE is recommended if you are using the RTE for text editing only.
Memory leaks
If you discover a memory leak with the RTE, Change the type of RTE to Lightweight and check the memory readings.
Copy-Paste issues with Microsoft Word and Excel
Operating system and browser support for Copy-Paste with Microsoft Word and Excel
Using Pega Platform versions 8.1, 8.2, 8.3, and 8.4, you can copy content from Microsoft Word documents and Microsoft Excel spreadsheets and paste copied content into the RTE. Paste actions are supported on macOS and Windows operating systems and industry-standard browsers (Chrome, Firefox, Safari, Internet Explorer, Edge).
- From Microsoft Word, you can paste into the RTE the following content:
- Text
- Images
- Text and Images
- Tables
- From Microsoft Excel, you can paste any content into the RTE.
Exceptions
The following actions are not supported, as expected, based on the CKEditor 4 demo:
- Dragging an image from Microsoft Word is not supported.
- Pasting Microsoft Excel content into the RTE using the Firefox browser on the macOS operating system succeeds partially: Pasted Excel content does not retain its styles in the RTE. (This exception does not apply to using Firefox on Windows.)
See also Pega Platform Client Operating System and Browser Support.
Copy-Paste issues with images
If you upload an image using the RTE control, the image is saved as Data-Content-Image and a reference to the image is appended to the source of the rendered RTE control.
However, if you Copy-and-Paste or Drag-and-Drop the image, then the RTE control creates a base64 code of the image and appends the image directly in the source of the RTE.
Operating system and browser support for Copy-Paste of images
Using Pega Platform versions 8.1, 8.2, 8.3, and 8.4, you can copy images and paste them into the RTE. Pasting images is supported on macOS and Windows operating systems and industry-standard browsers (Chrome, Firefox, Safari, Internet Explorer, Edge). The following actions for images contained in both <iframe> or <div> elements are supported:
- Copy and paste from Microsoft Word (text and image)
- Copy and paste from a web page (text and image)
- Copy and paste from the file system
- Drag and drop from Microsoft Word
- Drag and drop from a web page
- Drag and drop from the file system
Exceptions
The following actions are not supported, as expected, based on the CKEditor 4 demo:
- Drag and drop from Microsoft Word does not work.
- On Windows with the specified browsers, the following actions do not work:
- Chrome: Copy and paste from file system
- Edge: Copy and paste from the file system
- Internet Explorer: Copy and paste from Microsoft Word (text and image)
You can copy and paste text or copy and paste the image, but not both. - Internet Explorer: Copy and paste from the file system
- Internet Explorer: Drag and drop from a web page
See also Pega Platform Client Operating System and Browser Support.
Focus behaviors
RTE ESC+Tab control for ADA Section 508 compliance
RTE toolbar focus with Alt+10
When you are working in the editable area of the RTE, click Alt+F10 to focus on the toolbar. The RTE focus always goes to the first button or icon in the RTE toolbar. The CKEditor code that handles the Alt+F10 shortcut does not check to see if the first button or icon in the RTE toolbar is visible. If the button or icon is set to Display=None with a custom style or in the RTE property panel, it is not displayed in the RTE toolbar. Consequently, the RTE focus stays in the editable area of the RTE. See the latest CKEditor code in GitHub (Line #17):
https://github.com/ckeditor/ckeditor4/blob/887aa0903de249eb832c8a18704f9491862e828a/plugins/toolbar/plugin.js#L17
To customize the RTE toolbar focus to work around this issue, use the following JavaScript code in the harness where this behavior is necessary:
pega.u.d.attachOnload(function(){
if(window.CKEDITOR){
window.CKEDITOR.on("instanceReady",function(ev){
if(ev && ev.editor){
ev.editor.getCommand("toolbarFocus").exec = function(){
if ( ev.editor.toolbox ) {
ev.editor.toolbox.focusCommandExecuted = true;
$(".cke_button__spellcheck").focus();
}
};
}
});
}
},true);
This code defines the RTE toolbar focus command, on editor creation, to focus on the Spell Check button.
If this code is used in UserWorkForm, RTE instances everywhere are affected. Consider restricting this code to the harness where it is needed.
RTE ESC+Tab control for ADA Section 508 compliance
Users have reported that using the Tab key in the RTE does not work as expected. Application developers have enabled the Accessibility ruleset (PegaWAI). However, using the Tab key moves the focus directly to the text editing area. For compliance with ADA Section 508 accessibility standards, users expect the focus to reach the border of the RTE.
To work around this issue, users should select ESC+Tab. This keystroke combination moves the focus out of the RTE text editing area, allowing users to navigate by the Tab key through the entire RTE.
RTE does not display in pop-up windows
The RTE field does not display when it is configured for pop-up window. The same RTE field displays when it is configured on other screens other than the pop-up window. This functionality worked as expected in Pega Platform version 7.4. Users reported this problem after upgrading to Pega Platform version 8.1.2. This regression was fixed in Pega Platform version 8.2.2.
RTE in read-only mode without toolbar increases line break space
Users report that when they display the RTE content in a modal dialog in read-only mode without the toolbar, the line break space increases. This problem occurs in Internet Explorer 11 only.
To resolve this problem, add the following code to the UserWorkForm:
<style>
.modal-content p {
padding-bottom: 0em !important;
}
Font issues
By default, font family and size are not set for editing content in the Rich Text Editor. Use the toolbar options to set the font family and its size. There are also options for Copy Format and Remove Format.
Font size reverts to initial size in RTE
See Pega Platform version 7.1.8 SA-77734, Font size reverts to initial size on Rich Text Editor.
Non-ASCII characters
The Rich Text Editor control, unlike the Text Area control, submits HTML markup as the value for the property, not the plain text. For example, if the RTE content contains a bullet element, the RTE control submits the corresponding HTML markup, which includes <ul> and <li> markup tags. It performs HTML encoding for special characters; therefore, when you type non-ASCII characters into the RTE, it encodes them and posts the value, causing these characters to display incorrectly in the RTE.
To work around this issue, try to write the non-ASCII text in a way that the HTML encoding mimics ASCII text.
Localizing the RTE
The RTE does not follow the standard Pega localization process because the CKEditor markup is built on the client by the CKEditor JavaScript. CKEditor UI translations are done in a different manner compared to other Pega UI components.
To localize the RTE, you create a custom language extension by editing a copy of the Pega JavaScript rule pypega_ckeditor_lang_extn.js.
To localize the RTE into a non-English language, complete the following steps:
- SaveAs the Available rule pypega_ckeditor_lang_extn.js.
- Add your own language entry using the following format shown for English.
Complete the format within the comments in the JavaScript (.js) file:/*CKEDITOR.lang['en'] = {--------undo :{redo : 'Redo',undo : 'Undo'},--------};*/ - Replace the English values with the corresponding values of the non-English language.
The following example shows values for German.CKEDITOR.lang['de'] = {--------undo :{redo : 'Wiederherstellen',undo : 'Rückgängig'},--------};
As an alternative to writing your own language entries, you can use the localized samples that are available from the CKEditor website.
To get localized RTEs from the CKEditor website, complete the following steps:
- Go to http://ckeditor.com/builder
- Choose preset Standard.
- Select your plugins and skin.
- Finalize and download the languages you need for the RTE.
- Select the Optimized option.
- Click Download CKEditor <available version>.
- Extract the downloaded .zip file.
- Go to the \lang folder.
- Open the appropriate lang.js file in that folder.
- Replace the values of the pypega_ckeditor_lang_extn js commented template with the localized values of the lang.js file from the CKEditor.
Pega plugins for the RTE
pzpega_ckeditor_pegaPlugins holds the custom Pega plugins created for the RTE:
InsertProperty, InsertRule, SmartInfo
Refer to this file if you see any issues with these plugins.
RTE Spell Check is a custom Pega plugin developed for the RTE. See RTE spell checker.
Custom plugins for the RTE
A plugin definition needs to be added into the map associated with the name of the plugin. You can create custom plugins for the RTE by adding the plugin definition entry to the plugin map pega.u.d.customRTEPlugins and then creating functions to initialize the plugin and execute the commands.
A new singleton pega.ui.RTEPluginManager offers methods to load and return the list of custom RTE plugins.
The plugin definition should contain a method called init, which gets called on plugin initialization. Inside this method, you can add commands and buttons.
A command is a named operation to be performed. The editor instance is available as the parameter to the command's exec method. Any of the CKEditor API (CKEditor 4 Documentation) and other JavaScript code can be executed from within the command's exec method.
A button is a toolbar component. Each button must be associated with a command. When user’s click the button, the associated command's exec method is called.
Custom plugin to auto generate the RTE
One example of a custom plugin is a plugin to auto generate the RTE. The code sample is provided below.
In this code sample, MyCustomPlugin is the name of the plugin.
pega.u.d.customRTEPlugins = pega.u.d.customRTEPlugins || {}; /* Initialize the map if not initialized already. */
pega.u.d.customRTEPlugins["MyCustomPlugin"] = {
init: function(editor) {
editor.addCommand("cmdSayHello", {
exec: function(editor) {
alert("HELLO!");
}
});
editor.addCommand("cmdSayBye", {
exec: function(editor) {
alert("BYE!");
}
});
editor.ui.addButton("SayHello", {
label: "Say Hello",
command: "cmdSayHello",
icon: "webwb/pztick.png"
});
editor.ui.addButton("SayBye", {
label: "Say Bye",
command: "cmdSayBye",
icon: "webwb/pzcross.png"
});
},
buttons: ["SayHello", "SayBye"]
};
Custom plugin for Pega client-side event handlers
Only the onChange event is supported in the Pega RTE control.
If you need to support other events such as keypress, keydown, and keyup, you need to write your own event handlers for the RTE control.
- Get the HTML element of the RTE control on which you want to bind some event handler, and then do the binding as shown in the following code sample.
$(the_RTE_Control_element).on(“keyup”,handler);
- Set the window.startupShowBorders:
- true to show dotted-borders on RTE render
- false to not display borders
- By default, the RTE control generates the <para> tag for simple entered text.
To remove this, setwindow.autoParagraph = false; - By default, the RTE control for Images uses double-click to open a dialog.
To stop opening a dialog on RTE Image with double-click, setwindow.removeRTEImageDialog = true. - When you want the RTE to act like a chat window, and if it contains an image, users can open the Image property by double-clicking it.
To remove this functionality, setwindow.removeRTEImageDialog = true.
Read-only rich text
Use the RichTextDisplay control to display the read-only rich text content. This control also filters the script tags and blocks XSS threats. The container that specifies RichTextDisplay controls content wrapping.
If you encounter issues with content wrapping, verify the CSS styles and classes on the container having the <div>, for example, the dynamic layout. Try adding some styles directly in the DOM and verify that the content is wrapped.
RTE spell checker
Browser spell checking
OperatorID specifies the language locale
RTE spell checker properties
Browser spell checking
By default, browser spell check functionality is disabled in Pega applications. If you want to enable native browser spell checking, complete the following steps:
- In UserWorkForm, set the
window.disableNativeSpellCheckeroption tofalseto enable it. - If the Context Menu plugin is enabled, users must select and hold the Ctrl key when right-clicking misspelled words to see the suggested corrections.
OperatorID specifies the language locale
Spell check works on the locale of the operator (OperatorID).
If the locale of the operator is not set, then the locale specified by the operating system is used by default.
Sometimes a JSON parsing error in the console is triggered when users are checking spelling in the RTE. If this error occurs, check the operator locale and set it to the correct locale by editing the Operator ID record.
- Open the Operator ID record in Edit mode.
- In the Profile tab, go to the Localization section.
- See the Default locale field.
- Change this field’s value to the correct locale.
- Select the one of the values from the Time Zone field to auto-populate the Default locale field.
The following languages are supported for localizing the RTE spell check.
- English
- German
- French
- Portuguese
- Spanish
- Italian
- Dutch
RTE spell checker properties
Spell checker Dictionaries
Spell checker Supplemental Dictionaries
Spell checker behavior
The language dictionary used by the Pega RTE, which is an implementation of CKEditor, is not a Pega rule but the CKEditor files, which are not editable.
Spell Checker properties are the Pega records that you can edit to specify spell checking behavior and manage the lexicon.
To work with the Spell Checker properties, click
Spell checker Dictionaries
Under the first tab, Dictionaries, you see three sections:
- Main, which specifies the name of the language dictionary
- Supplemental, which specifies the names for words added to the language lexicon. You can also remove words from the language lexicon.
- User specifies the user.
Spell checker Supplemental Dictionaries
- The supplementals are the Pega rules that control the addition or removal of words in the lexicon for the language.
- These files are editable: You can add or remove words from them.
For more information, see Spellchecker Properties form, Completing the Dictionaries tab.
Spell checker behavior
In the SpellChecker Properties window, click the Properties tab and set the properties that control spell checking behavior for the application users. For more information, see Spellchecker Properties Form, Completing the Properties tab.
Related Content
Specifying presentation options for a Rich text editor control
Adding and configuring a Rich text editor control
Converting plain text to rich text