class sap.ui.richtexteditor.RichTextEditor

Visiblity: public
UX Guidelines: Rich Text Editor
Implements:
Available since: N/A
Module: sap/ui/richtexteditor/RichTextEditor
Application Component: CA-UI5-CTR-RIL

The RichTextEditor-Control is used to enter formatted text. It uses the third-party component called TinyMCE. In addition to the native toolbar, you can also use a toolbar built with SAPUI5 controls.

Overview

With version 1.48 onward, aside from the native toolbar of the TinyMCE, the RichTextEditor can also use a toolbar built with SAPUI5 controls. Which toolbar is used is taken into consideration only while the control is being initialized and it will not be possible to change it during runtime, because of lifecycle incompatibilities between the SAPUI5 and the third-party library. The custom toolbar acts like a wrapper to the native toolbar and takes care of synchronizing the state of its internal controls with the current state of the selection in the editor (bold, italics, font styles etc.).

Restrictions

Note: The RichTextEditor uses a third-party component and therefore some additional restrictions apply for its proper usage and support. For more information see the Preamble section in sap.ui.richtexteditor.

Guidelines

Usage

When to use

When not to use


Constructor

Constructor for a new RichTextEditor.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.ui.richtexteditor.RichTextEditor(sId?, mSettings?)
Param Type Default Value Description
sId? string

ID for the new control, generated automatically if no ID is given

mSettings? object

Initial settings for the new control


Properties

Name Type Default Value Description
buttonGroups object[]

An array of button configurations. These configurations contain the names of buttons as array in the property "buttons" and the name of the group in "name", they can also contain the "row" where the buttons should be placed, a "priority" and whether the buttons are "visible". See method addButtonGroup() for more details on the structure of the objects in this array. Note: buttonGroups is a feature from the native editor. Its supported scope with customToolbar is limited up to the grouping- the user could turn on/off a whole group, but modifiyng buttons within a group is not possible. In order to achieve that functionality with customToolbar, the developer needs to turn the group off and instantiate their own sap.m.Button(s) with the desired functionality.

Visibility: public
customToolbar boolean false

Determines whether a Fiori Toolbar is used instead of the TinyMCE default toolbar one. It is applied only when the EditorType is TinyMCE4 or TinyMCE5 and sap.m library is loaded. Note: The customToolbar property will have effect only on initial loading. Changing it during runtime will not affect the initially loaded toolbar.

Since: 1.48.

Visibility: public
editable boolean true

Determines whether the editor content can be modified by the user. When set to "false" there might not be any editor toolbar.

Visibility: public
editorLocation string js/tiny_mce4/tinymce.js

Relative or absolute URL where the editor is available. Must be on the same server. Note: Any attempts to set this property after the first rendering will not have any effect.

Visibility: public
editorType string TinyMCE4

The editor implementation to use.

Valid values are the ones found under sap.ui.richtexteditor.EditorType and any other editor identifier that may be introduced by other groups (hence this is not an enumeration).

Notes:

  • TinyMCE version 3 is no longer supported and cannot be used. If you set the property to TinyMCE, it will load TinyMCE version 4.
  • Any attempts to set this property after the first rendering will not have any effect.

Visibility: public
height sap.ui.core.CSSSize

Height of RichTextEditor control in CSS units. Note: If the height property results in a value smaller than 200px, the minimum height of 200px will be applied.

Visibility: public
plugins object[]

An array of plugin configuration objects with the obligatory property "name". Each object has to contain a property "name" which then contains the plugin name/ID.

Visibility: public
required boolean false

Determines whether a value is required.

Visibility: public
sanitizeValue boolean true

Determines whether to run the HTML sanitizer once the value (HTML markup) is applied or not. To configure allowed URLs please use the validator API via URLListValidator API.

Visibility: public
showGroupClipboard boolean true

Determines whether the toolbar button group containing commands like Cut, Copy and Paste is available. Changing this after the initial rendering will result in some visible redrawing.

Visibility: public
showGroupFont boolean false

Determines whether the toolbar button group containing commands like Font, Font Size and Colors is available. Changing this after the initial rendering will result in some visible redrawing.

Visibility: public
showGroupFontStyle boolean true

