@openui5/sap.m 1.103.1 → 1.104.0

package/src/sap/m/p13n/modules/AdaptationProvider.js

@@ -0,0 +1,67 @@
+/*
+* ! OpenUI5
+ * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
+*/
+sap.ui.define([
+	"sap/ui/base/Object"
+], function(BaseObject) {
+	"use strict";
+
+	/**
+	 * @class Interface to implement basic adaptation functionality.
+	 * Implementing this interface enables the usage of certain p13n
+	 * modules such as the UIManager and the DefaultProviderRegistry.
+	 *
+	 * @author SAP SE
+	 * @since 1.104
+	 * @private
+     *
+	 * @ui5-restricted sap.m
+	 * @alias sap.m.p13n.AdaptationProvider
+	 */
+	var AdaptationProvider = BaseObject.extend("sap.m.p13n.AdaptationProvider", {
+		metadata: {
+			baseType : "sap.m.p13n.AdaptationProvider"
+		}
+	});
+
+	/**
+	 * Initialize adaptation for a provided control instance, set of keys and properties
+	 *
+	 * @param {string|sap.ui.core.Control} vControl The control id or instance
+	 * @param {Array} aKeys An Array of keys
+	 * @param {Array} [aCustomInfo] An Array of propertyinfos
+	 *
+	 * @returns {Promise} A Promise resolving in the according property helper instance
+	 */
+	AdaptationProvider.prototype.initAdaptation = function(vControl, aKeys, aCustomInfo){
+		throw new Error("Please implement 'initAdaptation'");
+	};
+
+	/**
+	 * Reset the personalization for a provided control instance and key
+	 *
+	 * @param {sap.ui.core.Control} oControl The control instance
+	 * @param {string} sKey Key to be affected by reset
+	 *
+	 * @returns {Promise} A Promise resolving after the reset has been processed
+	 */
+	AdaptationProvider.prototype.reset = function(oControl, sKey){
+		throw new Error("Please implement 'reset'");
+	};
+
+	/**
+	 * Reset the personalization for a provided control instance and key
+	 *
+	 * @param {sap.ui.core.Control} oControl The control instance
+	 * @param {Array} aKeys An Array of keys
+	 *
+	 * @returns {Promise} A Promise resolving after all changes have been processed
+	 */
+	AdaptationProvider.prototype.handleP13n = function(oControl, aKeys){
+		throw new Error("Please implement 'handleP13n'");
+	};
+
+	return AdaptationProvider;
+});

package/src/sap/m/p13n/modules/DefaultProviderRegistry.js

