Updated: February 14, 2018

Rich Text Editor

sap.ui.richtexteditor.RichTextEditor

Intro

The rich text editor (RTE) is a complex control for data input and editing. It allows users to format the text and insert different types of elements within the text, such as images and hyperlinks.

The rich text editor uses the third party component TinyMCE. In addition to the native toolbar, you can also use a toolbar built with SAPUI5 controls. This custom toolbar acts as a wrapper around the native toolbar and takes care of synchronizing the state of the internal controls with the current state of the selection in the editor.

Rich text editor
Rich text editor

Usage

Use the rich text editor if:

  • You want to enable users to enter rich text with different styles and colors.
  • You need to provide an instrument for texts that require additional formatting.

Do not use the rich text editor if:

  • You want to let users add simple text that doesn’t require formatting. Use text area instead.
  • Your app will be used mainly on mobile devices. If your use case requires the rich text editor, you should define a fallback solution.

Responsiveness

Due to technical limitations, the rich text editor is only available for desktop devices. However, it still displays smoothly on mobile devices.

Overflow Behavior

On smaller screens, the custom toolbar utilizes the overflow behavior of the standard SAP Fiori toolbar.

If the available actions do not all fit into the available space in the toolbar, the extra actions disappear from the visible part of the toolbar from right to left, and an overflow menu button appears on the right of the toolbar. Clicking the overflow button reveals the hidden options.

Each action has a priority, which determines whether and when the action moves into the overflow menu. You can prioritize the actions in the toolbar by applying one of five statuses:

  • Always overflow: The action always goes into the overflow.
  • Disappear: An action that is not so relevant for the user can disappear if the space is limited.
  • Low: Actions with the priority “Low” overflow first. Assign this status to actions the user rarely needs.
  • High: Actions with priority “High” remain visible in the toolbar until all lower-priority actions have moved to the overflow. Lower-priority actions are those with the priorities “Disappear” or “Low”, and all unprioritized actions.
  • Never overflow: These actions are always visible in the toolbar.
Size S
Size S
Size M
Size M
Size L
Size L

Layout

The richt text editor has two main components – the toolbar and the content area.

  • Toolbar: All available actions are displayed in the toolbar. App development teams can add or remove individual action groups, depending on the use case.
  • Content area: The content area is where users create their text. It visualizes all the changes made using the actions in the toolbar.
Schematic visualization of the rich text editor
Schematic visualization of the rich text editor

Toolbar Types

The rich text editor comes with two types of toolbar: the common TinyMCE toolbar and the custom toolbar.

The first image shows the default (native) toolbar, which comes with its own behavior for smaller screens.

Rich text editor - Native TinyMCE toolbar
Rich text editor - Native TinyMCE toolbar

The next image shows the custom toolbar, which includes common SAP Fiori controls and utilizes the overflow toolbar behavior. All common actions provided by the native toolbar are also offered by the custom toolbar.

Rich text editor - Custom SAP Fiori toolbar
Rich text editor - Custom SAP Fiori toolbar
Developer Hint
You can decide which toolbar to use. Please bear in mind that the type of toolbar is only considered when control is being initialized. It cannot be changed during runtime because of lifecycle incompatibilities between SAPUI5 and the third-party library.

Actions in the Custom Toolbar

The custom toolbar includes most of the native TinyMCE actions. The actions are separated into several virtual groups. You can hide each group of actions individually if it is not required by the use case.

Rich text editor - Actions in the custom toolbar
Rich text editor - Actions in the custom toolbar
  • Font styles group: This group contains four actions (Bold, Italic, Underline, and Strikethrough) that can be applied to individual symbols. All of the actions can be combined, which means that a preselected text can be bold, italicized, underlined, and crossed out at the same time.
  • Text alignment: Changes the alignment of the text. The available alignments are Left, Right, Center, and Justify. By default the text is left aligned. The selected style is applied to the entire paragraph.
  • Font family: Changes the font family of the text. All the available fonts are displayed in a select control. 17 font families are supported, including popular fonts like Verdana, Tahoma, Arial, Times New Roman, and Helvetica.  The change is applied to individual symbols.
  • Font size: Changes the size of the text. All available font sizes are displayed in a select control. The minimum size is 8 pt and the maximum size is 36 pt. The change is applied to indivdual symbols.
  • Font color: Opens a color picker dialog to change the color of the text. The default text color is black.
  • Background color: Opens a color picker dialog to change the color of the background. The default background color is white.
  • Structure group: Includes the the “Lists” and “Text indent” subgroups.
    • Lists: There are two types of list, Bulleted List and Numbered List. This action is applied at paragraph level and turns a normal paragraph into a list. The two list types cannot be applied simultaneously.
    • Text indent: This action group lets users increase or decrease the indentation of the text.
  • Edit group: This action group includes Cut, Copy, and Paste actions.
  • Insert table: Inserts a simple table within the content area.
  • Headings and styles: Offers a list of predefined styles, including 6 heading levels and a paragraph. The default style is Paragraph.
  • Custom action: If the use case requires an action that is not available in the set of common actions, you can attach an external plugin to the custom action. Technically, you can add as many custom actions as you like. However, because custom actions are displayed after the common actions, we recommend keeping the number of custom actions down to a reasonable level.