Determines whether the toolbar button group containing commands like Bold, Italic, Underline and Strikethrough is available. Changing this after the initial rendering will result in some visible redrawing.

Visibility: public
showGroupInsert boolean false

Determines whether the toolbar button group containing commands like Insert Image and Insert Smiley is available. Changing this after the initial rendering will result in some visible redrawing.

Visibility: public
showGroupStructure boolean true

Determines whether the toolbar button group containing commands like Bullets and Indentation is available. Changing this after the initial rendering will result in some visible redrawing.

Visibility: public
showGroupTextAlign boolean true

Determines whether the toolbar button group containing text alignment commands is available. Changing this after the initial rendering will result in some visible redrawing.

Visibility: public
showGroupUndo boolean false

Determines whether the toolbar button group containing commands like Undo and Redo is available. Changing this after the initial rendering will result in some visible redrawing.

Visibility: public
textDirection sap.ui.core.TextDirection Inherit

The text direction

Visibility: public
useLegacyTheme boolean true

Determines whether or not to use the legacy theme for the toolbar buttons. If this is set to false, the default theme for the editor will be used (which might change slightly with every update). The legacy theme has the disadvantage that not all functionality has its own icon, so using non default buttons might lead to invisible buttons with the legacy theme - use the default editor theme in this case.

Visibility: public
value string empty string

An HTML string representing the editor content. Because this is HTML, the value cannot be generically escaped to prevent cross-site scripting, so the application is responsible for doing so. Overwriting this property would also reset editor's Undo manager and buttons "Undo"/"Redo" would be set to their initial state.

Visibility: public
width sap.ui.core.CSSSize

Width of RichTextEditor control in CSS units.

Visibility: public
wrapping boolean true

Determines whether the text in the editor is wrapped. This does not affect the editor's value, only the representation in the control.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
_toolbarWrapper 0..1 sap.ui.richtexteditor.IToolbar

Custom toolbar wrapper. The wrapper gets instantiated when customToolbar property is set to true.

Since: 1.48.

customButtons 0..n sap.ui.core.Control

Custom buttons are meant to extend the RichTextEditor's custom toolbar. Though type is set to sap.ui.Control, only sap.m.Button is allowed. Note: customButtons are available only when the customToolbar is enabled and all the requirements are fulfilled.

Since: 1.48.


Associations

Name Cardinality Type Description
ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / IDs which label this control (see WAI-ARIA attribute aria-labelledby).

Since: 1.76.0.


Events Overview

Event Description
beforeEditorInit

This event is fired right before the TinyMCE instance is created and can be used to change the settings object that will be given to TinyMCE. The parameter "configuration" is the javascript oject that will be given to TinyMCE upon first instantiation. The configuration parameter contains a map that can be changed in the case of TinyMCE.

change

Event is fired when the text in the field has changed AND the focus leaves the editor or when the Enter key is pressed.

ready

Fired when the used editor is loaded and ready (its HTML is also created).

readyRecurring

Analogous to the ready event, the event is fired when the used editor is loaded and ready. But the event is fired after every time the control is ready to use and not only once like the ready event.

beforeEditorInit

This event is fired right before the TinyMCE instance is created and can be used to change the settings object that will be given to TinyMCE. The parameter "configuration" is the javascript oject that will be given to TinyMCE upon first instantiation. The configuration parameter contains a map that can be changed in the case of TinyMCE.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

change

Event is fired when the text in the field has changed AND the focus leaves the editor or when the Enter key is pressed.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object
newValue string

The new control value.

ready

Fired when the used editor is loaded and ready (its HTML is also created).

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

readyRecurring

Analogous to the ready event, the event is fired when the used editor is loaded and ready. But the event is fired after every time the control is ready to use and not only once like the ready event.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

addButtonGroup

Adds a button group to the editor.

addCustomButton

Adds some customButton to the aggregation customButtons.

addPlugin

Allows to add a plugin (that must already be installed on the server) to the RichTextEditor.

attachBeforeEditorInit

Attaches event handler fnFunction to the beforeEditorInit event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

