@sapui5/sap.ui.richtexteditor 1.99.1 → 1.102.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sapui5/sap.ui.richtexteditor",
-  "version": "1.99.1",
+  "version": "1.102.0",
   "description": "SAPUI5 Library sap.ui.richtexteditor",
   "homepage": "https://sap.github.io/ui5-tooling/pages/SAPUI5/",
   "author": "SAP SE (https://www.sap.com)",

package/src/sap/ui/richtexteditor/.library

@@ -5,7 +5,7 @@
 	<vendor>SAP SE</vendor>
 	<copyright>SAPUI5
  * (c) Copyright 2009-2022 SAP SE. All rights reserved.</copyright>
-	<version>1.99.1</version>
+	<version>1.102.0</version>
 
 	<documentation>A rich text editor (RTE) control. Requires installation of an additional rich text editor library.</documentation>
 

package/src/sap/ui/richtexteditor/RTESplitButton.js

@@ -24,7 +24,7 @@ sap.ui.define([
 		 * @alias sap.ui.richtexteditor.RTESplitButton
 		 *
 		 * @author SAP SE
-		 * @version 1.99.1
+		 * @version 1.102.0
 		 */
 		var RTESplitButton = SplitButton.extend("sap.ui.richtexteditor.RTESplitButton", {
 			metadata: {

package/src/sap/ui/richtexteditor/RichTextEditor.js

@@ -3,12 +3,12 @@
  * (c) Copyright 2009-2022 SAP SE. All rights reserved.
  */
 
-/*global Promise */
-
 // Provides control sap.ui.richtexteditor.RichTextEditor.
 sap.ui.define([
 	"sap/ui/thirdparty/jquery",
 	'sap/ui/core/Control',
+	'sap/ui/core/library',
+	'sap/ui/core/Locale',
 	'sap/ui/core/ResizeHandler',
 	'./library',
 	'./ToolbarWrapper',
@@ -23,6 +23,8 @@ sap.ui.define([
 	function(
 		jQuery,
 		Control,
+		coreLibrary,
+		Locale,
 		ResizeHandler,
 		library,
 		ToolbarWrapper,
@@ -33,6 +35,9 @@ sap.ui.define([
 		Core
 	) {
 	"use strict";
+
+	var TextDirection = coreLibrary.TextDirection;
+
 	/**
 	 * Describes the internal status of the editor component used inside the RichTextEditor control.
 	 *
@@ -102,6 +107,47 @@ sap.ui.define([
 	 * <li>Use callbacks to the native third-party API with care, as there may be compatibility issues with later versions.</li>
 	 * </ul>
 	 *
+	 * <h3>Custom toolbar - adding and removing buttons</h3>
+	 * With version 1.102 it is possible to redefine the button groups configuration in order to show only particular set of buttons in the custom toolbar of the <code>RichTextEditor</code>.
+	 * This is possible in few ways:
+	 * <ul>
+	 * <li>By providing the buttons group configurations as a whole by setting the <code>buttonGroups</code> property of the control.</li>
+	 * <li>By providing individual button group configuration via <code>addButtonGroup</code> method.</li>
+	 * </ul>
+	 *
+	 * Consider the following when choosing your approach:
+	 * <ul>
+	 * <li>Setting <code>buttonGroups</code> will override all current custom toolbar button group configurations. This method allows for total redefining of the custom toolbar groups.</li>
+	 * <li>Using <code>addButtonGroups</code> will try to add non-existing group into the configuration array, however, if such group configuration exists already, a warning will be logged and the new configuration will not be added. In order to replace the existing configuration you will need to remove it first via <code>removeButtonGroup</code>.</li>
+	 * </ul>
+	 *
+	 * Below is a list of supported groups and buttons, which can be specified in the configuration objects (format is <<group name>>: <<supported buttons>>):
+	 *	<ul>
+	 *		<li>font-style: bold, italic, underline, strikethrough</li>
+	 *		<li>font: fontselect, fontsizeselect, forecolor, backcolor</li>
+	 *		<li>clipboard: cut, copy, paste</li>
+	 *		<li>structure: bullist, numlist, outdent, indent</li>
+	 *		<li>undo: undo, redo</li>
+	 *		<li>insert: image, emoticons</li>
+	 *		<li>link: link, unlink</li>
+	 *		<li>text-align: alignleft, aligncenter, alignright, alignjustify</li>
+	 *	</ul>
+	 * Additional supported groups, which can be added only after the editor is loaded (they can not be specified in the above mentioned configuration):
+	 *	<ul>
+	 *		<li>table: table</li>
+	 *		<li>styleselect: styleselect</li>
+	 *	<ul>
+	 * <b>Note!</b> Adding configuration for "text-align" group with any buttons will still render a menu button with all available options inside. Removing/hiding the group can be achieved by invoking <code>removeButtonGroup</code> or <code>setShowGroupTextAlign(false)</code> depending on the desired result.
+	 *
+	 * <b>Note!</b> There is no synchronization between the <code>setShowGroup*</code> properties and the configuration object that the application can specifying via <code>buttonGroups</code> in the constructor or on a later stage. This means that in case new configuration is provided and for particular group the passed object contains property <code>visible: true</code>, this group property will be respected no matter if the <code>RichTextEditor</code>'s property for this particular group is set to <code>false</code>.
+	 * Example:
+	 * Providing the following object as group configuration:
+	 * {
+	 * 	name: "font"
+	 * 	visible: true
+	 * }
+	 * Will make the "font" group visible, no matter that calling <code>RichTextEditor.getShowGroupFont()</code> returns <code>false</code>.
+	 *
 	 * @extends sap.ui.core.Control
 	 *
 	 * @author SAP SE
@@ -130,7 +176,7 @@ sap.ui.define([
 				/**
 				 * The text direction
 				 */
-				textDirection: { type: "sap.ui.core.TextDirection", group: "Appearance", defaultValue: sap.ui.core.TextDirection.Inherit },
+				textDirection: { type: "sap.ui.core.TextDirection", group: "Appearance", defaultValue: TextDirection.Inherit },
 
 				/**
 				 * Width of RichTextEditor control in CSS units.
@@ -172,41 +218,49 @@ sap.ui.define([
 
 				/**
 				 * 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupFontStyle: { type: "boolean", group: "Misc", defaultValue: 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupTextAlign: { type: "boolean", group: "Misc", defaultValue: 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupStructure: { type: "boolean", group: "Misc", defaultValue: true },
 
 				/**
 				 * 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupFont: { type: "boolean", group: "Misc", defaultValue: false },
 
 				/**
 				 * 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupClipboard: { type: "boolean", group: "Misc", defaultValue: true },
 
 				/**
 				 * 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupInsert: { type: "boolean", group: "Misc", defaultValue: false },
 
 				/**
 				 * 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupLink: { type: "boolean", group: "Misc", defaultValue: 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.
+				 * Note: This property will not be synchronized with group configuration provided via the buttonGroups property or when groups are added on a later stage.
 				 */
 				showGroupUndo: { type: "boolean", group: "Misc", defaultValue: false },
 
@@ -240,7 +294,7 @@ sap.ui.define([
 
 				/**
 				 * 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.
-				 * <b>Note:</b> <code>buttonGroups</code> is a feature from the native editor. Its supported scope with <code>customToolbar</code> 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 <code>customToolbar</code>, the developer needs to turn the group off and instantiate their own <code>sap.m.Button</code>(s) with the desired functionality.
+				 * <b>Note:</b> <code>buttonGroups</code> is a feature from the native editor. Its supported scope with <code>customToolbar</code> is limited up to the grouping- the user could turn on/off a whole group, but modifying buttons within a group is not possible. In order to achieve that functionality with <code>customToolbar</code>, the developer needs to turn the group off and instantiate their own <code>sap.m.Button</code>(s) with the desired functionality.
 				 */
 				buttonGroups: {type: "object[]", group: "Behavior", defaultValue: [] },
 
@@ -777,85 +831,100 @@ sap.ui.define([
 
 	/**
 	 * Adds a button group to the editor.
+	 * <b>Note</b>: Adding already existing group will not do anything. If a button group needs to be changed, it first needs to be removed and then added by providing its name or map object, containing its desired configuration.
 	 *
-	 * @param {object|string} [mGroup] Name/ID of a single button or object containing the group information
-	 * @param {string[]}   [mGroup.buttons] Array of name/IDs of the buttons in the group
-	 * @param {string}     [mGroup.name] Name/ID of the group.
-	 * @param {boolean}    [mGroup.visible=true] (optional) The priority of the button group. Lower priorities are added first.
-	 * @param {int}        [mGroup.row=0] (optional) Row number in which the button should be
-	 * @param {int}        [mGroup.priority=10] (optional) The priority of the button group. Lower priorities are added first.
-	 * @param {int}        [mGroup.customToolbarPriority] (optional) The priority of the button group in the custom toolbar. Each default group in the custom toolbar has a predefined <code>customToolbarPriority</code>. Lower priorities are added in first.
+	 * @param {object|string} [vGroup] Name/ID of a single button or object containing the group information
+	 * @param {string[]}   [vGroup.buttons] Array of name/IDs of the buttons in the group
+	 * @param {string}     [vGroup.name] Name/ID of the group.
+	 * @param {boolean}    [vGroup.visible=true] (optional) The priority of the button group. Lower priorities are added first.
+	 * @param {int}        [vGroup.row=0] (optional) Row number in which the button should be
+	 * @param {int}        [vGroup.priority=10] (optional) The priority of the button group. Lower priorities are added first.
+	 * @param {int}        [vGroup.customToolbarPriority] (optional) The priority of the button group in the custom toolbar. Each default group in the custom toolbar has a predefined <code>customToolbarPriority</code>. Lower priorities are added in first.
 	 * @returns {object} Control instance (for method chaining)
 	 * @public
 	 */
-	RichTextEditor.prototype.addButtonGroup = function (mGroup) {
+	RichTextEditor.prototype.addButtonGroup = function (vGroup) {
 		var aGroups = this.getProperty("buttonGroups").slice(),
-			oCustomToolbar = this.getAggregation("_toolbarWrapper"),
-			bFullGroup = true;
+			oCustomToolbar = this.getAggregation("_toolbarWrapper");
+
+		if (!vGroup) {
+			return this;
+		}
 
 		// check if the group is already added
 		for (var i = 0; i < aGroups.length; ++i) {
-			if (mGroup === "string" && aGroups[i].name === mGroup || aGroups[i].name === mGroup.name) {
+			if (typeof vGroup === "string" && aGroups[i].name === vGroup || aGroups[i].name === vGroup.name) {
+				Log.warning("Trying to add already existing group: " + (typeof vGroup === "string" ? vGroup : vGroup.name) + ". Please remove the group first and then add it.", this);
 				return this;
 			}
 		}
 
-		//if mGroup is string internally we are creating a group object.
-		if (typeof mGroup === "string") {
-			bFullGroup = false;
-			switch (mGroup) {
+		// check for the mandatory parameters "vGroup.buttons" and "vGroup.name"
+		if (typeof vGroup === "object" && !(vGroup.name && Array.isArray(vGroup.buttons))) {
+			Log.error("The properties 'name' and 'buttons' are mandatory for the group configuration object. Please make sure they exist within the provided configuration.", this);
+			return this;
+		}
+
+		// check buttons in the vGroup.buttons property
+		if (typeof vGroup === "object" && !(Array.isArray(vGroup.buttons) && vGroup.buttons.length)) {
+			Log.error("The 'buttons' array of the provided group configuration object cannot be empty.", this);
+			return this;
+		}
+
+		//if vGroup is string and the group name is known to the RTE control, internally we are creating a group object.
+		if (typeof vGroup === "string") {
+			switch (vGroup) {
 				case "formatselect":
-					bFullGroup = true;
-					mGroup = {
+					vGroup = {
 						name: "formatselect",
 						buttons: ["formatselect"]
 					};
 					break;
 				case "styleselect":
-					bFullGroup = true;
-					mGroup = {
+					vGroup = {
 						name: "styleselect",
 						buttons: ["styleselect"],
 						customToolbarPriority: 40
 					};
 					break;
 				case "table":
-					bFullGroup = true;
-					mGroup = {
+					vGroup = {
 						name: "table",
 						buttons: ["table"],
 						customToolbarPriority: 90
 					};
 					break;
 				default:
-					mGroup = {
+					vGroup = {
 						name: this._createId("buttonGroup"),
-						buttons: [mGroup]
+						buttons: [vGroup]
 					};
 			}
 		}
 
-		if (mGroup.visible === undefined) {
-			mGroup.visible = true;
-		}
-		if (mGroup.priority === undefined) {
-			mGroup.priority = 10;
-		}
-		if (mGroup.row === undefined) {
-			mGroup.row = 0;
-		}
+		// Check if any optional configuration parameters are missing
+		// and if so - update the group object with their default values.
+		this._checkAndUpdateGroupInfo(vGroup);
 
 		var aButtonGroups = this.getButtonGroups();
-		aButtonGroups.push(mGroup);
+		aButtonGroups.push(vGroup);
 		this.setProperty("buttonGroups", aButtonGroups);
 
 		if (oCustomToolbar) {
-			oCustomToolbar.addButtonGroupToContent(mGroup, bFullGroup);
+			// Provide the new configuration of the group to the custom toolbar
+			oCustomToolbar.addButtonGroupToContent(vGroup);
 		}
 
 		return this;
 	};
 
+	/**
+	 * Removes a button group from the editor.
+	 *
+	 * @param {string} [sGroupName] The name of the group to be removed.
+	 * @returns {object} Control instance (for method chaining)
+	 * @public
+	 */
 	RichTextEditor.prototype.removeButtonGroup = function(sGroupName) {
 		var aGroups = this.getProperty("buttonGroups").slice(0),
 			oCustomToolbar = this.getAggregation("_toolbarWrapper");
@@ -864,7 +933,6 @@ sap.ui.define([
 			if (aGroups[i].name === sGroupName) {
 				aGroups.splice(i, 1);
 				--i;
-
 				oCustomToolbar && oCustomToolbar.removeButtonGroup(sGroupName);
 			}
 		}
@@ -888,6 +956,10 @@ sap.ui.define([
 			return this;
 		}
 
+		// There are some optional parameters in the groups config, which need to be checked and if not provided
+		// set a default values
+		aGroups.forEach(this._checkAndUpdateGroupInfo);
+
 		this.setProperty("buttonGroups", aGroups);
 
 		oCustomToolbar = this.getAggregation("_toolbarWrapper");
@@ -900,6 +972,29 @@ sap.ui.define([
 
 	};
 
+	/**
+	 * Checks the group object for optional parameters and adds them with their default values in case they are missing
+	 * The properties that this method checks for are (default values are in brackets):
+	 * - visible (true)
+	 * - priority (10)
+	 * - row (0)
+	 *
+	 * @param {object} oGroup The group object that needs to be checked and modified if needed.
+	 */
+	RichTextEditor.prototype._checkAndUpdateGroupInfo = function (oGroup) {
+		// As those are optional parameters we are adding default values
+		// in case the application developers have not done so.
+		if (oGroup.visible === undefined) {
+			oGroup.visible = true;
+		}
+		if (oGroup.priority === undefined) {
+			oGroup.priority = 10;
+		}
+		if (oGroup.row === undefined) {
+			oGroup.row = 0;
+		}
+	};
+
 	/**
 	 * Sets the plugins to the editor.
 	 *
@@ -932,7 +1027,7 @@ sap.ui.define([
 	/**
 	 * Make the button group with the given name (in)visible (if used before initialization of the editor)
 	 *
-	 * @param {string} [sGroupName] Name of the group of buttons to be chenged
+	 * @param {string} [sGroupName] Name of the group of buttons to be changed
 	 * @param {boolean} [bVisible=false] Whether or not this group should be visible
 	 * @returns {object} Control instance (for method chaining)
 	 * @private
@@ -1022,13 +1117,6 @@ sap.ui.define([
 			buttons: [
 				"bullist", "numlist", "outdent", "indent"
 			]
-		}, {
-			name: "e-mail",
-			visible: false,
-			row: 1,
-			priority: 30,
-			customToolbarPriority: 10,
-			buttons: []
 		}, {
 			name: "undo",
 			visible: false,
@@ -1056,9 +1144,7 @@ sap.ui.define([
 			buttons: [
 				"link", "unlink"
 			]
-		}]);
-
-		this.addButtonGroup({
+		}, {
 			// Text Align group
 			name: "text-align",
 			visible: true,
@@ -1068,7 +1154,7 @@ sap.ui.define([
 			buttons: [
 				"alignleft", "aligncenter", "alignright", "alignjustify"
 			]
-		});
+		}]);
 	};
 
 	// the following functions shall not work after the first rendering
@@ -1228,19 +1314,6 @@ sap.ui.define([
 		return aPluginNames.join(",");
 	};
 
-
-
-	/**
-	 * Checks whether TinyMCE has rendered its HTML
-	 *
-	 * @returns {boolean} Whether TinyMCE is rendered inside the page
-	 * @private
-	 */
-	RichTextEditor.prototype.tinyMCEReady = function() {
-		var iframe = (this._iframeId ? window.document.getElementById(this._iframeId) : null);
-		return !!iframe;
-	};
-
 	/**
 	 * Event handler being called when the text in the editor has changed
 	 *
@@ -1335,7 +1408,7 @@ sap.ui.define([
 	/**
 	 * Determines if a new TinyMCE instance should be loaded.
 	 * @private
-	 * @returns {boolean}
+	 * @returns {boolean} Whether tinyMCE should be loaded.
 	 */
 	RichTextEditor.prototype._shouldLoadTinyMCE = function () {
 		var sEditorType = this.getEditorType();
@@ -1480,6 +1553,7 @@ sap.ui.define([
 	 * @private
 	 */
 	RichTextEditor.prototype.setValueTinyMCE = function(sValue) {
+
 		switch (this._tinyMCEStatus) {
 			case EditorStatus.Initial:
 			case EditorStatus.Initializing:
@@ -1629,6 +1703,8 @@ sap.ui.define([
 			oToolbarDOM.setAttribute("aria-roledescription", oResourceBundle.getText("CUSTOM_TOOLBAR_ARIA_ROLEDESCRIPTION"));
 		}
 
+		this._oEditor.getContainer().classList.add("sapUiRteEditorContainer");
+
 		// TODO: make sure ready is fired if no reinitializations are pending
 		this.fireReadyTinyMCE();
 	};
@@ -1696,7 +1772,7 @@ sap.ui.define([
 	/**
 	 * Helper function for evaluating the textDirection of the tinyMCE's content config
 	 *
-	 * @returns {sString} Text direction
+	 * @returns {string} Text direction
 	 * @private
 	 */
 	RichTextEditor.prototype._getTextDirection = function() {
@@ -1779,7 +1855,7 @@ sap.ui.define([
 	 * @returns {string} The language to be used for TinyMCE
 	 */
 	RichTextEditor.prototype._getLanguageTinyMCE = function() {
-		var oLocale = new sap.ui.core.Locale(Core.getConfiguration().getLanguage()),
+		var oLocale = new Locale(Core.getConfiguration().getLanguage()),
 			sLanguage = oLocale.getLanguage(),
 			sRegion = oLocale.getRegion(),
 			bIsTinyMCE5 = this.getEditorType() === RichTextEditor.EDITORTYPE_TINYMCE5,

package/src/sap/ui/richtexteditor/RichTextEditorRenderer.js

@@ -10,8 +10,7 @@ sap.ui.define(['sap/ui/core/Core'],
 
 	/**
 	 * RichTextEditorRenderer
-	 * @class
-	 * @static
+	 * @namespace
 	 * @author Malte Wedel, Andreas Kunz
 	 */
 	var RichTextEditorRenderer = {