@@ -0,0 +1,124 @@
+/*
+ * ! OpenUI5
+ * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
+ */
+
+sap.ui.define([
+	"sap/ui/base/Object",
+	"sap/m/p13n/PersistenceProvider"
+], function (BaseObject, PersistenceProvider) {
+	"use strict";
+
+	var ERROR_INSTANCING = "DefaultProviderRegistry: This class is a singleton and should not be used without an AdaptationProvider. Please use 'sap.m.p13n.Engine.getInstance().defaultProviderRegistry' instead";
+
+	//Singleton storage
+	var oDefaultProviderRegistry;
+
+	/**
+	 * Constructor for a new DefaultProviderRegistry.
+	 * This registry creates and manages default persistence providers for each persistence mode.
+	 * It is intended for use cases where no dedicated provider can or should be created by an application.
+	 * The DefaultProviderRegistry currently resides in the Engine and must never be called separately.
+	 *
+	 * @class
+	 * @extends sap.ui.base.Object
+	 *
+	 * @author SAP SE
+	 * @version 1.104.0
+	 *
+	 * @private
+	 * @since 1.104
+	 * @alias sap.m.p13n.modules.DefaultProviderRegistry
+	 */
+	var DefaultProviderRegistry = BaseObject.extend("sap.m.p13n.modules.DefaultProviderRegistry", {
+		constructor: function() {
+
+			if (oDefaultProviderRegistry) {
+				throw Error(ERROR_INSTANCING);
+			}
+
+			BaseObject.call(this);
+			this._mDefaultProviders = {};
+		}
+	});
+
+	/**
+	 * @override
+	 * @inheritDoc
+	 */
+	DefaultProviderRegistry.prototype.destroy = function() {
+		Object.keys(this._mDefaultProviders).forEach(function (sProviderName) {
+			this._mDefaultProviders[sProviderName].destroy();
+			delete this._mDefaultProviders[sProviderName];
+		}.bind(this));
+		BaseObject.prototype.destroy.apply(this, arguments);
+	};
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * Attaches a control to a default persistence provider held inside the DefaultProviderRegistry for the given <code>PersistenceMode</code>
+	 *
+	 * @param {sap.m.Control|string} vControl The control instance or a control id.
+	 * @param {sap.m.enum.PersistenceMode} sPersistenceMode Desired persistence mode for the retrieved persistence provider
+	 * @returns {sap.m.p13n.PersistenceProvider} Returns a persistence provider instance, if possible
+	 */
+	DefaultProviderRegistry.prototype.attach = function (vControl, sPersistenceMode) {
+		if (vControl.getEngine().isRegisteredForModification(vControl)) { // Modification settings for a registered control are only determined once in the Engine
+			throw new Error("DefaultProviderRegistry: You must not change the modificationSettings for an already registered control");
+		}
+		var oDefaultProvider = this._retrieveDefaultProvider(sPersistenceMode);
+		var sControlId = typeof vControl === "string" ? vControl : vControl.getId();
+		if (oDefaultProvider.getFor().indexOf(sControlId) === -1) {
+			oDefaultProvider.addFor(vControl);
+		}
+
+		return oDefaultProvider;
+	};
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * Detaches a control from any existing default persistence provider
+	 *
+	 * @param {sap.m.Control|string} vControl The control instance or a control id.
+	 */
+	DefaultProviderRegistry.prototype.detach = function (vControl) {
+		Object.keys(this._mDefaultProviders).forEach(function (sMode) {
+			var oDefaultProvider = this._mDefaultProviders[sMode];
+			oDefaultProvider.removeFor(vControl);
+		}.bind(this));
+	};
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * Returns a promise resolving a default persistence provider for the given <code>Control</code> and <code>PersistenceMode</code>.
+	 *
+	 * @param {sap.m.enum.PersistenceMode} sPersistenceMode Desired persistence mode for the retrieved persistence provider
+	 * @returns {Promise} Returns a <code>Promise</code> returning a persistence provider instance, if possible
+	 */
+	DefaultProviderRegistry.prototype._retrieveDefaultProvider = function (sPersistenceMode) {
+		this._mDefaultProviders[sPersistenceMode] = this._mDefaultProviders[sPersistenceMode] || new PersistenceProvider({mode: sPersistenceMode});
+		return this._mDefaultProviders[sPersistenceMode];
+	};
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * This method is the central point of access to the DefaultProviderRegistry Singleton.
+	 */
+	 DefaultProviderRegistry.getInstance = function() {
+		if (!oDefaultProviderRegistry) {
+			oDefaultProviderRegistry = new DefaultProviderRegistry();
+		}
+		return oDefaultProviderRegistry;
+	};
+
+	return DefaultProviderRegistry;
+});

package/src/sap/m/p13n/modules/StateHandlerRegistry.js