This event is fired right before the TinyMCE instance is created and can be used to change the settings object that will be given to TinyMCE. The parameter "configuration" is the javascript oject that will be given to TinyMCE upon first instantiation. The configuration parameter contains a map that can be changed in the case of TinyMCE.

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

Event is fired when the text in the field has changed AND the focus leaves the editor or when the Enter key is pressed.

attachReady

Attaches event handler fnFunction to the ready event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

Fired when the used editor is loaded and ready (its HTML is also created).

attachReadyRecurring

Attaches event handler fnFunction to the readyRecurring event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

Analogous to the ready event, the event is fired when the used editor is loaded and ready. But the event is fired after every time the control is ready to use and not only once like the ready event.

destroyCustomButtons

Destroys all the customButtons in the aggregation customButtons.

detachBeforeEditorInit

Detaches event handler fnFunction from the beforeEditorInit event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

detachReady

Detaches event handler fnFunction from the ready event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

detachReadyRecurring

Detaches event handler fnFunction from the readyRecurring event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

sap.ui.richtexteditor.RichTextEditor.extend

Creates a new subclass of class sap.ui.richtexteditor.RichTextEditor with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireBeforeEditorInit

Fires event beforeEditorInit to attached listeners.

fireChange

Fires event change to attached listeners.

fireReady

Fires event ready to attached listeners.

fireReadyRecurring

Fires event readyRecurring to attached listeners.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getButtonGroups

Gets current value of property buttonGroups.

An array of button configurations. These configurations contain the names of buttons as array in the property "buttons" and the name of the group in "name", they can also contain the "row" where the buttons should be placed, a "priority" and whether the buttons are "visible". See method addButtonGroup() for more details on the structure of the objects in this array. Note: buttonGroups is a feature from the native editor. Its supported scope with customToolbar is limited up to the grouping- the user could turn on/off a whole group, but modifiyng buttons within a group is not possible. In order to achieve that functionality with customToolbar, the developer needs to turn the group off and instantiate their own sap.m.Button(s) with the desired functionality.

Default value is [].

getCustomButtons

Gets content of aggregation customButtons.

Custom buttons are meant to extend the RichTextEditor's custom toolbar. Though type is set to sap.ui.Control, only sap.m.Button is allowed. Note: customButtons are available only when the customToolbar is enabled and all the requirements are fulfilled.

getCustomToolbar

Gets current value of property customToolbar.

Determines whether a Fiori Toolbar is used instead of the TinyMCE default toolbar one. It is applied only when the EditorType is TinyMCE4 or TinyMCE5 and sap.m library is loaded. Note: The customToolbar property will have effect only on initial loading. Changing it during runtime will not affect the initially loaded toolbar.

Default value is false.

getEditable

Gets current value of property editable.

Determines whether the editor content can be modified by the user. When set to "false" there might not be any editor toolbar.

Default value is true.

getEditorLocation

Gets current value of property editorLocation.

Relative or absolute URL where the editor is available. Must be on the same server. Note: Any attempts to set this property after the first rendering will not have any effect.

Default value is 'js/tiny_mce4/tinymce.js'.

Since 1.25.0 The editorLocation is set implicitly when choosing the editorType.
getEditorType

Gets current value of property editorType.

The editor implementation to use.

Valid values are the ones found under sap.ui.richtexteditor.EditorType and any other editor identifier that may be introduced by other groups (hence this is not an enumeration).

Notes:

  • TinyMCE version 3 is no longer supported and cannot be used. If you set the property to TinyMCE, it will load TinyMCE version 4.
  • Any attempts to set this property after the first rendering will not have any effect.

Default value is 'TinyMCE4'.

getHeight

Gets current value of property height.

Height of RichTextEditor control in CSS units. Note: If the height property results in a value smaller than 200px, the minimum height of 200px will be applied.

sap.ui.richtexteditor.RichTextEditor.getMetadata

Returns a metadata object for class sap.ui.richtexteditor.RichTextEditor.

getNativeApi

Returns the current editor's instance. CAUTION: using the native editor introduces a dependency to that editor and breaks the wrapping character of the RichTextEditor control, so it should only be done in justified cases.

getPlugins

Gets current value of property plugins.

