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.

Примітка.

When working with CRXDE Lite, it is recommended to save the changes regularly using Save All.

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 plugins and all their features are enabled in RTE.

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:
- 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

Depending on the UI you are configuring for, create a node <rtePlugins-node>, if it does not exist:

Name rtePlugins
Type nt:unstructured

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

After activating a plug-in, follow these guidelines to configure features property.

	Enable all features	Enable a few specific features	Disable all features
Name	features	features	features
Type	String	String[] (multi-string; set Type to String and click Multi in CRXDE Lite)	String
Value	* (an asterisk)	set to one, or more, feature values	-

The findreplace plug-in does not need any configuration. It works as expected, out of the box.

The find and replace dialog becomes transparent when find is clicked and becomes opaque when replace is clicked. This allows the author to review the text that the author will replace. If users click replace all, the dialog closes and displays the number of replacements made.

When using RTE, authors can paste content in one of the following three ways. One of more or more of these options can be displayed on the RTE toolbar for the authors to use.

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 AEM 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.

Authors can also use one or more UI options enabled as part of the RTE configuration. You can configure the UI options by following these steps.

Navigate to your component; 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 the edit node and add one or more of the features.

Save all changes.

You can provide one or more of these three icons in the RTE toolbar that are:

Paste: Can be pre-configured to correspond to one of the three Paste modes.
Paste as Text
Paste from Word

You can configure RTE to display some, all, or none of these three toolbar icons. To pre-configure the behavior of the paste icon, follow these steps.

In your component, navigate to <rtePlugins-node>/edit node. Create the nodes if these 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 One of the required paste mode browser, plaintext, or wordhtml.

The paste-as-Microsoft-Word (paste-wordhtml) mode can be further configured so that you can explicitly define which styles are allowed when pasting into AEM from another program, such as Microsoft Word.

For example, if only bold formats and lists should be allowed when pasting into AEM, you can filter out the other formats. This is called configurable paste filtering.

This can be done for both:

Text
Links

For links, you can also define the protocols that are automatically accepted.

To configure which formats are allowed when pasting text into AEM from another program:

In your component, navigate to the node <rtePlugins-node>/edit. Create the nodes if these 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

Create a node under htmlPasteRules, to hold details of the basic formats allowed:

Name allowBasics
Type nt:unstructured

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.

Примітка.

If not explicitly defined the default value of true is used and the format accepted.

Other formats can also be defined using a range of other properties or nodes, also applied to the htmlPasteRules node:

Property	Type	Description
allowBlockTags	String[]	Defines the list of block tags allowed. Possible block tags include (amongst others): headlines (h1, h2, h3) paragraphs (p) lists (ol, ul) tables (table)
fallbackBlockTag	String	Defines the block tag used for any blocks having a block tag not included in allowBlockTags. p suffices in most cases.
table	nt:unstructured	Defines the behavior when pasting tables. This node must have the property allow (type Boolean) to define whether pasting tables is allowed. If allow is set to false, you must specify the property ignoreMode (type String) to define how pasted table content is handled. Valid values for ignoreMode are: remove: Removes table content. paragraph: Turns table cells into paragraphs.
list	nt:unstructured	Defines the behavior when pasting lists. Must have the property allow (type Boolean) to define whether the pasting of lists is allowed. If allow is set to false, you must specify the property ignoreMode (type String) to define how to handle any list content pasted. Valid values for ignoreMode are: remove: Removes list content. paragraph: Turns list items into paragraphs.

Example of a valid htmlPasteRules structure:

"htmlPasteRules": {
    "allowBasics": {
        "italic": true,
        "link": true
    },
    "allowBlockTags": [
        "p", "h1", "h2", "h3"
    ],
    "list": {
        "allow": false,
        "ignoreMode": "paragraph"
    },
    "table": {
        "allow": true,
        "ignoreMode": "paragraph"
    }
}

Save all changes.

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 the location(s) of the style sheet(s).
Specify the individual styles that can be selected from the Style drop down list.

For later (re-)configurations, say to add more styles, follow only the instructions to reference a new style sheet and to specify the additional styles.