@@ -0,0 +1,101 @@
+/*
+ * ! OpenUI5
+ * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
+ */
+
+sap.ui.define([
+	"sap/ui/base/EventProvider"
+], function (EventProvider) {
+	"use strict";
+
+	var ERROR_INSTANCING = "StateHandlerRegistry: This class is a singleton and should not be used without an AdaptationProvider. Please use 'sap.m.p13n.Engine.getInstance().stateHandlerRegistry' instead";
+
+	//Singleton storage
+	var oStateHandlerRegistry;
+
+	/**
+	 * Constructor for a new StateHandlerRegistry.
+	 *
+	 * @class
+	 * @extends sap.ui.base.Object
+	 *
+	 * @author SAP SE
+	 * @version 1.104.0
+	 *
+	 * @private
+	 * @since 1.104
+	 * @alias sap.m.p13n.modules.StateHandlerRegistry
+	 */
+	var StateHandlerRegistry = EventProvider.extend("sap.m.p13n.modules.StateHandlerRegistry", {
+		constructor: function() {
+
+			if (oStateHandlerRegistry) {
+				throw Error(ERROR_INSTANCING);
+			}
+
+			EventProvider.call(this);
+		}
+	});
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * Attaches an event handler to the <code>StateHandlerRegistry</code> class.
+	 * The event handler may be fired every time a user triggers a personalization change for a control instance during runtime.
+	 *
+	 * @param {function} fnStateEventHandler The handler function to call when the event occurs
+	 * @returns {this} Returns <code>this</code> to allow method chaining
+	 */
+	StateHandlerRegistry.prototype.attachChange = function(fnStateEventHandler) {
+		return EventProvider.prototype.attachEvent.call(this, "stateChange", fnStateEventHandler);
+	};
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * Removes a previously attached state change event handler from the <code>StateHandlerRegistry</code> class.
+	 * The passed parameters must match those used for registration with {@link StateHandlerRegistry#attachChange} beforehand.
+	 *
+	 * @param {function} fnStateEventHandler The handler function to detach from the event
+	 * @returns {this} Returns <code>this</code> to allow method chaining
+	 */
+	StateHandlerRegistry.prototype.detachChange = function(fnStateEventHandler) {
+		return EventProvider.prototype.detachEvent.call(this, "stateChange", fnStateEventHandler);
+	};
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * Fires an {@link sap.ui.base.Event event} with the given settings and notifies all attached event handlers.
+	 *
+	 * @param {sap.m.Control} oControl The control instance
+	 * @param {object} oState The updated state
+	 * @returns {this} Returns <code>this</code> to allow method chaining
+	 */
+	StateHandlerRegistry.prototype.fireChange = function(oControl, oState) {
+		return EventProvider.prototype.fireEvent.call(this, "stateChange", {
+			control: oControl,
+			state: oState
+		});
+	};
+
+	/**
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * This method is the central point of access to the DefaultProviderRegistry Singleton.
+	 * @returns {this} Returns the <code>StateHandlerRegistry</code> instance.
+	 */
+	StateHandlerRegistry.getInstance = function () {
+		if (!oStateHandlerRegistry) {
+			oStateHandlerRegistry = new StateHandlerRegistry();
+		}
+		return oStateHandlerRegistry;
+	};
+
+	return StateHandlerRegistry;
+});

package/src/sap/m/p13n/modules/UIManager.js

@@ -0,0 +1,230 @@
+/*
+ * ! OpenUI5
+ * (c) Copyright 2009-2022 SAP SE or an SAP affiliate company.
+ * Licensed under the Apache License, Version 2.0 - see LICENSE.txt.
+ */
+
+sap.ui.define([
+	"sap/ui/base/Object",
+	"sap/ui/mdc/util/loadModules",
+	"sap/base/Log"
+], function (BaseObject, loadModules, Log) {
+	"use strict";
+
+	var ERROR_INSTANCING = "UIManager: This class is a singleton and should not be used without an AdaptationProvider. Please use 'sap.m.p13n.Engine.getInstance().uimanager' instead";
+
+	//Singleton storage
+	var oUIManager;
+
+	/**
+	 * Constructor for a new UIManager.
+	 * This manager creates and manages <code>sap.m.p13n.Popup</code> instances in order to personalize a certain control instance.
+	 * The <cod>UIManager</code> serves as additional implementation for the <code>sap.m.p13n.Engine</code> to visualize p13n UIs for end user personalization.
+	 *
+	 * <b>Note:</b>The UIManager resides in the Engine and must never be called separately.
+	 * The Engine currently is being used to provide controller capabilities, accessed by the UIManager, the according is {@link sap.m.p13n.AdaptationProvider}.
+	 *
+	 * @class
+	 * @extends sap.ui.base.Object
+	 *
+	 * @author SAP SE
+	 * @version 1.104.0
+	 *
+	 * @private
+	 *
+	 * @since 1.104
+	 * @alias sap.m.p13n.modules.UIManager
+	 */
+	var UIManager = BaseObject.extend("sap.m.p13n.UIManager", {
+		constructor: function(oAdaptationProvider) {
+
+			if (oUIManager) {
+				throw Error(ERROR_INSTANCING);
+			}
+
+			this.oAdaptationProvider = oAdaptationProvider;
+
+			BaseObject.call(this);
+		}
+	});
+
+	/**
+	 *
+	 * @param {sap.ui.core.Control} oControl The control instance to be personalized
+	 * @param {string|string[]} vPanelKeys The affected panels that should be added to the <code>sap.m.p13n.Popup</code>
+	 * @param {object} mSettings The settings object for the personalization
+	 * @param {string} [mSettings.title] The title for the <code>sap.m.p13n.Popup</code> control
+	 * @param {object} [mSettings.source] The source contro to be used by the <code>sap.m.p13n.Popup</code> control (only necessary in case the mode is set to <code>ResponsivePopover</code>)
+	 * @param {object} [mSettings.mode] The mode to be used by the <code>sap.m.p13n.Popup</code> control
+	 * @param {object} [mSettings.contentHeight] Height configuration for the related popup container
+	 * @param {object} [mSettings.contentWidth] Width configuration for the related popup container
+	 *
+	 * @returns {Promise} Promise resolving in the <code>sap.m.p13n.Popup</code> instance.
+	 */
+	UIManager.prototype.show = function(oControl, vPanelKeys, mSettings) {
+		var aPanelKeys = vPanelKeys instanceof Array ? vPanelKeys : [vPanelKeys];
+		var oResourceBundle = sap.ui.getCore().getLibraryResourceBundle("sap.m");
+		var that = this;
+		mSettings = Object.assign({}, mSettings);
+
+		if (!this.hasActiveP13n(oControl)){
+			this.setActiveP13n(oControl, vPanelKeys);
+
+			return this.create(oControl, vPanelKeys, mSettings)
+			.then(function(aInitializedPanels){
+				return loadModules(["sap/m/p13n/Popup"]).then(function(aModules){
+
+					//if there is no title provided and only one panel created, use it's title as the Popup title
+					var sTitle;
+					if (!mSettings.title && aPanelKeys.length === 1) {
+						sTitle = aInitializedPanels[0].getTitle();
+					} else {
+						sTitle = mSettings.title || oResourceBundle.getText("p13n.VIEW_SETTINGS");
+					}
+
+					//Enrich Popup with AdaptationProvider functionality --> add controller logic (reset and appliance)
+					var Popup = aModules[0];
+					var oP13nContainer = new Popup({
+						mode: mSettings.mode,
+						warningText: mSettings.warningText || oResourceBundle.getText("p13n.RESET_WARNING_TEXT"),
+						title: sTitle,
+						close: function(oEvt){
+							var sReason = oEvt.getParameter("reason");
+							if (sReason == "Ok") {
+								that.oAdaptationProvider.handleP13n(oControl, aPanelKeys);
+							}
+							oP13nContainer.removeAllPanels();//TODO
+							that.setActiveP13n(oControl, null);
+
+							oP13nContainer.destroy();
+						},
+						reset: function(){
+							that.oAdaptationProvider.reset(oControl, aPanelKeys);
+						}
+					});
+
+					aInitializedPanels.forEach(function(oPanel, iIndex){
+						oP13nContainer.addPanel(oPanel, aPanelKeys[iIndex]);
+					});
+
+					oControl.addDependent(oP13nContainer);
+					oP13nContainer.open(mSettings.source, mSettings);
+					return oP13nContainer._oPopup;
+
+				});
+			}, function(eContainerFailure){
+				this.setActiveP13n(oControl, null);
+				Log.error("UIManager failure:" + eContainerFailure.stack);
+			}.bind(this));
+		} else {
+			return Promise.resolve();
+		}
+	};
+
+	UIManager.prototype.create = function(oControl, vPanelKeys) {
+		var aPanelKeys = vPanelKeys instanceof Array ? vPanelKeys : [vPanelKeys];
+		var that = this;
+
+		return this.oAdaptationProvider.initAdaptation(oControl, aPanelKeys)
+		.then(function(){
+			var vSettings = this.oAdaptationProvider.getUISettings(oControl, aPanelKeys);
+
+			//if condition only temporarly necessary until sap.ui.comp adjusted
+			if (vSettings instanceof Promise) {
+				return vSettings;
+			} else {
+				var aPanelPromises = [], aPanelSettings = [];
+				Object.keys(vSettings).forEach(function(sSetting){
+					var vSetting = vSettings[sSetting];
+					if (vSetting && vSetting.hasOwnProperty("adaptationUI")) {
+						var pCreation = vSetting.adaptationUI;
+						aPanelPromises.push(pCreation);
+
+						aPanelSettings.push({
+							key: sSetting,
+							settings: vSetting
+						});
+					}
+				});
+				return Promise.all(aPanelPromises).then(function(aPanels){
+					var mMappedSetting = {};
+					aPanels.forEach(function(oPanel, iIndex){
+						if (oPanel) {
+							var oPanelSetting = aPanelSettings[iIndex];
+							var mContainerSettings = oPanelSetting.settings.containerSettings;
+							if (mContainerSettings.title) {
+								oPanel.setTitle(mContainerSettings.title);
+							}
+							mMappedSetting[oPanelSetting.key] = {
+								panel: oPanel
+							};
+						}
+					});
+					return mMappedSetting;
+				});
+			}
+		}.bind(this))
+
+		.then(function(mSettings){
+			var aInitializedPanels = [];
+
+			//Attach state validation during personalization
+			Object.keys(mSettings).forEach(function(sPanel, iIndex){
+				var oPanel = mSettings[sPanel].panel;
+
+				//not every panel used is a p13n.BasePanel (comp.FilterPanel, AdaptationFilterBar) these panels might not provide a change event
+				if (oPanel.attachChange instanceof Function) {
+					oPanel.attachChange(function(oEvt){
+						that.oAdaptationProvider.validateP13n(oControl, aPanelKeys[iIndex], oEvt.getSource());
+					});
+				}
+				aInitializedPanels.push(oPanel);
+			});
+
+			return aInitializedPanels;
+		});
+	};
+
+	UIManager.getInstance = function(oAdaptationProvider) {
+		if (!oUIManager) {
+			this._checkValidInterface(oAdaptationProvider);
+			oUIManager = new UIManager(oAdaptationProvider);
+		}
+		return oUIManager;
+	};
+
+	UIManager.prototype.setActiveP13n = function(vControl, vKeys) {
+		if (this.oAdaptationProvider.setActiveP13n instanceof Function) {
+			this.oAdaptationProvider.setActiveP13n(vControl, vKeys);
+		}
+	};
+
+	UIManager.prototype.hasActiveP13n = function(vControl) {
+		var bActiveP13n = false;
+		if (this.oAdaptationProvider.hasActiveP13n instanceof Function) {
+			bActiveP13n = this.oAdaptationProvider.hasActiveP13n(vControl);
+		}
+		return bActiveP13n;
+	};
+
+	/**
+	 * Checks if the UIManager has been initialized with a valid AdaptationProvider interface.
+	 *
+	 * @private
+	 * @ui5-restricted sap.m
+	 *
+	 * @param {sap.m.AdaptationProvider} oAdaptationProvider Object implementing the <code>sap.m.AdaptationProvider</code> interface to provide personalization capabilites.
+	 */
+	UIManager._checkValidInterface = function(oAdaptationProvider) {
+		if (!oAdaptationProvider || !oAdaptationProvider.isA("sap.m.p13n.AdaptationProvider")){
+			throw Error("The UIManager singleton must not be accessed without an AdaptationProvider interface!");
+		}
+	};
+
+	UIManager.prototype.destroy = function() {
+		BaseObject.prototype.destroy.apply(this, arguments);
+		oUIManager = null;
+	};
+
+	return UIManager;
+});