An array of plugin configuration objects with the obligatory property "name". Each object has to contain a property "name" which then contains the plugin name/ID.

Default value is [].

getRequired

Gets current value of property required.

Determines whether a value is required.

Default value is false.

getSanitizeValue

Gets current value of property sanitizeValue.

Determines whether to run the HTML sanitizer once the value (HTML markup) is applied or not. To configure allowed URLs please use the validator API via URLListValidator API.

Default value is true.

getShowGroupClipboard

Gets current value of property showGroupClipboard.

Determines whether the toolbar button group containing commands like Cut, Copy and Paste is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupFont

Gets current value of property showGroupFont.

Determines whether the toolbar button group containing commands like Font, Font Size and Colors is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is false.

getShowGroupFontStyle

Gets current value of property showGroupFontStyle.

Determines whether the toolbar button group containing commands like Bold, Italic, Underline and Strikethrough is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupInsert

Gets current value of property showGroupInsert.

Determines whether the toolbar button group containing commands like Insert Image and Insert Smiley is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is false.

getShowGroupLink

Gets current value of property showGroupLink.

Determines whether the toolbar button group containing commands like Create Link and Remove Link is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is false.

getShowGroupStructure

Gets current value of property showGroupStructure.

Determines whether the toolbar button group containing commands like Bullets and Indentation is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupTextAlign

Gets current value of property showGroupTextAlign.

Determines whether the toolbar button group containing text alignment commands is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupUndo

Gets current value of property showGroupUndo.

Determines whether the toolbar button group containing commands like Undo and Redo is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is false.

getTextDirection

Gets current value of property textDirection.

The text direction

Default value is Inherit.

getUseLegacyTheme

Gets current value of property useLegacyTheme.

Determines whether or not to use the legacy theme for the toolbar buttons. If this is set to false, the default theme for the editor will be used (which might change slightly with every update). The legacy theme has the disadvantage that not all functionality has its own icon, so using non default buttons might lead to invisible buttons with the legacy theme - use the default editor theme in this case.

Default value is true.

getValue

Gets current value of property value.

An HTML string representing the editor content. Because this is HTML, the value cannot be generically escaped to prevent cross-site scripting, so the application is responsible for doing so. Overwriting this property would also reset editor's Undo manager and buttons "Undo"/"Redo" would be set to their initial state.

Default value is empty string.

getWidth

Gets current value of property width.

Width of RichTextEditor control in CSS units.

getWrapping

Gets current value of property wrapping.

Determines whether the text in the editor is wrapped. This does not affect the editor's value, only the representation in the control.

Default value is true.

indexOfCustomButton

Checks for the provided sap.ui.core.Control in the aggregation customButtons. and returns its index if found or -1 otherwise.

insertCustomButton

Inserts a customButton into the aggregation customButtons.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllCustomButtons

Removes all the controls from the aggregation customButtons.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

removeCustomButton

Removes a customButton from the aggregation customButtons.

removePlugin

Removes the plugin with the given name/ID from the list of plugins to load

setButtonGroups

Sets the button groups to the editor.

setCustomToolbar

Sets a new value for property customToolbar.

Determines whether a Fiori Toolbar is used instead of the TinyMCE default toolbar one. It is applied only when the EditorType is TinyMCE4 or TinyMCE5 and sap.m library is loaded. Note: The customToolbar property will have effect only on initial loading. Changing it during runtime will not affect the initially loaded toolbar.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setEditable

Sets a new value for property editable.

Determines whether the editor content can be modified by the user. When set to "false" there might not be any editor toolbar.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setEditorLocation

Sets a new value for property editorLocation.

Relative or absolute URL where the editor is available. Must be on the same server. Note: Any attempts to set this property after the first rendering will not have any effect.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 'js/tiny_mce4/tinymce.js'.

Since 1.25.0 The editorLocation is set implicitly when choosing the editorType.
setEditorType

Switches the editor type and sets the default settings for the editor. All plugins and button groups should be set after this has been invoked

setHeight

Sets a new value for property height.

Height of RichTextEditor control in CSS units. Note: If the height property results in a value smaller than 200px, the minimum height of 200px will be applied.

When called with a value of null or undefined, the default value of the property will be restored.

setPlugins