Примітка.

Styles can also be defined for tables or table cells. These configurations require separate procedures.

This is done by enabling the styles plug-in.

In your component, navigate to the node <rtePlugins-node>/styles. Create the nodes if these do not exist. For more details, see activate a plug-in.

Create the features property on the styles node:

Name features
Type String
Value * (asterisk)

Save all changes.

Примітка.

Once the Styles plug-in is enabled, the Style drop-down list is displayed in the edit dialog. However, the list is empty as no Styles are configured.

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)
Value(s) The path and filename of every style sheet you want to include. Use repository paths.

Примітка.

You can add references to additional style sheets at any later time.

Save all changes.

Примітка.

When using RTE in a dialog (Classic UI) You may want to specify style sheets that are optimized for rich text editing. Due to technical restrictions the CSS context is lost in the editor, so you may want to emulate this context to improve the WYSIWYG experience.

The Rich Text Editor uses a container DOM element with an ID of CQrte which may be used to provide different styles for viewing and editing:

#CQ td {
// defines the style for viewing
}

#CQrte td {
// defines the style for editing
}

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 new node (also called styles) to hold the list being made available:

Name styles
Type cq:WidgetCollection

Create a new 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)

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.

Save the changes.

Repeat the above steps for each required style.

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.

Увага!

This plug-in is not suitable for content with complex structure, such as lists or tables.

Примітка.

If a block tag, for example an <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 drop-down selector list.
Specify the block tags that can be selected as paragraph formats from the drop-down.

For later (re-)configurations, say to add more formats, follow only the relevant part of the instructions.

First enable the paraformat plug-in:

In your component, navigate to the node <rtePlugins-node>/paraformat. Create the nodes if these do not exist. For more details, see activate a plug-in.

Create the features property on the paraformat node:

Name features
Type String
Value * (asterisk)

Примітка.

If the plug-in is not configured further, the following default formats are enabled:

Paragraph (<p>)
Heading 1 (<h1>)
Heading 2 (<h2>)
Heading 3 (<h3>)

Увага!

When configuring the paragraph formats of the RTE, do not remove the paragraph tag <p> as a formatting option. If the <p> tag is removed, then the content author can not select the Paragraph formats option even if there are additional formats configured.

Paragraph formats may be 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 new node, to hold the list of formats:

Name formats
Type cq:WidgetCollection

Create a new 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, etc.
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.

Save the changes.

Repeat the steps for each required format.

Увага!

If you define custom formats, the default formats (<p>, <h1>, <h2>, and <h3>) are removed. Re-create <p> format as it is the default format.

In a standard AEM 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 own selection of characters available; either by defining distinct characters, or an entire sequence.

Увага!

Adding your own special characters overrides the default selection. If required, (re-)define these characters in your own selection.

In your component, navigate to the node <rtePlugins-node>/misctools. Create the nodes if these do not exist. For more details, see activate a plug-in.

Create the features property on the misctools 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

Under specialCharsConfig create another node to hold the list of characters:

Name chars
Type nt:unstructured

Under chars add a new 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.

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.

In CRXDE, add a single character to be made available in the RTE toolbar

Use steps 1 to 3 from Defining a Single Character.

Under chars add a new 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:

Name rangeStart
Type Long
Value the Unicode representation (decimal) of the first character in the range
Name rangeEnd
Type Long
Value the Unicode representation (decimal) of the last character in the range

Save the changes.

For example, define a range from 9998 - 10000 provides you with the following characters.

In CRXDE, define a range of characters to be made available in RTE

Special characters available in RTE are displayed to authors in a pop-up window

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.

Примітка.

You can define styles for tables and cells for Classic UI only.

Примітка.

Copying and pasting tables in or from RTE component is browser-dependent. It is not supported out of the box for all browsers. You may get varied results depending on table structure and browser. For example, when you copy and paste a table in a RTE component in Mozilla Firefox in Classic UI and Touch UI, the layout of the table is not preserved.

Within your component navigate to the node <rtePlugins-node>/table. Create the nodes if these do not exist. For more details, see activate a plug-in.

