RTE - In-place and In a Dialog

In-place Editing

When opened (with a slow double-tap/-click) the content can be edited and there is a compact toolbar with the basic options:

The full-screen version of in-place editing can be opened from the compact toolbar (content will hide page content):

Nota:

Table plugins and the source-edit feature are not available for In-place editing in Touch UI. Moreover, the Image plugin is only supported partially (drag-and-drop functionality is not available). Also, the drag-and-drop does not apply to the Full-screen mode.

Classic UI

A slow double-tap/-click on the component area will open in-place editing. The content is surrounded by an orange border:

Nota:

If you have the content finder open then a toolbar with the RTE formatting options will be shown at the top of the window area (as above).

If the content finder is not open then the toolbar will not be shown.

Editing in a Dialog

Touch-optimized UI

Not required as the functionality is covered by In-place/Full-screen editing.

Nota:

Table Plugin is not supported when editing in a Dialog in Touch UI.

Classic UI

A dialog is opened directly within the flow of the content:

Nota:

In specific scenarios this dialog can also open as a pop-up window. For example, when a Text component is part of a column structure - and space is too small for the dialog to be within the content flow.

Configure the following properties that apply to RTE in Dialog Mode (Touch-UI only):

useFixedInlineToolbar: Set this Boolean Property defined on the RTE node (one with sling:resourceType="/libs/cq/gui/components/authoring/dialog/richtext") to true, to make RTE toolbar permanently visible (even on out of area clicks) and fixed instead of floating.
When this property is true, Richtext editing is, by default, started on the "foundation-contentloaded" event.
To prevent this, set the property 'customStart' to true and trigger the 'rte-start' event to start RTE editing.
When this property is 'true', the default behaviour, rte start on click, does not work.

customStart: Set this Boolean property defined on the RTE node to true, to control when to start RTE
by triggering the event "rte-start" e.g. (Multifield Implementation)

rte-start: Trigger this event on the contenteditable-div of RTE, when to start editing RTE. This works
only if 'customStart' has been set to true.

When RTE is used in the Touch-UI dialog, setting the property useFixedInlineToolbar to true is mandatory to avoid unknown issues.

Nota:

For reference purposes, the default Text components (delivered as part of a standard installation) can be found at:

/libs/wcm/foundation/components/text

/libs/foundation/components/text

These must not be edited, but can be copied to create your own text component.

Activate a Plugin and Configure the features Property

Each plugin node can have a features property configured to activate, or deactivate, one or more features:

Nota:

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

Activating a Plugin

Nota:

These steps are only needed the first time that a plugin is explicitly configured for your component. After that the nodes will already exist.

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

Depending on your component you might need to create parent node of <rtePlugins-node> before configuring any RTE plugins:

Different UI settings are used for the inline mode and full-screen mode. The toolbar property is used to specify the buttons of the toolbar.