Sets the plugins to the editor.

setRequired

Sets a new value for property required.

Determines whether a value is required.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setSanitizeValue

Sets a new value for property sanitizeValue.

Determines whether to run the HTML sanitizer once the value (HTML markup) is applied or not. To configure allowed URLs please use the validator API via URLListValidator API.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setShowGroupClipboard

Sets a new value for property showGroupClipboard.

Determines whether the toolbar button group containing commands like Cut, Copy and Paste is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setShowGroupFont

Sets a new value for property showGroupFont.

Determines whether the toolbar button group containing commands like Font, Font Size and Colors is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setShowGroupFontStyle

Sets a new value for property showGroupFontStyle.

Determines whether the toolbar button group containing commands like Bold, Italic, Underline and Strikethrough is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setShowGroupInsert

Sets a new value for property showGroupInsert.

Determines whether the toolbar button group containing commands like Insert Image and Insert Smiley is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setShowGroupLink

Sets a new value for property showGroupLink.

Determines whether the toolbar button group containing commands like Create Link and Remove Link is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setShowGroupStructure

Sets a new value for property showGroupStructure.

Determines whether the toolbar button group containing commands like Bullets and Indentation is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setShowGroupTextAlign

Sets a new value for property showGroupTextAlign.

Determines whether the toolbar button group containing text alignment commands is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setShowGroupUndo

Sets a new value for property showGroupUndo.

Determines whether the toolbar button group containing commands like Undo and Redo is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setTextDirection

Sets a new value for property textDirection.

The text direction

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Inherit.

setUseLegacyTheme

Sets a new value for property useLegacyTheme.

Determines whether or not to use the legacy theme for the toolbar buttons. If this is set to false, the default theme for the editor will be used (which might change slightly with every update). The legacy theme has the disadvantage that not all functionality has its own icon, so using non default buttons might lead to invisible buttons with the legacy theme - use the default editor theme in this case.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setValue

Sets a new value for property value.

An HTML string representing the editor content. Because this is HTML, the value cannot be generically escaped to prevent cross-site scripting, so the application is responsible for doing so. Overwriting this property would also reset editor's Undo manager and buttons "Undo"/"Redo" would be set to their initial state.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

setWidth

Sets a new value for property width.

Width of RichTextEditor control in CSS units.

When called with a value of null or undefined, the default value of the property will be restored.

setWrapping

Sets a new value for property wrapping.

Determines whether the text in the editor is wrapped. This does not affect the editor's value, only the representation in the control.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

addButtonGroup

Adds a button group to the editor.

Param Type DefaultValue Description
mGroup object string

Name/ID of a single button or object containing the group information

buttons string[]

Array of name/IDs of the buttons in the group

name string

Name/ID of the group.

visible boolean true

(optional) The priority of the button group. Lower priorities are added first.

row int 0

(optional) Row number in which the button should be

priority int 10

(optional) The priority of the button group. Lower priorities are added first.

customToolbarPriority int

(optional) The priority of the button group in the custom toolbar. Each default group in the custom toolbar has a predefined customToolbarPriority. Lower priorities are added in first.

addCustomButton

Adds some customButton to the aggregation customButtons.

Param Type DefaultValue Description
oCustomButton sap.ui.core.Control

The customButton to add; if empty, nothing is inserted

addPlugin

Allows to add a plugin (that must already be installed on the server) to the RichTextEditor.

Param Type DefaultValue Description
mPlugin object string

The plugin ID/name or an object with property "name", containing the ID/name of the plugin

attachBeforeEditorInit

Attaches event handler fnFunction to the beforeEditorInit event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

This event is fired right before the TinyMCE instance is created and can be used to change the settings object that will be given to TinyMCE. The parameter "configuration" is the javascript oject that will be given to TinyMCE upon first instantiation. The configuration parameter contains a map that can be changed in the case of TinyMCE.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.richtexteditor.RichTextEditor itself

attachChange

Attaches event handler fnFunction to the change event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

Event is fired when the text in the field has changed AND the focus leaves the editor or when the Enter key is pressed.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.richtexteditor.RichTextEditor itself

attachReady

Attaches event handler fnFunction to the ready event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