Create the features property on the table node:

Name features
Type String
Value *

Примітка.

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

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 new nodes (as required):

To define styles for the entire table (available under Table properties):
- Name tableStyles
- Type cq:WidgetCollection
To define styles for the individual cells (available under Cell properties):
- Name cellStyles
- Type cq:WidgetCollection

Create a new node (under the tableStyles or cellStyles 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 to be referenced
- Name cssName
- Type String
- Value the name of the CSS class (without a preceding '.'; for example, cssClass instead of .cssClass)
To define a descriptive text to appear in the drop-down selector
- Name text
- Type String
- Value the text to appear in the selection list

Save all changes.

Repeat the above steps for each required style.

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.

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.

Примітка.

The message "Spell checking failed." is seen if a check is tried for a language that is not installed.

A standard AEM installation includes the dictionaries for:

American English (en_us)
British English (en_gb)

Примітка.

The standard dictionaries are located at /libs/cq/spellchecker/dictionaries, along with the appropriate readme files. Do not modify the files.

To add more dictionaries, if required, 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.

Увага!

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 and de_de.dic.

Load the .aff and .dic files in the repository at /apps/cq/spellchecker/dictionaries.

Примітка.

The RTE spell checker is available on-demand. It does not run automatically as you start typing text.

To run the spell checker, tap/click the Spellchecker button from the toolbar. RTE checks the spelling of words and highlights mis-spelled words.

If you incorporate any change that the spell checker suggests, the state of the text changes and mis-spelled words are no longer highlighted. To run the spell checker, tap/click Spellchecker button again.

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 disable undo/redo completely.

Save the changes.

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 these 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

Save the changes.

When indentation is enabled (default) you can define the size of indent:

Примітка.

This indent size is only applied to paragraphs (blocks) of text; it does not affect the indentation of actual lists.

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 the identSize parameter:

Name: identSize
Type: Long
Value: number of pixels required for the indent margin

Примітка.

This is only applicable when using the RTE in a dialog (not in-place editing - classic UI).

You can define the height of the editable space shown within the component dialog:

On the ../items/text node in the dialog definition for the component, create a new property:

Name height
Type Long
Value the height of the edit canvas in pixels

Примітка.

This does not change the height of the dialog window.

Save the changes.

When adding links in AEM, you can define:

The CSS styles to be used
The protocols automatically accepted

To configure how links are added in AEM from another program, define the HTML rules.

Using CRXDE Lite, locate the text component for your project.

Create a new 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

Примітка.

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 include:

/apps/<myProject>/components/text/dialog/items/text
/apps/<myProject>/components/text/dialog/items/panel/items/text

Under htmlRules, create a new node.

Name links
Type nt:unstructured

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)
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)
Array of valid protocols (including http://, https:// file://, mailto:, amongst others)
- Name protocols
- Type String[]
- Value(s) one, or more, protocols
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
Definition of how to handle the target attribute of a link. Create a new 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 or targetInternal 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)
- The target for external links:
  - Name targetExternal
  - Type String
  - Value the target for external links (only used when the mode is auto).

Save all changes.

Інші схожі матеріали

Юридична інформація | Політика мережевої конфіденційності

Configure the Rich Text Editor plug-ins

Activate a plug-in and configure the features property

Understand the findreplace plug-in

Configure the paste modes

Configure Paste options available on the RTE toolbar

Configure the behavior of the Paste(Ctrl+V) option on the RTE toolbar

Configure the formats allowed when pasting content

Configure text styles

Enable the Style drop-down selector list

Specify the style sheet location

Specify the available Styles in the pop-up list

Configure the paragraph formats

Enable the Format drop-down selector

Specify the available Paragraph Formats

Configure special characters

Define a single character

Define a range of characters

Configure table styles

Configure hidden headers in tables for accessibility

Add dictionaries for the spell checker

Configure the history size for undo and redo actions

Configure the tab size

Set indent margin

Configure the height of editable space

Configure styles and protocols for links

Інші схожі матеріали

Спитайте спільноту

Зверніться до нас