@openui5/sap.ui.mdc 1.95.0 → 1.96.3

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

@@ -24,12 +24,12 @@ sap.ui.define([
 	 * @param {object} [mSettings] Initial settings for the new control
 	 * @class Container for the <code>ValueHelp</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.Container
 	 * @ui5-metamodel This control/element also will be described in the UI5 (legacy) designtime metamodel
 	 */
@@ -48,43 +48,94 @@ sap.ui.define([
 				}
 			},
 			aggregations: {
+				/**
+				 * Used container element. (e.g. Popover or Dialog)
+				 */
 				_container: {
 					type: "sap.ui.core.Element",
 					multiple: false,
 					visibility: "hidden"
 				},
-				content: {
+				/**
+				 * Content of the container.
+				 * This aggregation holds the actual controls enabling the user to select items or create conditions (e.g. tables or condition panels)
+				 */
+				 content: {
 					type: "sap.ui.mdc.valuehelp.base.Content",
 					multiple: true
 				}
 			},
 			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[]" }
 					}
 				},
+				/**
+				 * Fired if a change on the value help is confirmed
+				 */
 				confirm: {
 					parameters: {
+						/**
+						 * True if the value help needs to be closed
+						 */
 						close: { type: "boolean" }
 					}
 				},
+				/**
+				 * Fired if the value help is opened.
+				 */
 				opened: {},
+				/**
+				 * Fired if the value help is closed.
+				 */
 				closed: {},
+				/**
+				 * Fired if the change is cancelled.
+				 */
 				cancel: {},
+				/**
+				 * Fired if the Container requests the delegate content.
+				 */
 				requestDelegateContent: {
 					parameters: {
 						container: { type: "sap.ui.mdc.valuehelp.base.Container" }
 					}
 				},
+				/**
+				 * Fired if the value help should switch to dialog mode.
+				 */
 				requestSwitchToDialog: {},
+				/**
+				 * Fired if a navigation was executed in the content of the container
+				 */
 				navigated: {
 					parameters: {
+						/**
+						 * 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" }
 					}
 				}
@@ -103,9 +154,9 @@ sap.ui.define([
 		if (oChanges.name === "content") {
 			var oContent = oChanges.child;
 			if (oChanges.mutation === "remove") {
-				oContent.unbindProperty("_filterValue");
-				oContent.unbindProperty("_conditions");
-				oContent.unbindProperty("_config");
+				oContent.unbindProperty("filterValue");
+				oContent.unbindProperty("conditions");
+				oContent.unbindProperty("config");
 				oContent.detachConfirm(this._handleConfirmed, this);
 				oContent.detachCancel(this._handleCanceled, this);
 				oContent.detachSelect(this._handleSelect, this);
@@ -120,13 +171,13 @@ sap.ui.define([
 				}
 
 			} else {
-				oContent.bindProperty("_filterValue", { path: "/filterValue", model: "$valueHelp", mode: BindingMode.OneWay}); // inherit from ValueHelp
+				oContent.bindProperty("filterValue", { path: "/filterValue", model: "$valueHelp", mode: BindingMode.OneWay}); // inherit from ValueHelp
 				var oBindingOptions = { path: "/conditions", model: "$valueHelp", mode: BindingMode.OneWay};
 				if (oContent._formatConditions) {
 					oBindingOptions.formatter = oContent._formatConditions.bind(oContent);
 				}
-				oContent.bindProperty("_conditions", oBindingOptions); // inherit from ValueHelp
-				oContent.bindProperty("_config", { path: "/_config", model: "$valueHelp", mode: BindingMode.OneWay}); // inherit from ValueHelp
+				oContent.bindProperty("conditions", oBindingOptions); // inherit from ValueHelp
+				oContent.bindProperty("config", { path: "/_config", model: "$valueHelp", mode: BindingMode.OneWay}); // inherit from ValueHelp
 
 				oContent.attachConfirm(this._handleConfirmed, this);
 				oContent.attachCancel(this._handleCanceled, this);
@@ -170,7 +221,8 @@ sap.ui.define([
 	};
 
 	Container.prototype.getDomRef = function() {
-		// need to be implemented by real container
+		var oContainer = this.getAggregation("_container");
+		return oContainer && oContainer.getDomRef();
 	};
 
 	Container.prototype.getUIArea = function() { // TODO: Ask Frank, if better way available
@@ -184,6 +236,7 @@ sap.ui.define([
 	/**
 	 * Opens the container
 	 *
+	 * @param {Promise} oValueHelpContentPromise Promise for content request
 	 * @returns {Promise} This promise resolves after the container completely opened.
 	 *
 	 * @private
@@ -208,8 +261,6 @@ sap.ui.define([
 	/**
 	 * Closes the container
 	 *
-	 * @returns {Promise} This promise resolves after the container completely closed.
-	 *
 	 * @private
 	 * @ui5-restricted sap.ui.mdc.ValueHelp
 	 */
@@ -261,23 +312,95 @@ sap.ui.define([
 		this.fireSelect({type: oEvent.getParameter("type"), conditions: oEvent.getParameter("conditions")});
 	};
 
-	Container.prototype.isOpen = function () {
+	/**
+	 * Determines if the container is open.
+	 *
+	 * <b>Note:</b> This function must only be called by the <code>ValueHelp</code> element.
+	 *
+	 * @returns {boolean} true if open or opening
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.ValueHelp
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	 Container.prototype.isOpen = function () {
 		var oPromise = this._retrievePromise("open");
 		return oPromise && oPromise.isSettled();
 	};
 
-	Container.prototype.isOpening = function () {
+	/**
+	 * Determines if the container is opening.
+	 *
+	 * <b>Note:</b> This function must only be called by the <code>ValueHelp</code> element.
+	 *
+	 * @returns {boolean} true if opening
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.ValueHelp
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	 Container.prototype.isOpening = function () {
 		var oPromise = this._retrievePromise("open");
 		return oPromise && !oPromise.isCanceled() && !oPromise.isSettled();
 	};
 
+	/**
+	 * Determines the item (key and description) for a given value.
+	 *
+	 * The container 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>ValueHelp</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 container checks first if the value fits a key // TODO: not longer needed?
+	 * @param {boolean} oConfig.checkKey If set, the container 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 container 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
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Container.prototype.getItemForValue = function(oConfig) { // TODO only for TypeAhead container
 	};
 
-	Container.prototype.isValidationSupported = function(oConfig) { // TODO only for TypeAhead container
+	/**
+	 * Defines if the content of the container can be used for input validation.
+	 *
+	 * @returns {boolean} True if content can be used for input validation
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.ValueHelp
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	 Container.prototype.isValidationSupported = function() { // TODO only for TypeAhead container
+		return false;
 	};
 
 
+	/**
+	 * Triggers navigation in the content of the container.
+	 *
+	 * As this could be asynchronous in case additional data needs to be loaded a promise is returned.
+	 *
+	 * <b>Note:</b> This function must only be called by the <code>ValueHelp</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
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Container.prototype.navigate = function(iStep) { // pass through to content
 		return Promise.all([this._getContainer()]).then(function (aResults) {
 			return this._placeContent(aResults[0]);
@@ -299,22 +422,84 @@ sap.ui.define([
 	Container.prototype.removeFocus = function() {
 	};
 
+	/**
+	 * Determines if the container is used as typeahead inside the value help
+	 *
+	 * <b>Note:</b> This function is used by the container and content and must not be used from outside
+	 *
+	 * @returns {boolean} True if used as typeahead
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valueHelp.base.Content
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Container.prototype.isTypeahead = function () {
 		var oValueHelp = this.getParent();
 		return oValueHelp && oValueHelp.getTypeahead() === this;
 	};
 
+	/**
+	 * Determines the delegate of the value help
+	 *
+	 * <b>Note:</b> This function is used by the container and content and must not be used from outside
+	 *
+	 * @returns {sap.ui.mdc.BaseDelegate} <code>typeUtil</code> made available by a delegate module
+	 * @throws Throws an error if the delegate module is not available
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valueHelp.base.Content
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
 	Container.prototype.getValueHelpDelegate = function () {
 		var oValueHelp = this.getParent();
 		return oValueHelp && oValueHelp.getControlDelegate();
 	};
 
-	Container.prototype.awaitValueHelpDelegate = function () {
+	/**
+	 * Determines the delegate payload of the value help
+	 *
+	 * <b>Note:</b> This function is used by the container and content and must not be used from outside
+	 *
+	 * @returns {object} payload
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valueHelp.base.Content
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	 Container.prototype.getValueHelpDelegatePayload = function () {
+		var oValueHelp = this.getParent();
+		return oValueHelp && oValueHelp.getPayload();
+	};
+
+	/**
+	 * Provides access to the delegate initialization <code>Promise</code> of the value help.
+	 *
+	 * <b>Note:</b> This function is used by the container and content and must not be used from outside
+	 *
+	 * @returns {Promise} Returns a <code>Promise</code> reflecting the delegate initialization
+	 * @throws Throws an error if the delegate module is not available
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valueHelp.base.Content
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	 Container.prototype.awaitValueHelpDelegate = function () {
 		var oValueHelp = this.getParent();
 		return oValueHelp && oValueHelp.awaitControlDelegate();
 	};
 
-	Container.prototype.isValueHelpDelegateInitialized = function () {
+	/**
+	 * Determines if delegate of the value help is initialized
+	 *
+	 * <b>Note:</b> This function is used by the container and content and must not be used from outside
+	 *
+	 * @returns {boolean} True if delegate is initialized
+	 *
+	 * @private
+	 * @ui5-restricted sap.ui.mdc.valueHelp.base.Content
+	 * @ui5-metamodel This method also will be described in the UI5 (legacy) designtime metamodel
+	 */
+	 Container.prototype.isValueHelpDelegateInitialized = function () {
 		var oValueHelp = this.getParent();
 		return oValueHelp && oValueHelp.bDelegateInitialized;
 	};
@@ -428,6 +613,23 @@ sap.ui.define([
 
 	};
 
+	Container.prototype._getContainerConfig = function (oContent) {
+		var oConfig = oContent && oContent.getContainerConfig();
+		var oResult = oConfig && oConfig[this.getMetadata().getName()];	// find configuration for this exact type
+
+		if (!oResult && oConfig) {	// search for configurations of other implemented types
+			var aTypes = Object.keys(oConfig);
+			var sNonSpecificType = aTypes.find(function (sType) {
+				return this.isA(sType);
+			}.bind(this));
+			if (sNonSpecificType) {
+				oResult = oConfig[sNonSpecificType];
+			}
+		}
+
+		return oResult;
+	};
+
 	Container.prototype.exit = function() {
 		this._oObserver.disconnect();
 		this._oObserver = undefined;