For example, if the button is itself a feature (e.g. Bold), it is specified as 'PluginName#FeatureName' (e.g. links#modifylink).

If the button is a popover (containing some features of a plugin), it is specified as '#PluginName' (e.g. #format).

Separators ( | ) between a group of buttons can be specified with '-'.

The popover node under inline/fullscreen contains a list of the popovers being used. Each child node under the 'popovers' node is named after the plugin (e.g. format). It has a property 'items' containing a list of features of the plugin (e.g. format#bold).

Overriding Default Features

In the standard Text component, AEM activates certain plugins and features as defaults, without them being explicitly defined (your site-specific components might set other defaults).

If you explicitly define such a plugin and its features, then your definition will override the defaults.

If for any reason you want to disable all features of a plugin that is activated per default, you can explicitly define the property features as String[] (i.e. setting the Type to String and selecting the Multi button in CRXDE Lite) with an empty list as the value.

Configuring Other Functionality of the RTE

Nota:

This section details configuration of a subset of the RTE functionality.

Styles (Text)

Styles affect the appearance of a portion of text, from a single character upwards. They are based on CSS classes (already existing in your CSS stylesheet); as they enclose a portion of text within span tags using the class attribute to reference the CSS class. For example:

Once the styles plugin is enabled you will see the Style drop-down selector in the edit dialog. However, as there are no default styles it will be either deactivated or empty.

Specifying the Location of Your Stylesheet

Then, specify the location(s) of the stylesheet(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

TypeString[] (multi-string; click Multi in CRXDE)

Value(s) The path and filename of every stylesheet you want to include.
Use repository paths; for example: /etc/designs/geometrixx/static.css

Nota:

You can add references to additional stylesheets at any later time.

Save all changes.

Nota:

When using RTE in a dialog (Editing in a Dialog - classic UI) You may want to specify stylesheets 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
}

Specifying the Styles Available in the Drop-down List

Finally, you need to specify the individual styles that can be selected from the Style drop down list in the editor:

Under the node styles, create a new node (also called styles) to hold the list being made available:

Namestyles

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

Typent:unstructured

Add the property cssName to this node to reference the CSS class:

NamecssName

TypeString

Value The name of the CSS class (without a preceding '.'; e.g. cssClass instead of .cssClass)

Add the property text to the same node; this defines the text shown in the selection box:

Nametext

TypeString

Value Description of the style; will appear in the Style drop down selection box.

Save the changes.

Repeat steps 3 to 6 for each style required.

Nota:

Steps 3 - 6 can be used at a later time to add additional styles.

Paragraph Formats

Paragraph formats determine the paragraph type by assigning the correct block tag. The author can select and assign them using the Format selector.

Nota:

Example block tags include (amongst others):

the standard paragraph <p>

headlines <h1>, <h2>, <h3>

Precaución:

This plugin is not suitable for blocks that imply a complex structure, such as lists or tables.

All text entered is placed within a block tag, the default being <p>. By enabling the paraformat plugin, you specify additional block tags that can be assigned to paragraphs, using a drop-down selection list.

Nota:

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

Specifying Paragraph Formats Available in the Drop-down List

Under the paraformat node create a new node, to hold the list of formats:

Nameformats

Typecq: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).

Typent:unstructured

To this node, add the property to define the block tag used:

Nametag

TypeString

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:

Namedescription

TypeString

Value The descriptive text for this format; for example, Paragraph, Heading 1, Heading 2, etc. This text will be shown in the Format selection list.

Save the changes.

Repeat steps 3 to 6 for each format required.

Nota:

Steps 3 - 6 can be used at a later time to add additional paragraph formats.

Precaución:

The default formats (<p>, <h1>, <h2> and <h3>) will be removed if you define custom formats (as specified above).

As <p> is the default format you must recreate this format.

The same applies to any formats that have already been used in existing content.

Special Characters

In a standard AEM installation, when the misctools plugin 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.

Precaución:

Adding your own special characters will override the default selection.

If required, you will need to (re)define these within your own selection.

Defining a Range of Characters

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.

Typent:unstructured

Under this node (named according to your special character range) add the following two properties:

NamerangeStartTypeLongValue the Unicode representation (decimal) of the first character in the range

NamerangeEndTypeLongValue the Unicode representation (decimal) of the last character in the range

Save the changes.

For example, defining a range from 9998 - 10000:

Provides you with the following characters:

Nota:

Steps 2 - 4 can be used at a later time to extend the special characters available.

Styles (Tables and Table Cells)

As well as defining styles to be used on the normal text, styles (a separate set) can also be defined for either an entire table, or for the individual cells. These will be available from the Style selector box in either the Cell properties or Table properties dialog:

Nota:

These styles will only be available when editing a table within a Text component (or derivative), not the standard Table component.

Nota:

Currently, you can define styles for tables and cells in Classic-UI only.

Nota:

Copying an pasting tables in/from RTE is browser-dependent and is not supported out of the box for all browsers. For example, when you copy or paste a table from the RTE/text component in Firefox in ClassicUI and TouchUI, the layout of the table is not preserved.

For best results, select the whole table from the end of previous paragraph to the beginning of the next paragraph below the table.

to define styles for the entire table (available under Table properties):

NametableStyles

Typecq:WidgetCollection

to define styles for the individual cells (available under Cell properties):

NamecellStyles

Typecq:WidgetCollection

Create a new node (under the tableStyles or cellStyles node as appropriate) to represent an individual style:

Nameyou can specify the name, but it should reflect the style.

Typent:unstructured

On this node create the properties:

To define the CSS style to be referenced

NamecssName

TypeString

Value the name of the CSS class (without a preceding '.'; e.g. cssClass instead of .cssClass)

To define a descriptive text to appear in the drop-down selector

Nametext

TypeString

Value the text to appear in the selection list

Save all changes.

Repeat steps 5 to 7 for each style required.

Hidden Headers (Tables)

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 differently-abled users 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 will be 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.

Adding Dictionaries for the Spell Checker

When the spellcheck plugin 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 will be checked as english, the /de/ branch as german.

Nota:

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:

British English (en_gb)

American English (en_us)

Nota:

These standard dictionaries can be found under/libs/cq/spellchecker/dictionaries
Together with the appropriate README files.

Select your required language and download the zip file with the spelling definitions.

Precaución:

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 fully test after downloading.

Extract the contents of the zip file on your local system.

Locate the files:

*.aff

*.dic

Nota:

The file name must be fully lowercase. Change from upper to lowercase if necessary.

For example, de_de.aff and de_de.dic.

Load the *.aff and *.dic files into the repository at:

/apps/cq/spellchecker/dictionaries

Nota:

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.

Nota:

The AEM RTE spell checker is based on the MySpell spell checker.

For further information please contact the Support or Sales team.

History Size for Undo/Redo

The RTE offers authors the opportunity to undo and redo the last editing steps if necessary. For a standard installation, a default of 50 steps are "remembered" in the history. You can change this value as required:

Height (of editable space)

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:

Nameheight

TypeLong

Value the height of the edit canvas in pixels

Nota:

This does not change the height of the dialog window.

Save the changes.

Formats Allowed when Pasting Content

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.