Fired when the used editor is loaded and ready (its HTML is also created).

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.richtexteditor.RichTextEditor itself

attachReadyRecurring

Attaches event handler fnFunction to the readyRecurring event of this sap.ui.richtexteditor.RichTextEditor.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.ui.richtexteditor.RichTextEditor itself.

Analogous to the ready event, the event is fired when the used editor is loaded and ready. But the event is fired after every time the control is ready to use and not only once like the ready event.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.ui.richtexteditor.RichTextEditor itself

destroyCustomButtons

Destroys all the customButtons in the aggregation customButtons.

detachBeforeEditorInit

Detaches event handler fnFunction from the beforeEditorInit event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachChange

Detaches event handler fnFunction from the change event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachReady

Detaches event handler fnFunction from the ready event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachReadyRecurring

Detaches event handler fnFunction from the readyRecurring event of this sap.ui.richtexteditor.RichTextEditor.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.ui.richtexteditor.RichTextEditor.extend

Creates a new subclass of class sap.ui.richtexteditor.RichTextEditor with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireBeforeEditorInit

Fires event beforeEditorInit to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireChange

Fires event change to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

newValue string

The new control value.

fireReady

Fires event ready to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireReadyRecurring

Fires event readyRecurring to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getButtonGroups

Gets current value of property buttonGroups.

An array of button configurations. These configurations contain the names of buttons as array in the property "buttons" and the name of the group in "name", they can also contain the "row" where the buttons should be placed, a "priority" and whether the buttons are "visible". See method addButtonGroup() for more details on the structure of the objects in this array. Note: buttonGroups is a feature from the native editor. Its supported scope with customToolbar is limited up to the grouping- the user could turn on/off a whole group, but modifiyng buttons within a group is not possible. In order to achieve that functionality with customToolbar, the developer needs to turn the group off and instantiate their own sap.m.Button(s) with the desired functionality.

Default value is [].

getCustomButtons

Gets content of aggregation customButtons.

Custom buttons are meant to extend the RichTextEditor's custom toolbar. Though type is set to sap.ui.Control, only sap.m.Button is allowed. Note: customButtons are available only when the customToolbar is enabled and all the requirements are fulfilled.

getCustomToolbar

Gets current value of property customToolbar.

Determines whether a Fiori Toolbar is used instead of the TinyMCE default toolbar one. It is applied only when the EditorType is TinyMCE4 or TinyMCE5 and sap.m library is loaded. Note: The customToolbar property will have effect only on initial loading. Changing it during runtime will not affect the initially loaded toolbar.

Default value is false.

getEditable

Gets current value of property editable.

Determines whether the editor content can be modified by the user. When set to "false" there might not be any editor toolbar.

Default value is true.

getEditorLocation

Gets current value of property editorLocation.

Relative or absolute URL where the editor is available. Must be on the same server. Note: Any attempts to set this property after the first rendering will not have any effect.

Default value is 'js/tiny_mce4/tinymce.js'.

Since 1.25.0 The editorLocation is set implicitly when choosing the editorType.

getEditorType

Gets current value of property editorType.

The editor implementation to use.

Valid values are the ones found under sap.ui.richtexteditor.EditorType and any other editor identifier that may be introduced by other groups (hence this is not an enumeration).

Notes:

Default value is 'TinyMCE4'.

getHeight

Gets current value of property height.

Height of RichTextEditor control in CSS units. Note: If the height property results in a value smaller than 200px, the minimum height of 200px will be applied.

sap.ui.richtexteditor.RichTextEditor.getMetadata

Returns a metadata object for class sap.ui.richtexteditor.RichTextEditor.

getNativeApi

Returns the current editor's instance. CAUTION: using the native editor introduces a dependency to that editor and breaks the wrapping character of the RichTextEditor control, so it should only be done in justified cases.

getPlugins

Gets current value of property plugins.

An array of plugin configuration objects with the obligatory property "name". Each object has to contain a property "name" which then contains the plugin name/ID.

Default value is [].

getRequired

Gets current value of property required.

Determines whether a value is required.

Default value is false.

getSanitizeValue

Gets current value of property sanitizeValue.

