@openui5/sap.ui.mdc 1.95.0 → 1.96.3

package/src/sap/ui/mdc/valuehelp/base/Content.js

@@ -32,12 +32,12 @@ sap.ui.define([
 	 * @param {object} [mSettings] Initial settings for the new control
 	 * @class Content for the <code>sap.ui.mdc.valuehelp.base.Container</code> element.
 	 * @extends sap.ui.core.Element
-	 * @version 1.95.0
+	 * @version 1.96.3
 	 * @constructor
 	 * @abstract
 	 * @private
 	 * @ui5-restricted sap.ui.mdc
-	 * @since 1.91.0
+	 * @since 1.95.0
 	 * @alias sap.ui.mdc.valuehelp.base.Content
 	 * @ui5-metamodel This control/element also will be described in the UI5 (legacy) designtime metamodel
 	 */
@@ -47,34 +47,50 @@ sap.ui.define([
 			library: "sap.ui.mdc",
 			properties: {
                 /**
-				 * Title text that appears in the dialog or tab header.
-				 *
-				 * @since 1.60.0
+				 * Title text that appears tab header.
 				 */
 				title: {
 					type: "string",
 					group: "Appearance",
 					defaultValue: ""
 				},
-				subTitle: {
+                /**
+				 * Title text that appears in the dialog header.
+				 */
+				shortTitle: {
 					type: "string",
 					group: "Appearance",
 					defaultValue: ""
 				},
-				_conditions: { // TODO: only internal? make restricted?
+				/**
+				 * Conditions of the value help
+				 *
+				 * <b>Note:</b> This property must not be set from outside, it is only to be used by the corresponding container
+				 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+				 */
+				conditions: { // TODO: only internal? make restricted?
 					type: "object[]",
 					defaultValue: [],
 					byValue: true
 				},
-				_filterValue: { // TODO: how to hide? Or how to access from ValueHelp?
+				/**
+				 * Value for filtering ($search)
+				 *
+				 * <b>Note:</b> This property must not be set from outside, it is only to be used by the corresponding container
+				 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+				 */
+				filterValue: { // TODO: how to hide? Or how to access from ValueHelp?
 					type: "string",
 					defaultValue: ""//,
 					//visibility: "hidden"
 				},
 				/**
 				 * internal configuration
+				 *
+				 * <b>Note:</b> This property must not be set from outside, it is only to be used by the corresponding container
+				 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
 				 */
-				_config: {
+				config: {
 					type: "object",
 					defaultValue: {}//,
 //					visibility: "hidden"
@@ -82,33 +98,77 @@ sap.ui.define([
 
 			},
 			aggregations: {
-				_displayContent: {
+				/**
+				 * Content control that is put inside the parent container
+				 *
+				 * <b>Note:</b> This aggregation must not be set from outside, it is only to be used by the corresponding container
+				 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+				 */
+				displayContent: {
 					type: "sap.ui.core.Control",
 					multiple: false//,
 					//visibility: "hidden" // as ManagedObjectModel can only observe hidden aggregations on root-control
 				}
 			},
 			events: {
+				/**
+				 * Fired if the selected condition changed.
+				 */
 				select: {
 					parameters: {
+						/**
+						 * Type of the selection change (add, remove)
+						 */
 						type: { type: "sap.ui.mdc.enum.SelectType" },
+						/**
+						 * Changed conditions
+						 *
+						 * <b>Note:</b> A condition must have the structure of {@link sap.ui.mdc.condition.ConditionObject ConditionObject}.
+						 */
 						conditions: { type: "object[]" }
 					}
 				},
-				requestDelegateContent: {},
-				requestSwitchToDialog: {},
+				/**
+				 * Fired if a change on the content is confirmed
+				 */
 				confirm: {
 					parameters: {
+						/**
+						 * True if the value help need to be closed
+						 */
 						close: { type: "boolean" }
 					}
 				},
+				/**
+				 * Fired if the change is cancelled.
+				 */
 				cancel: {},
+				/**
+				 * Fired if the content requests the delegate content.
+				 */
+				requestDelegateContent: {},
+				/**
+				 * Fired if the value help should switch to dialog mode.
+				 */
+				requestSwitchToDialog: {},
+				/**
+				 * Fired if a navigation was executed in the content
+				 */
 				navigated: {
 					parameters: {
-						leaveFocus: { type: "boolean" },
+						/**
+						 * True if the focus should be set back to the field.
+						 */
+						bLeaveFocus: { type: "boolean" },
+						/**
+						 * Navigated condition.
+						 *
+						 * <b>Note:</b> A condition must have the structure of {@link sap.ui.mdc.condition.ConditionObject ConditionObject}.
+						 */
 						condition: { type: "object" },
-//						value: { type: "string" },
-//						key: { type: "string" },
+						/**
+						 * ID of the navigated item. (This is needed to set the corresponding aria-attribute)
+						 */
 						itemId: { type: "string" }
 					}
 				}
@@ -121,7 +181,7 @@ sap.ui.define([
 		this._oObserver = new ManagedObjectObserver(this._observeChanges.bind(this));
 
 		this._oObserver.observe(this, {
-			properties: ["_filterValue", "_conditions", "_config"]
+			properties: ["filterValue", "conditions", "config"]
 		});
 
 	};
@@ -137,7 +197,7 @@ sap.ui.define([
 
 		// don't rerender content or parent-container on conditions change. This needs only be updated on
 		// content control inside (Table, List, DefineConditionPanel...).
-		if (sPropertyName === "_conditions") {
+		if (sPropertyName === "conditions" || sPropertyName === "filterValue" || sPropertyName === "config") {
 			bSuppressInvalidate = true;
 		}
 
@@ -146,29 +206,104 @@ sap.ui.define([
 	};
 
 
+	/**
+	 * Gets the content controls
+	 *
+	 * @returns {Promise<sap.ui.core.Control>} This promise resolves after the content is created
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 */
 	Content.prototype.getContent = function () {
 
 	};
 
-	Content.prototype.getFooterContent = function () {
+	/**
+	 * Provides a configuration map for supported containers
+	 *
+	 * @example
+	 * 	// Example configuration:
+	 * 	{
+	 *		'sap.ui.mdc.valuehelp.MyCustomContainer': {
+	 *			showArrow: true,
+	 *			showHeader: true,
+ 				getFooter: function () { Promise.resolve(oFooter); },
+	 *			getContentWidth: function () { return "500px"; },
+	 			getContentHeight: function () { ... },
+	 *		}
+	 *	}
+	 * @returns {object|undefined} if available, a container configuration object is returned.
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	Content.prototype.getContainerConfig = function () {
 
 	};
 
+	/**
+	 * Called if the content will be shown.
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 */
 	Content.prototype.onShow = function () {
 		this._bVisible = true;
 		this._handleConditionsUpdate();
 		//this._handleFilterValueUpdate();
 	};
 
+	/**
+	 * Called if the content will be hidden.
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 */
 	Content.prototype.onHide = function () {
 		this._bVisible = false;
 	};
 
+	/**
+	 * Determines the item (key and description) for a given value.
+	 *
+	 * The content checks if there is an item with a key or description that fits this value.
+	 *
+	 * <b>Note:</b> This function must only be called by the <code>Container</code> element.
+	 *
+	 * @param {object} oConfig Configuration
+	 * @param {any} oConfig.value Value as entered by user
+	 * @param {any} [oConfig.parsedValue] Value parsed by type to fit the data type of the key
+	 * @param {object} [oConfig.inParameters] In parameters for the key (as a key must not be unique.)
+	 * @param {object} [oConfig.outParameters] Out parameters for the key (as a key must not be unique.)
+	 * @param {sap.ui.model.Context} [oConfig.bindingContext] <code>BindingContext</code> of the checked field. Inside a table the <code>ValueHelp</code> element might be connected to a different row.
+	 * @param {boolean} [oConfig.checkKeyFirst] If set, the content checks first if the value fits a key // TODO: not longer needed?
+	 * @param {boolean} oConfig.checkKey If set, the content checks only if there is an item with the given key. This is set to <code>false</code> if the value cannot be a valid key because of type validation.
+	 * @param {boolean} oConfig.checkDescription If set, the content checks only if there is an item with the given description. This is set to <code>false</code> if only the key is used in the field.
+	 * @param {sap.ui.mdc.condition.ConditionModel} [oConfig.conditionModel] <code>ConditionModel</code>, in case of <code>FilterField</code>
+	 * @param {string} [oConfig.conditionModelName] Name of the <code>ConditionModel</code>, in case of <code>FilterField</code>
+	 * @param {boolean} [oConfig.caseSensitive] If set, the check is done case sensitive
+	 * @returns {Promise<sap.ui.mdc.field.FieldHelpItem>} Promise returning object containing description, key, in and out parameters.
+	 * @throws {sap.ui.model.FormatException|sap.ui.model.ParseException} if entry is not found or not unique
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Content.prototype.getItemForValue = function (oConfig) {
 
 	};
 
-	Content.prototype.isValidationSupported = function(oConfig) { // TODO only for TypeAhead content
+	/**
+	 * Defines if the content can be used for input validation.
+	 *
+	 * @returns {boolean} True if content can be used for input validation
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	Content.prototype.isValidationSupported = function() { // TODO only for TypeAhead content
+		return false;
 	};
 
 	Content.prototype.getScrollDelegate = function() {
@@ -177,15 +312,15 @@ sap.ui.define([
 	};
 
 	Content.prototype._observeChanges = function(oChanges) {
-		if (oChanges.name === "_conditions") {
+		if (oChanges.name === "conditions") {
 			this._handleConditionsUpdate(oChanges);
 		}
 
-		if (oChanges.name === "_filterValue") {
+		if (oChanges.name === "filterValue") {
 			this._handleFilterValueUpdate(oChanges);
 		}
 
-		if (oChanges.name === "_config") {
+		if (oChanges.name === "config") {
 			_configChanged.call(this, oChanges.current);
 		}
 	};
@@ -201,20 +336,20 @@ sap.ui.define([
 	/**
 	 * Creates a condition based on the used operator.
 	 *
-	 * @param {string} sKey Operator for the condition
-	 * @param {string} sDescription Description of the operator
-	 * @param {object} oInParameters In parameters of the condition
-	 * @param {object} oOutParameters Out parameters of the condition
+	 * @param {string} vValue Value of the condition. For item conditions this must be the key.
+	 * @param {string} [sDescription] Description of the operator
+	 * @param {object} [oInParameters] In parameters of the condition
+	 * @param {object} [oOutParameters] Out parameters of the condition
 	 * @returns {sap.ui.mdc.condition.ConditionObject} The new condition object with the maintained operator along with <code>sKey</code> and <code>sDescription</code> as <code>aValues</code>
 	 * @private
 	 * @ui5-restricted FieldHelp subclasses
 	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
 	 */
-	Content.prototype._createCondition = function(sKey, sDescription, oInParameters, oOutParameters) {
+	Content.prototype._createCondition = function(vValue, sDescription, oInParameters, oOutParameters) {
 
 		var oOperator = _getOperator.call(this);
 
-		var aValues = [sKey];
+		var aValues = [vValue];
 		if (oOperator.valueTypes.length > 1 && oOperator.valueTypes[1] !== Operator.ValueType.Static && sDescription !== null && sDescription !== undefined) {
 			// description is supported
 			aValues.push(sDescription);
@@ -237,6 +372,20 @@ sap.ui.define([
 
 	};
 
+	/**
+	 * Triggers navigation in the content.
+	 *
+	 * As this could be asyncron as data might be loaded a promise is returned.
+	 *
+	 * <b>Note:</b> This function must only be called by the <code>Container</code> element.
+	 *
+	 * @param {int} iStep Number of steps for navigation (e.g. 1 means next item, -1 means previous item)
+	 * @returns {Promise<object>} Promise returning object of navigated item (condition and itemId)
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valueHelp.base.Container
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Content.prototype.navigate = function(iStep) {
 
 	};
@@ -251,6 +400,16 @@ sap.ui.define([
 		return Element.prototype.getUIArea.apply(this, arguments);
 	};
 
+	/**
+	 * Determines if the container of the content is used as typeAhead inside the value help
+	 *
+	 * <b>Note:</b> This function is used by the content and must not be used from outside
+	 *
+	 * @returns {boolean} True if used as typeahead
+	 *
+	 * @private
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Content.prototype.isTypeahead = function () {
 		var oContainer = this.getParent();
 		return oContainer && oContainer.isTypeahead();
@@ -271,6 +430,11 @@ sap.ui.define([
 		return oContainer && oContainer.getValueHelpDelegate();
 	};
 
+	Content.prototype._getValueHelpDelegatePayload = function () {
+		var oContainer = this.getParent();
+		return oContainer && oContainer.getValueHelpDelegatePayload();
+	};
+
 	Content.prototype._awaitValueHelpDelegate = function () {
 		var oContainer = this.getParent();
 		return oContainer && oContainer.awaitValueHelpDelegate();
@@ -325,8 +489,7 @@ sap.ui.define([
 	};
 
 	Content.prototype._isSingleSelect = function (oEvent) {
-		var oConfig = this.getProperty("_config");
-		return oConfig && oConfig.maxConditions === 1;
+		return this._getMaxConditions() === 1;
 	};
 
 	/**
@@ -415,6 +578,18 @@ sap.ui.define([
 		return this._oOperator;
 	}
 
+	/**
+	 * Determines the title used in the TabBar of the dialog.
+	 *
+	 * <b>Note:</b> This function is used by the container and must not be used from outside
+	 *
+	 * @param {int} iCount Number of selected items or conditions
+	 * @returns {string} title
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Content.prototype.getFormattedTitle = function(iCount) {
 		var sTitle = this.getTitle();
 		if (sTitle) {
@@ -423,13 +598,24 @@ sap.ui.define([
 		return sTitle;
 	};
 
-	Content.prototype.getFormattedSubTitle = function() {
-		return this.getSubTitle();
+	/**
+	 * Determines the title used in the header of the dialog.
+	 *
+	 * <b>Note:</b> This function is used by the container and must not be used from outside
+	 *
+	 * @returns {string} title
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valuehelp.base.Container
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	Content.prototype.getFormattedShortTitle = function() {
+		return this.getShortTitle();
 	};
 
 	Content.prototype._getMaxConditions = function() {
 
-		var oConfig = this.getProperty("_config");
+		var oConfig = this.getConfig();
 		return oConfig && oConfig.maxConditions;
 
 	};

package/src/sap/ui/mdc/valuehelp/base/DialogTab.js

@@ -5,33 +5,76 @@
  */
 
 sap.ui.define([
-	'sap/ui/core/Control',
-	'sap/ui/base/ManagedObjectObserver'
+	'sap/ui/core/Control'//,
+	//'sap/ui/base/ManagedObjectObserver'
 ], function(
-	Control,
-	ManagedObjectObserver
+	Control//,
+	//ManagedObjectObserver
 ) {
 	"use strict";
 
+	/**
+	 * Constructor for a new <code>DialogTab</code>.
+	 *
+	 * @param {string} [sId] ID for the new control, generated automatically if no ID is given
+	 * @param {object} [mSettings] Initial settings for the new control
+	 * @class Content for the <code>sap.ui.mdc.valuehelp.content.Dialog</code> element.
+	 * @extends sap.ui.core.Control
+	 * @version 1.96.3
+	 * @constructor
+	 * @abstract
+	 * @private
+	 * @ui5-restricted sap.ui.mdc
+	 * @since 1.95.0
+	 * @alias sap.ui.mdc.valuehelp.base.DialogTab
+	 * @ui5-metamodel This control/element also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	var DialogTab = Control.extend("sap.ui.mdc.valuehelp.base.DialogTab", /** @lends sap.ui.mdc.valuehelp.base.DialogTab.prototype */
 	{
 		metadata: {
 			library: "sap.ui.mdc",
 			properties: {
+				/**
+				 * Content control
+				 */
 				content: {
-					type: "object"
+					type: "object" // as a Control can officially not be a property
 				}
 			},
 			// aggregations: {
 			// },
 			events: {
-				select: {
+				/**
+				 * Fired if the selected condition changed.
+				 */
+				 select: {
 					parameters: {
+						/**
+						 * Type of the selection change (add, remove)
+						 */
 						type: { type: "sap.ui.mdc.enum.SelectType" },
+						/**
+						 * Changed conditions
+						 *
+						 * <b>Note:</b> A condition must have the structure of {@link sap.ui.mdc.condition.ConditionObject ConditionObject}.
+						 */
 						conditions: { type: "object[]" }
 					}
 				},
-				confirm: {},
+				/**
+				 * Fired if a change on the content is confirmed
+				 */
+				 confirm: {
+					parameters: {
+						/**
+						 * True if the value help need to be closed
+						 */
+						close: { type: "boolean" }
+					}
+				},
+				/**
+				 * Fired if the change is cancelled.
+				 */
 				cancel: {}
 			}
 		},