Configure the Rich Text Editor plug-ins configure-the-rich-text-editor-plug-ins
RTE functionalities are made available via a series of plug-ins, each with features property. You can configure the features property to enable or disable, one or more RTE features. This article describes how to specifically configure the RTE plug-ins.
For details about the other RTE configurations, see configure Rich Text Editor.
Activate a plug-in and configure the features property activateplugin
To activate a plug-in, follow these steps. Some steps are needed only when you configure a plug-in for the first time, as the corresponding nodes do not exist.
By default, format
, link
, list
, justify
, and control
plug-ins and all their features are enabled in RTE.
rtePlugins
node is referred to as <rtePlugins-node>
to avoid duplication in this article.-
Using CRXDE Lite, locate the text component for your project.
-
Create the parent node of
<rtePlugins-node>
if it does not exist, before configuring any RTE plug-ins:-
Depending on your component, the parent nodes are:
config: .../text/cq:editConfig/cq:inplaceEditing/config
- an alternative configuration node:
.../text/cq:editConfig/cq:inplaceEditing/inplaceEditingTextConfig
text: .../text/dialog/items/tab1/items/text
-
Are of type: jcr:primaryType
cq:Widget
-
Both have the following property:
- Name
name
- Type
String
- Value
./text
- Name
-
-
Depending on the interface you are configuring for, create a node
<rtePlugins-node>
, if it does not exist:- Name
rtePlugins
- Type
nt:unstructured
- Name
-
Below this, create a node for each plug-in that you want to activate:
- Type
nt:unstructured
- Name the Plug-in ID of the plug-in required
- Type
After activating a plug-in, follow these guidelines to configure the features
property.
String
(multi-string; set Type to String
and click Multi
in CRXDE Lite)*
(an asterisk)Understand the findreplace plug-in findreplace
The findreplace
plug-in does not need any configuration. It works out of the box.
When using the replace functionality, the replace string to be replaced should be entered at the same time as find string. However you can still click find to search for the string before replacing it. If the replace string is entered after clicking find, the search is reset to the beginning of the text.
The find and replace dialog becomes transparent when find is clicked and becomes opaque when replace is clicked. The behavior allows the author to review the text to be replaced. If users click replace all, the dialog closes and displays the number of replacements made.
Configure the paste modes pastemodes
When using RTE, authors can paste content in one of the following three modes:
-
Browser mode: Paste text using the browser’s default paste implementation. It is not a recommended method as it may introduce unwanted markup.
-
Plain text mode: Paste the clipboard content as plain text. It strips all elements of style and formatting from the copied content before inserting in Experience Manager component.
-
MS Word mode: Paste the text, including tables, with formatting when copying from MS Word. Copying and pasting text from another source such as a web page or MS Excel is not supported and retain only partial formatting.
Configure Paste options available on the RTE toolbar configure-paste-options-available-on-the-rte-toolbar
You can provide some, all, or none of these three icons to your authors in the RTE toolbar:
-
Paste (Ctrl+V): Can be pre-configured to correspond to one of the above three Paste modes.
-
Paste as Text: Provides plain text mode functionality.
-
Paste from Word: Provides MS Word mode functionality.
To configure RTE to display the required icons, follow these steps.
- Navigate to your component, say for example,
/apps/<myProject>/components/text
. - Navigate to the node
rtePlugins/edit
. See activate a plug-in if the node does not exist. - Create the
features
property on theedit
node and add one or more of the features. Save all changes.
Configure the behavior of the Paste (Ctrl+V) icon and shortcut configure-the-behavior-of-the-paste-ctrl-v-icon-and-shortcut
You can pre-configure the behavior of the Paste (Ctrl+V) icon, using the following steps. This configuration also defines the behavior of keyboard shortcut Ctrl+V that Authors use to paste content.
The configuration allows for the following three types of use cases:
-
Paste text using the browser’s default paste implementation. It is not a recommended method as it may introduce unwanted markup. Configured using
browser
below. -
Paste the clipboard content as plain text. It strips all elements of style and formatting from the copied content before inserting in Experience Manager component. Configured using
plaintext
below. -
Paste the text, including tables, with formatting when copying from MS Word. Copying and pasting text from another source such as a web page or MS Excel is not supported and retain only partial formatting. Configured using
wordhtml
below.
-
In your component, navigate to
<rtePlugins-node>/edit
node. Create the nodes if the nodes do not exist. For more information, see activate a plug-in. -
In the
edit
node create a property using the following details:- Name
defaultPasteMode
- Type
String
- Value is one of the required paste mode from
browser
,plaintext
, orwordhtml
modes.
- Name
Configure the formats allowed when pasting content pasteformats
The paste-as-Microsoft-Word (paste-wordhtml
) mode can be further configured so that you can explicitly allow a few styles when pasting in Experience Manager from another program, such as Microsoft Word.
For example, if only bold formats and lists should be allowed when pasting in Experience Manager, you can filter out the other formats. This is called configurable paste filtering, which can be done for both:
For links, you can also define the protocols that are automatically accepted.
To configure which formats are allowed when pasting text into Experience Manager from another program:
-
In your component, navigate to the node
<rtePlugins-node>/edit
. Create the nodes if the node do not exist. For more details, see activate a plug-in. -
Create a node under the
edit
node to hold the HTML paste rules:- Name
htmlPasteRules
- Type
nt:unstructured
- Name
-
Create a node under
htmlPasteRules
, to hold details of the basic formats allowed:- Name
allowBasics
- Type
nt:unstructured
- Name
-
To control the individual formats accepted, create one, or more, of the following properties on the
allowBasics
node:- Name
bold
- Name
italic
- Name
underline
- Name
anchor
(for both links and named anchors) - Name
image
All properties are of Type
Boolean
, so in the appropriate Value you can either select or remove the check mark to enable or disable the functionality.note note NOTE If not explicitly defined the default value of true is used and the format accepted. - Name
-
Other formats can also be defined using a range of other properties or nodes, also applied to the
htmlPasteRules
node:
allowBlockTags
String
fallbackBlockTag
String
allowBlockTags
. Usually, p
suffices.table
nt:unstructured
remove
to remove table content and paragraph
to turn table cells into paragraphs.list
nt:unstructured
allow
(type Boolean) to define whether the pasting of lists is allowed. If allow
is set to false
, specify the property ignoreMode
(type String
) to define how to handle any list content pasted. The valid values for ignoreMode are remove
that removes list content and paragraph
that turns list items into paragraphs.An example of a valid htmlPasteRules
structure is below:
"htmlPasteRules": {
"allowBasics": {
"italic": true,
"link": true
},
"allowBlockTags": [
"p", "h1", "h2", "h3"
],
"list": {
"allow": false,
"ignoreMode": "paragraph"
},
"table": {
"allow": true,
"ignoreMode": "paragraph"
}
}
- Save all changes.
Configure text styles textstyles
Authors can apply Styles to change the appearance of a portion of text. The styles are based on CSS classes that you pre-define in your CSS style sheet. Stylized content is enclosed in span
tags using the class
attribute to refer to the CSS class. For example:
<span class=monospaced>Monospaced Text Here</span>
When the Styles plug-in is enabled for the first time, no default Styles are available. The pop-up list is empty. To provide the authors with Styles, do the following:
- Enable the Style drop-down selector.
- Specify one or more locations of the style sheets.
- Specify the individual styles that can be selected from the style pop-up list.
For later reconfigurations, say to add more styles, follow only the instructions to reference a new style sheet and to specify the additional styles.
Enable the Style drop-down selector list styleselectorlist
This is done by enabling the styles plug-in.
-
In your component, navigate to the node
<rtePlugins-node>/styles
. Create the nodes if the nodes do not exist. For more details, see activate a plug-in. -
Create the
features
property on thestyles
node:- Name
features
- Type
String
- Value
*
(asterisk)
- Name
-
Save all changes.
Specify the style sheet location locationofstylesheet
Then, specify the location(s) of the style sheet(s) you want to reference:
-
Navigate to the root node of your text component, for example,
/apps/<myProject>/components/text
. -
Add the property
externalStyleSheets
to the parent node of<rtePlugins-node>
:- Name
externalStyleSheets
- Type
String[]
(multi-string; click Multi in CRXDE) - Values The path and filename of every style sheet you want to include. Use repository paths.
note note NOTE You can add references to additional style sheets at any later time. - Name
-
Save all changes.
When using RTE in a dialog (Classic UI) You can specify style sheets that are optimized for rich text editing. Due to technical restrictions the CSS context is lost in the editor, so you can emulate this context to improve the WYSIWYG experience.
The Rich Text Editor uses a container DOM element with an ID of CQrte
that provides different styles to view and edit:
#CQ td {
// defines the style for viewing
}
#CQrte td {
// defines the style for editing
}
Specify the available Styles in the pop-up list stylesindropdown
-
In the component definition, navigate to the node
<rtePlugins-node>/styles
, as created in Enabling the style drop-down selector. -
Under the node
styles
, create a node (also calledstyles
) to hold the list being made available:- Name
styles
- Type
cq:WidgetCollection
- Name
-
Create a node under the
styles
node to represent an individual style:- Name, you can specify the name, but it should be suitable for the style
- Type
nt:unstructured
-
Add the property
cssName
to this node to reference the CSS class:- Name
cssName
- Type
String
- Value The name of the CSS class (without a preceding ‘.’; for example,
cssClass
instead of.cssClass
)
- Name
-
Add the property
text
to the same node; this defines the text shown in the selection box:- Name
text
- Type
String
- Value Description of the style; appears in the Style drop-down selection box.
- Name
-
Save the changes.
Repeat the above steps for each required style.
Configure RTE for optimal word breaks in Japanese jpwordwrap
Authors using Experience Manager to author Japanese language content can apply a style to characters to avoid line break where a break is not required. This allows authors to let the sentences break at the desired position. The style for this functionality is based on CSS class that is pre-defined in the CSS style sheet.
To create the style that authors can apply to Japanese text, follow these steps:
-
Create a node under the styles node. See specify a style.
- Name:
jpn-word-wrap
- Type:
nt:unstructure
- Name:
-
Add the property
cssName
to the node to reference the CSS class. This class name is a reserved name for Japanese word wrap feature.- Name:
cssName
- Type:
String
- Value:
jpn-word-wrap
(without a preceding.
)
- Name:
-
Add the property text to the same node. The value is the name of the style that the authors see when selecting the style.
- Name:
text
*Type:String
- Value:
Japanese word-wrap
- Name:
-
Create a style sheet and specify its path. See specify location of stylesheet. Add the following contents to the stylesheet. Change the background color as desired.
code language-css .text span.jpn-word-wrap { display:inline-block; } .is-edited span.jpn-word-wrap { background-color: #ffddff; }
Configure the paragraph formats paraformats
Any text authored in RTE is placed within a block tag, the default being <p>
. By enabling the paraformat
plug-in, you specify additional block tags that can be assigned to paragraphs, using a drop-down selection list. Paragraph formats determine the paragraph type by assigning the correct block tag. The author can select and assign them using the Format selector. The example block tags include, amongst others, the standard paragraph <p> and headings <h1>, <h2>, and so on.
<hr>
tag, can’t be assigned to a paragraph, it is not a valid use case for a paraformat
plug-in.When the Paragraph Formats plug-in is enabled for the first time, no default Paragraph Formats are available. The pop-up list is empty. To provide the authors with paragraph formats, do the following:
- Enable the Format pop-up selector list.
- Specify the block tags that can be selected as paragraph formats from the pop-up menu.
For later re-configurations, say to add more formats, follow only the relevant part of the instructions.
Enable the Format drop-down selector formatselectorlist
To enable the paraformat
plug-in, follow these steps:
-
In your component, navigate to the node
<rtePlugins-node>/paraformat
. Create the nodes if the nodes do not exist. For more details, see activate a plug-in. -
Create the
features
property on theparaformat
node:- Name
features
- Type
String
- Value
*
(asterisk)
- Name
<p>
), Heading 1 ( <h1>
), Heading 2 ( <h2>
), Heading 3 ( <h3>
).<p>
tag is removed, then the content authorcannot select the Paragraph formats option even if there are additional formats configured.Specify the available Paragraph Formats paraformatsindropdown
Paragraph formats are made available for selection by:
-
In the component definition, navigate to the node
<rtePlugins-node>/paraformat
, as created in Enabling the format drop-down selector. -
Under the
paraformat
node create a node, to hold the list of formats:- Name
formats
- Type
cq:WidgetCollection
- Name
-
Create a node under the
formats
node, this holds details for an individual format:- Name, you can specify the name, but it should be suitable for the format (for example, myparagraph, myheading1).
- Type
nt:unstructured
-
To this node, add the property to define the block tag used:
-
Name
tag
-
Type
String
-
Value The block tag for the format; for example: p, h1, h2, and so on.
You do not need to enter the delimiting angle-brackets.
-
-
To the same node add another property, for descriptive text to appear in the drop-down list:
- Name
description
- Type
String
- Value The descriptive text for this format; for example, Paragraph, Heading 1, Heading 2, and so on. This text is displayed in the Format selection list.
- Name
-
Save the changes.
Repeat the steps for each required format.
<p>
, <h1>
, <h2>
, and <h3>
) are removed. Re-create <p>
format as it is the default format.Configure special characters spchar
In a standard Experience Manager installation, when the misctools
plug-in is enabled for special characters (specialchars
) a default selection is immediately available for use; for example, the copyright and trademark symbols.
You can configure the RTE to make your selection of characters available; either by defining distinct characters, or an entire sequence.
Define a single character definesinglechar
-
In your component, navigate to the node
<rtePlugins-node>/misctools
. Create the nodes if the nodes do not exist. For more details, see activate a plug-in. -
Create the
features
property on themisctools
node:-
Name
features
-
Type
String[]
-
Value
specialchars
(or
String / *
if applying all features for this plug-in)
-
-
Under
misctools
create a node to hold the special character configurations:- Name
specialCharsConfig
- Type
nt:unstructured
- Name
-
Under
specialCharsConfig
create another node to hold the list of characters:- Name
chars
- Type
nt:unstructured
- Name
-
Under
chars
add a node to hold an individual character definition:- Name you can specify the name, but it should reflect the character; for example, half.
- Type
nt:unstructured
-
To this node add the following property:
- Name
entity
- Type
String
- Value the HTML representation of the required character; for example,
&189;
for the fraction one half.
- Name
-
Save the changes.
In CRXDE, once the property is saved, the represented character is displayed. See below the example of half. Repeat the above steps to make more special characters available to authors.
Define a range of characters definerangechar
-
Use steps 1 to 3 from Define a single character.
-
Under
chars
add a node to hold the definition of the character range:- Name you can specify the name, but it should reflect the character range; for example, pencils.
- Type
nt:unstructured
-
Under this node (named according to your special character range) add the following two properties:
-
Save the changes.
For example, define a range from 9998 - 10000 provides you with the following characters.
Figure: In CRXDE, define a range of characters to be made available in RTE
Configure table styles tablestyles
Styles are typically applied on text, but a separate set of Styles can also be applied on a table or a few table cells. Such Styles are available to authors from the Style selector box in either the Cell properties or Table properties dialog. The styles are available when editing a table within a Text component (or derivative) and not in the standard Table component.
-
Within your component navigate to the node
<rtePlugins-node>/table
. Create the nodes if the nodes do not exist. For more details, see activate a plug-in. -
Create the
features
property on thetable
node:- Name
features
- Type
String
- Value
*
note note NOTE If you do not want to enable all table features you can create the features
property as:-
Type
String[]
-
Value(s) one, or both, of the following, as required:
table
to allow the editing of table properties; including the styles.cellprops
to allow the editing of cell properties, including the styles.
- Name
-
Define the location of CSS style sheets to refer those. See Specifying the location of your style sheet as this is the same as when defining styles for text. The location may be defined if you defined other styles.
-
Under the
table
node create the following nodes as required:-
To define styles for the entire table (available under Table properties):
- Name
tableStyles
- Type
cq:WidgetCollection
- Name
-
To define styles for the individual cells (available under Cell properties),
- Name
cellStyles
- Type
cq:WidgetCollection
- Name
-
-
Create a node (under the
tableStyles
orcellStyles
node as appropriate) to represent an individual style,- Name you can specify the name, but it should reflect the style.
- Type
nt:unstructured
-
On this node create the properties:
-
To define the CSS style that is referenced,
- Name
cssName
- Type
String
- Value the name of the CSS class (without a preceding
.
, for example,cssClass
instead of.cssClass
)
- Name
-
To define a descriptive text to appear in the pop-up selector,
- Name
text
- Type
String
- Value the text to appear in the selection list
- Name
-
-
Save all changes.
Repeat the above steps for each required style.
Configure hidden headers in tables for accessibility hiddenheader
Sometimes, you may create data tables without visual text in a column header assuming that the header’s purpose is implied by the visual relationship of the column with other columns. In this case, it is necessary to provide hidden inner text within the cell in the header cell to allow screen readers and other assistive technologies to help the readers with various needs understand the purpose of the column.
To enhance accessibility in such scenarios, RTE supports hidden header cells. In addition, it provides configuration settings related to hidden headers in tables. These settings let you apply CSS styles on hidden headers in edit and preview modes. To help authors identify hidden headers in the edit mode, include the following parameters in your code:
hiddenHeaderEditingCSS
: Specifies the name of the CSS class that is applied on the hidden-header cell, when RTE is edited.hiddenHeaderEditingStyle
: Specifies a Style string that is applied on the hidden-header cell when RTE is edited.
If you specify both the CSS and the Style string in code, the CSS class takes precedence over the style string and may overwrite any configuration changes the Style string makes.
To help authors apply CSS on hidden headers in the preview mode, you can include the following parameters in your code:
hiddenHeaderClassName
: Specifies the name of the CSS class that is applied on the hidden header cell in preview mode.hiddenHeaderStyle
: Specifies a Style string that is applied on the hidden-header cell in preview mode.
If you specify both the CSS and the Style string in code, the CSS class takes precedence over the style string and may overwrite any configuration changes the Style string makes.
Add dictionaries for the spell checker adddict
When the spellcheck plug-in is activated, the RTE uses dictionaries for each appropriate language. These are then selected according to the language of the website by taking either the language property of the subtree or extracting the language from the URL; for example. the /en/
branch is checked as English, the /de/
branch as German.
A standard Experience Manager installation includes the dictionaries for:
- American English (en_us)
- British English (en_gb)
/libs/cq/spellchecker/dictionaries
, along with the appropriate ReadMe files. Do not modify the files.To add more dictionaries, if necessary, follow these steps.
-
Navigate to the page https://extensions.openoffice.org/.
-
Select the required language and download the ZIP file with the spelling definitions. Extract the contents of the archive on your file system.
note caution CAUTION Only dictionaries in the MySpell
format for OpenOffice.org v2.0.1 or earlier, are supported. As the dictionaries are now archive files, it is recommended that you verify the archive after downloading. -
Locate the .aff and .dic files. Keep filename in lowercase. For example,
de_de.aff
andde_de.dic
. -
Load the .aff and .dic files in the repository at
/apps/cq/spellchecker/dictionaries
.
Configure the history size for undo and redo actions undohistory
RTE allows authors to undo or redo a few last edits. By default, 50 edits are stored in the history. You can configure this value as required.
-
Within your component navigate to the node
<rtePlugins-node>/undo
. Create these nodes if they do not exist. For more details, see activate a plug-in. -
On the
undo
node create the property:- Name
maxUndoSteps
- Type
Long
- Value the number of undo steps you want saved in the history. The default is 50. Use
0
to completely disable undo/redo.
- Name
-
Save the changes.
Configure the tab size tabsize
When the tab character is pressed within any text a predefined number of spaces is inserted; by default this is three non-breaking spaces and one space.
To define the tab size:
-
In your component, navigate to the node
<rtePlugins-node>/keys
. Create the nodes if the nodes do not exist. For more details, see activate a plug-in. -
On the
keys
node create the property:- Name
tabSize
- Type
String
- Value the number of space characters to be used for the tabulator.
- Name
-
Save the changes.
Set indent margin indentmargin
When indentation is enabled (default) you can define the size of indent:
-
Within your component navigate to the node
<rtePlugins-node>/lists
. Create these nodes if they do not exist. For more details, see activate a plug-in. -
On the
lists
node create theidentSize
parameter:- Name:
identSize
- Type:
Long
- Value: number of pixels required for the indent margin.
- Name:
Configure the height of editable space editablespace
You can define the height of the editable space shown within the component dialog. The configuration is only applicable when using the RTE in a dialog. The configuration does not change the height of the dialog window.
-
In the
../items/text
node, in the dialog definition for the component, create a property:- Name
height
- Type
Long
- Value the height of the edit canvas in pixels.
- Name
-
Save the changes.
Configure styles and protocols for links linkstyles
When adding links in Experience Manager, you can define the CSS styles to be used and the protocols to automatically accept. To configure how links are added in Experience Manager from another program, define the HTML rules.
-
Using CRXDE Lite, locate the text component for your project.
-
Create a node at the same level as
<rtePlugins-node>
, that is, create the node under the parent node of<rtePlugins-node>
:- Name
htmlRules
- Type
nt:unstructured
note note NOTE The ../items/text
node has the property:- Name
xtype
- Type
String
- Value
richtext
The location of the ../items/text
node can vary, depending on the structure of your dialog. Two examples are/apps/myProject>/components/text/dialog/items/text
and/apps/<myProject>/components/text/dialog/items/panel/items/text
. - Name
-
Under
htmlRules
, create a node.- Name
links
- Type
nt:unstructured
- Name
-
Under the
links
node define the properties as required:-
CSS style for internal links:
- Name
cssInternal
- Type
String
- Value the name of the CSS class (without a preceding ‘.’; for example,
cssClass
instead of.cssClass
)
- Name
-
CSS style for external links
- Name
cssExternal
- Type
String
- Value the name of the CSS class (without a preceding ‘.’; for example,
cssClass
instead of.cssClass
)
- Name
-
Array of valid protocols including
https://
,https://
,file://
,mailto:
, and others,- Name
protocols
- Type
String[]
- Value(s) one, or more, protocols
- Name
-
defaultProtocol (property of type String): Protocol to be used if the user did not specify one explicitly.
- Name
defaultProtocol
- Type
String
- Value(s) one, or more, default protocols
- Name
-
Definition of how to handle the target attribute of a link. Create a node:
- Name
targetConfig
- Type
nt:unstructured
On the node
targetConfig
: define the required properties:-
Specify the target mode:
-
Name
mode
-
Type
String
) -
Value(s) :
-
auto
: means that an automatic target is chosen(specified by the
targetExternal
property for external links ortargetInternal
for internal links). -
manual
: not applicable in this context -
blank
: not applicable in this context
-
-
-
The target for internal links:
- Name
targetInternal
- Type
String
- Value the target for internal links (only use when the mode is
auto
)
- Name
-
The target for external links:
- Name
targetExternal
- Type
String
- Value the target for external links (only used when the mode is
auto
).
- Name
- Name
-
-
Save all changes.