Determines whether to run the HTML sanitizer once the value (HTML markup) is applied or not. To configure allowed URLs please use the validator API via URLListValidator API.

Default value is true.

getShowGroupClipboard

Gets current value of property showGroupClipboard.

Determines whether the toolbar button group containing commands like Cut, Copy and Paste is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupFont

Gets current value of property showGroupFont.

Determines whether the toolbar button group containing commands like Font, Font Size and Colors is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is false.

getShowGroupFontStyle

Gets current value of property showGroupFontStyle.

Determines whether the toolbar button group containing commands like Bold, Italic, Underline and Strikethrough is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupInsert

Gets current value of property showGroupInsert.

Determines whether the toolbar button group containing commands like Insert Image and Insert Smiley is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is false.

getShowGroupStructure

Gets current value of property showGroupStructure.

Determines whether the toolbar button group containing commands like Bullets and Indentation is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupTextAlign

Gets current value of property showGroupTextAlign.

Determines whether the toolbar button group containing text alignment commands is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is true.

getShowGroupUndo

Gets current value of property showGroupUndo.

Determines whether the toolbar button group containing commands like Undo and Redo is available. Changing this after the initial rendering will result in some visible redrawing.

Default value is false.

getTextDirection

Gets current value of property textDirection.

The text direction

Default value is Inherit.

getUseLegacyTheme

Gets current value of property useLegacyTheme.

Determines whether or not to use the legacy theme for the toolbar buttons. If this is set to false, the default theme for the editor will be used (which might change slightly with every update). The legacy theme has the disadvantage that not all functionality has its own icon, so using non default buttons might lead to invisible buttons with the legacy theme - use the default editor theme in this case.

Default value is true.

getValue

Gets current value of property value.

An HTML string representing the editor content. Because this is HTML, the value cannot be generically escaped to prevent cross-site scripting, so the application is responsible for doing so. Overwriting this property would also reset editor's Undo manager and buttons "Undo"/"Redo" would be set to their initial state.

Default value is empty string.

getWidth

Gets current value of property width.

Width of RichTextEditor control in CSS units.

getWrapping

Gets current value of property wrapping.

Determines whether the text in the editor is wrapped. This does not affect the editor's value, only the representation in the control.

Default value is true.

indexOfCustomButton

Checks for the provided sap.ui.core.Control in the aggregation customButtons. and returns its index if found or -1 otherwise.

Param Type DefaultValue Description
oCustomButton sap.ui.core.Control

The customButton whose index is looked for

insertCustomButton

Inserts a customButton into the aggregation customButtons.

Param Type DefaultValue Description
oCustomButton sap.ui.core.Control

The customButton to insert; if empty, nothing is inserted

iIndex int

The 0-based index the customButton should be inserted at; for a negative value of iIndex, the customButton is inserted at position 0; for a value greater than the current size of the aggregation, the customButton is inserted at the last position

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAllCustomButtons

Removes all the controls from the aggregation customButtons.

Additionally, it unregisters them from the hosting UIArea.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

removeCustomButton

Removes a customButton from the aggregation customButtons.

Param Type DefaultValue Description
vCustomButton int string sap.ui.core.Control

The customButton to remove or its index or id

removePlugin

Removes the plugin with the given name/ID from the list of plugins to load

Param Type DefaultValue Description
sPluginName string

The name/ID of the plugin to remove

setButtonGroups

Sets the button groups to the editor.

Param Type DefaultValue Description
aGroups array

Array of names or objects containing the group information

setCustomToolbar

Sets a new value for property customToolbar.

Determines whether a Fiori Toolbar is used instead of the TinyMCE default toolbar one. It is applied only when the EditorType is TinyMCE4 or TinyMCE5 and sap.m library is loaded. Note: The customToolbar property will have effect only on initial loading. Changing it during runtime will not affect the initially loaded toolbar.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bCustomToolbar boolean false

New value for property customToolbar

setEditable

Sets a new value for property editable.

Determines whether the editor content can be modified by the user. When set to "false" there might not be any editor toolbar.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bEditable boolean true

New value for property editable

setEditorLocation

Sets a new value for property editorLocation.