Developer Hint
The rich text editor is actually an SAPUI5 wrapper around the open source TinyMCE editor. TinyMCE’s functionality can easily be extended using plugins, which can also be attached to the custom toolbar.

The general approach for enabling 3rd-party TinyMCE plugins for the rich text editor is:

  1. Create or find a plugin.js file and place it in convenient place in your application. Alternatively, define the plugin directly in your code.
  2. Load or call the plugin after the TinyMCE core library has loaded. This can be done in the rich text editor’s beforeEditorInit hook.
  3. Add the plugin to the TinyMCE instance.
    • If you’ve defined the plugin directly in your code (synchronous), you can also enable the plugin in the beforeEditorInit hook.
    • If the plugin is in external file and is loaded asynchronously, the plugin should be registered in the instance when the plugin file is downloaded. A convenient place to enable the plugin is the rich text editor’s ready or readyRecurring event.
  4. Optional: If the rich text editor is instantiated with the custom toolbar, be sure to add a custom button to it to make the functionality available.

Important: Third-party plugins are not supported by SAP. We cannot guarantee that there will not be any issues with their enablement.

Behavior and Interaction

General Information

The rich text editor is available only in edit mode of the floorplan it is displayed in. In display mode the content is shown as it is formatted by the user. The user-defined formatting cannot be overwritten.

The toolbar always visible and the user has access to all the action groups. To start typing, the user has to click or tap inside the content area.

To apply any of the actions from the toolbar, the user has to select the text to be formatted upfront.

Some of the actions can be preselected and applied prior to typing the text. These actions are:

  • Font family, font size and styling (bold, italic, underline)
  • Paragraph alignment
  • Color selection (font color and background color)

Font Styles

The user selects the font style using the respective icon toggle buttons (Bold, Italic, Underline, Strikethrough). The style is applied to a preselected text, and remains active until the user clicks the button again or moves the marker to an area where a different style is applied, or no style is applied.

Alignment

The user can change the alignment of the text (Left, Right, Center, Justify).

By default the text is left-aligned. The selected style is applied to the entire paragraph. To apply any of the styles, the user must select the text and then to click on the Align Text select button  . It is also possible to select the alignment upfront, but in this case only the text written after the selection will have the desired alignment.

Font Family

The user selects the desired font family from a list of all available font families. The selected font family can be applied to a preselected text, or selected upfront.

Font Size

The user selects the desired font size from a list of font sizes from 8 pt to 36 pt. The selected font size can be applied to a preselected text, or selected upfront.

List Types

The user can create two types of lists, both of which are triggered by toggle buttons: bulleted lists  and numbered lists  . List formatting is applied at paragraph level. To apply list formatting, the user preselects the relevant paragraphs and selects the relevant list type action.

Text Indent

The text indent defines the amount of empty space in front of a paragraph. The user can increase the indentation  , or decrease it  . Both actions are triggered by standard buttons, and are applied at paragraph level. To change the indentation, the user selects the paragraph (or just positions the cursor within the text) and selects the indent action. The text is moved 30 px left or right, depending on the action chosen.

Color Selection

Rich text editor - Selecting font and background colors
Rich text editor - Selecting font and background colors

Guidelines

Minimum Width

Although the control allows a minimum width of 6 rem (96 px), we recommend setting the width to at least 17.5 rem (280 px). Any less will make the editor practically unusable.

Number of Actions in the Toolbar

Only offer actions that are relevant for the use case. If you just need simple text formatting (such as bold, italic, underline, and strikethrough), remove the other groups.

Custom Plugins

Exercise judgement when adding custom plugins to the editor. Only offer a reasonable number of additional options.

Use self-explanatory icons for custom actions. Do not use a text label, or combine a text label with and icon.
As for all icons, offer a tooltip with a text label instead.

Additional Guidelines

The guidelines for the following controls also apply:

Resources

Want to dive deeper? Follow the links below to find out more about related controls, the SAPUI5 implementation, and the visual design.

Elements and Controls

Implementation