Relative or absolute URL where the editor is available. Must be on the same server. Note: Any attempts to set this property after the first rendering will not have any effect.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is 'js/tiny_mce4/tinymce.js'.

Since 1.25.0 The editorLocation is set implicitly when choosing the editorType.
Param Type DefaultValue Description
sEditorLocation string 'js/tiny_mce4/tinymce.js'

New value for property editorLocation

setEditorType

Switches the editor type and sets the default settings for the editor. All plugins and button groups should be set after this has been invoked

Param Type DefaultValue Description
sEditorType string

Which editor type to be used (currently only TinyMCE 4 and 5)

setHeight

Sets a new value for property height.

Height of RichTextEditor control in CSS units. Note: If the height property results in a value smaller than 200px, the minimum height of 200px will be applied.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize

New value for property height

setPlugins

Sets the plugins to the editor.

Param Type DefaultValue Description
aPlugins array

Array of names or objects containing the plugin information

setRequired

Sets a new value for property required.

Determines whether a value is required.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bRequired boolean false

New value for property required

setSanitizeValue

Sets a new value for property sanitizeValue.

Determines whether to run the HTML sanitizer once the value (HTML markup) is applied or not. To configure allowed URLs please use the validator API via URLListValidator API.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bSanitizeValue boolean true

New value for property sanitizeValue

setShowGroupClipboard

Sets a new value for property showGroupClipboard.

Determines whether the toolbar button group containing commands like Cut, Copy and Paste is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bShowGroupClipboard boolean true

New value for property showGroupClipboard

setShowGroupFont

Sets a new value for property showGroupFont.

Determines whether the toolbar button group containing commands like Font, Font Size and Colors is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bShowGroupFont boolean false

New value for property showGroupFont

setShowGroupFontStyle

Sets a new value for property showGroupFontStyle.

Determines whether the toolbar button group containing commands like Bold, Italic, Underline and Strikethrough is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bShowGroupFontStyle boolean true

New value for property showGroupFontStyle

setShowGroupInsert

Sets a new value for property showGroupInsert.

Determines whether the toolbar button group containing commands like Insert Image and Insert Smiley is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bShowGroupInsert boolean false

New value for property showGroupInsert

setShowGroupStructure

Sets a new value for property showGroupStructure.

Determines whether the toolbar button group containing commands like Bullets and Indentation is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bShowGroupStructure boolean true

New value for property showGroupStructure

setShowGroupTextAlign

Sets a new value for property showGroupTextAlign.

Determines whether the toolbar button group containing text alignment commands is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bShowGroupTextAlign boolean true

New value for property showGroupTextAlign

setShowGroupUndo

Sets a new value for property showGroupUndo.

Determines whether the toolbar button group containing commands like Undo and Redo is available. Changing this after the initial rendering will result in some visible redrawing.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bShowGroupUndo boolean false

New value for property showGroupUndo

setTextDirection

Sets a new value for property textDirection.

The text direction

When called with a value of null or undefined, the default value of the property will be restored.

Default value is Inherit.

Param Type DefaultValue Description
sTextDirection sap.ui.core.TextDirection Inherit

New value for property textDirection

setUseLegacyTheme

Sets a new value for property useLegacyTheme.

Determines whether or not to use the legacy theme for the toolbar buttons. If this is set to false, the default theme for the editor will be used (which might change slightly with every update). The legacy theme has the disadvantage that not all functionality has its own icon, so using non default buttons might lead to invisible buttons with the legacy theme - use the default editor theme in this case.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bUseLegacyTheme boolean true

New value for property useLegacyTheme

setValue

Sets a new value for property value.

An HTML string representing the editor content. Because this is HTML, the value cannot be generically escaped to prevent cross-site scripting, so the application is responsible for doing so. Overwriting this property would also reset editor's Undo manager and buttons "Undo"/"Redo" would be set to their initial state.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

Param Type DefaultValue Description
sValue string ''

New value for property value

setWidth

Sets a new value for property width.

Width of RichTextEditor control in CSS units.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width

setWrapping

Sets a new value for property wrapping.

Determines whether the text in the editor is wrapped. This does not affect the editor's value, only the representation in the control.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bWrapping boolean true

New value for property wrapping