@sapui5/sap.ushell 1.123.1 → 1.124.1

package/src/main/js/sap/ushell/services/FrameBoundExtension.js

@@ -0,0 +1,371 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+
+/**
+ * @fileOverview FrameBoundExtension.
+ * This files exposes an API to extend the launchpad with new elements.
+ * It is exposed publicly and meant to be used by apps and plugins.
+ *
+ * This service can only be called from the outer shell and is not available
+ * in the inner shell or via post message API.
+ *
+ * @version 1.124.1
+ */
+sap.ui.define([
+    "sap/ushell/services/FrameBoundExtension/FloatingContainer",
+    "sap/ushell/services/FrameBoundExtension/Footer",
+    "sap/ushell/services/FrameBoundExtension/Item",
+    "sap/ushell/services/FrameBoundExtension/SidePane",
+    "sap/ushell/services/FrameBoundExtension/ToolArea",
+    "sap/ushell/Container",
+    "sap/ushell/utils"
+], function (
+    FloatingContainerArea,
+    FooterItem,
+    ExtensionItem,
+    SidePaneArea,
+    ToolAreaArea,
+    Container,
+    ushellUtils
+) {
+    "use strict";
+
+    /**
+     * @alias sap.ushell.services.FrameBoundExtension
+     * @class
+     * @classdesc The Unified Shell's Extension service.
+     * Allows adding extensions on the user's home page.
+     *
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
+     * <code>sap.ushell.Container.getServiceAsync("FrameBoundExtension")</code>. For details, see
+     * {@link sap.ushell.Container#getServiceAsync}.
+     *
+     * <p><b>Restriction:</b> This Service does not work when called from within a iframe.
+     * The calling function has to be in the 'same frame' as the launchpad itself.</p>
+     *
+     * <br>
+     * All extension items and extension areas are instantiated as invisible.
+     * You have to call .show<...> to make them visible.
+     *
+     * @augments sap.ushell.services.Service
+     * @hideconstructor
+     *
+     * @since 1.124.0
+     * @public
+     */
+    function FrameBoundExtension () { }
+
+    // ========================================== Helper ====================================================================
+
+    /**
+     * Creates a function which scopes a specific control to a single visibility handler.
+     * The new function combines a show and hide function.
+     * @param {string} controlId The id of the control.
+     * @param {function} show The show function.
+     * @param {function} hide The hide function.
+     * @returns {function} The scoped visibility handler.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    FrameBoundExtension.prototype._createItemVisibilityHandler = function (controlId, show, hide) {
+        return async function visibilityHandler (visible, currentState, state) {
+            const states = state ? [state] : undefined;
+            if (visible) {
+                await ushellUtils.promisify(show(controlId, currentState, states));
+                return;
+            }
+            await ushellUtils.promisify(hide(controlId, currentState, states));
+        };
+    };
+
+    /**
+     * Utility function to await a function call.
+     * @param {function} create The create function.
+     * @param {Array<*>} createArgs The list of arguments.
+     * @returns {Promise<sap.ui.core.Control>} The created control.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    FrameBoundExtension.prototype._createControl = async function (create, createArgs) {
+        return ushellUtils.promisify(create(...createArgs));
+    };
+
+    // ========================================== Header - Items ====================================================================
+
+    /**
+     * Creates a header item in the shell header.
+     * @param {sap.ushell.ui.shell.ShellHeadItem.Properties} controlProperties The properties that will be passed to the created control.
+     * @param {object} [parameters] Additional parameters.
+     * @param {string} [parameters.position=end] Possible values are <code>begin</code> and <code>end</code>.
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.Item>} The newly created header item.
+     *
+     * @since 1.124.0
+     * @public
+     */
+    FrameBoundExtension.prototype.createHeaderItem = async function (controlProperties, parameters = {}) {
+        const { position } = parameters;
+        const aValidPositions = ["begin", "end", undefined];
+        if (!aValidPositions.includes(position)) {
+            throw new Error(`Unexpected Input: '${position}' is not a valid position!`);
+        }
+
+        if (position === "begin") {
+            return this._createHeaderStartItem(controlProperties);
+        }
+        // "end" or undefined
+        return this._createHeaderEndItem(controlProperties);
+    };
+
+    /**
+     * Creates a header item in the shell header next to the company logo.
+     * @param {object} controlProperties The properties that will be passed to the created control.
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.Item>} The newly created header item.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    FrameBoundExtension.prototype._createHeaderStartItem = async function (controlProperties) {
+        const oRenderer = Container.getRendererInternal();
+        const aCreateArgs = [
+            controlProperties,
+            false, // visible
+            undefined, // currentState
+            undefined // states
+        ];
+        const fnCreate = oRenderer.addHeaderItem.bind(oRenderer);
+        const fnShow = oRenderer.showHeaderItem.bind(oRenderer);
+        const fnHide = oRenderer.hideHeaderItem.bind(oRenderer);
+
+        const oControl = await this._createControl(fnCreate, aCreateArgs);
+        const fnVisibilityHandler = this._createItemVisibilityHandler(oControl.getId(), fnShow, fnHide);
+
+        return new ExtensionItem(oControl, fnVisibilityHandler);
+    };
+
+    /**
+     * Creates a header item in the shell header next to the user action menu.
+     * @param {object} controlProperties The properties that will be passed to the created control.
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.Item>} The newly created header item.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    FrameBoundExtension.prototype._createHeaderEndItem = async function (controlProperties) {
+        const oRenderer = Container.getRendererInternal();
+
+        const aCreateArgs = [
+            controlProperties,
+            false, // visible
+            undefined, // currentState
+            undefined // states
+        ];
+        const fnCreate = oRenderer.addHeaderEndItem.bind(oRenderer);
+        const fnShow = oRenderer.showHeaderEndItem.bind(oRenderer);
+        const fnHide = oRenderer.hideHeaderEndItem.bind(oRenderer);
+
+        const oControl = await this._createControl(fnCreate, aCreateArgs);
+        const fnVisibilityHandler = this._createItemVisibilityHandler(oControl.getId(), fnShow, fnHide);
+
+        return new ExtensionItem(oControl, fnVisibilityHandler);
+    };
+
+    // ========================================== SubHeader ====================================================================
+
+    /**
+     * Creates a new sub header which is positioned below the header.
+     *
+     * <p><b>Note:</b> Only one sub header is displayed at once</p>
+     * <p><b>Restriction:</b> NOT available for apps running in an iframe</p>
+     * @param {object} controlProperties The properties that will be passed to the created control.
+     * @param {object} [parameters] Additional parameters.
+     * @param {string} [parameters.controlType=sap.m.Bar] Defines the <code>controlType</code>.
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.Item>} The newly created sub header.
+     *
+     * @since 1.124.0
+     * @public
+     */
+    FrameBoundExtension.prototype.createSubHeader = async function (controlProperties, parameters = {}) {
+        const oRenderer = Container.getRendererInternal();
+
+        const aCreateArgs = [{
+            controlType: parameters.controlType || "sap.m.Bar",
+            oControlProperties: controlProperties,
+            bIsVisible: false,
+            bCurrentState: undefined,
+            aStates: undefined
+        }];
+        const fnCreate = oRenderer.addShellSubHeader.bind(oRenderer);
+        const fnShow = oRenderer.showSubHeader.bind(oRenderer);
+        const fnHide = oRenderer.hideSubHeader.bind(oRenderer);
+
+        const oControl = await this._createControl(fnCreate, aCreateArgs);
+        const fnVisibilityHandler = this._createItemVisibilityHandler(oControl.getId(), fnShow, fnHide);
+
+        // hide
+        // fnVisibilityHandler(false, true, []);
+
+        return new ExtensionItem(oControl, fnVisibilityHandler);
+    };
+
+    // ========================================== SidePane ====================================================================
+
+    /**
+     * Returns the API for the SidePane which is located next to the launchpad content.
+     * <p><b>Restriction:</b> NOT available for apps running in an iframe</p>
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.SidePane>} The SidePane.
+     *
+     * @since 1.124.0
+     * @public
+     */
+    FrameBoundExtension.prototype.getSidePane = async function () {
+        return new SidePaneArea();
+    };
+
+    // ========================================== ToolArea ====================================================================
+
+    /**
+     * Returns the API for the ToolArea which is located next to the launchpad content.
+     * <p><b>Restriction:</b> NOT available for apps running in an iframe</p>
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.ToolArea>} The ToolArea.
+     *
+     * @since 1.124.0
+     * @public
+     */
+    FrameBoundExtension.prototype.getToolArea = async function () {
+        return new ToolAreaArea();
+    };
+
+    // ========================================== UserAction ====================================================================
+
+    /**
+     * Creates a user action in the user action menu.
+     * @param {object} controlProperties The properties that will be passed to the created control.
+     * @param {object} [parameters] Additional parameters.
+     * @param {string} [parameters.controlType=sap.ushell.ui.launchpad.ActionItem] Defines the <code>controlType</code>.
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.Item>} The newly created user action.
+     *
+     * @since 1.124.0
+     * @public
+     */
+    FrameBoundExtension.prototype.createUserAction = async function (controlProperties, parameters = {}) {
+        const oRenderer = Container.getRendererInternal();
+
+        const aCreateArgs = [{
+            controlType: parameters.controlType || "sap.m.Button",
+            oControlProperties: controlProperties,
+            bIsVisible: false,
+            bCurrentState: undefined,
+            aStates: undefined
+        }];
+        const fnCreate = oRenderer.addUserAction.bind(oRenderer);
+        const fnShow = oRenderer.showActionButton.bind(oRenderer);
+        const fnHide = oRenderer.hideActionButton.bind(oRenderer);
+
+        const oControl = await this._createControl(fnCreate, aCreateArgs);
+        const fnVisibilityHandler = this._createItemVisibilityHandler(oControl.getId(), fnShow, fnHide);
+
+        return new ExtensionItem(oControl, fnVisibilityHandler);
+    };
+
+    // ========================================== Footer ====================================================================
+
+    /**
+     * Creates a new footer which is positioned below the launchpad content.
+     *
+     * <p><b>Note:</b> Only one footer is displayed at once. Any new footer will replace the previous one</p>
+     * <p><b>Restriction:</b> NOT available for apps running in an iframe</p>
+     * @param {object} controlProperties The properties that will be passed to the created control.
+     * @param {object} [parameters] Additional parameters.
+     * @param {string} [parameters.controlType=sap.m.Bar] Defines the <code>controlType</code>.
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.Footer>} The newly created footer.
+     *
+     * @since 1.124.0
+     * @public
+     */
+    FrameBoundExtension.prototype.createFooter = async function (controlProperties, parameters = {}) {
+        const oRenderer = Container.getRendererInternal();
+
+        const aCreateArgs = [{
+            controlType: parameters.controlType || "sap.m.Bar",
+            oControlProperties: controlProperties
+        }];
+        const fnCreate = oRenderer.setShellFooter.bind(oRenderer);
+
+        const oControl = await this._createControl(fnCreate, aCreateArgs);
+
+        return new FooterItem(oControl);
+    };
+
+    // ========================================== UserSettings ====================================================================
+
+    /**
+     * Adds an entry to the user settings dialog box including the UI control that appears when the user clicks the new entry,
+     * and handling of user settings actions such as SAVE and CANCEL.
+     * <p><b>Restriction:</b> NOT available for apps running in an iframe</p>
+     * @param {object} properties The data of the new added user settings entry.
+     * @param {string} [properties.entryHelpID] The ID of the object.
+     * @param {string} properties.title The title of the entry to be presented in the list in the user settings dialog box. We recommend using a string from the translation bundle.
+     * @param {string|function(): Promise<string>} properties.value A string to be presented as the sub title of the entry OR a function which resolves the sub title.
+     * @param {function(): Promise<sap.ui.core.Control>} properties.content A function that resolves the content which has to be a {@link sap.ui.core.Control}.
+     *      A SAPUI5 view instance can also be returned. The result will be displayed in the settings as content for this entry.
+     * @param {function(): Promise} properties.onSave A callback which is called when the user clicks "save" in the user settings dialog. The function has to return a native promise.
+     *      If an error occurs, pass the error message via rejected promise. Errors are displayed in the common log.
+     * @param {function} properties.onCancel A callback which is called when the user closes the user settings dialog without saving any changes.
+     * @param {boolean} [properties.provideEmptyWrapper=false] Set this value to <code>true</code> if you want that your content is displayed without the standard header.
+     * @returns {Promise} Resolves once the settings entry was added.
+     *
+     * @since 1.124.0
+     * @public
+     */
+    FrameBoundExtension.prototype.addUserSettingsEntry = async function (properties) {
+        const oRenderer = Container.getRendererInternal();
+        await ushellUtils.promisify(oRenderer.addUserPreferencesEntry(properties));
+    };
+
+    /**
+     * Adds an entry to the user settings dialog box including the UI control that appears when the user clicks the new entry,
+     * and handling of user settings actions such as SAVE and CANCEL.
+     * <p><b>Restriction:</b> NOT available for apps running in an iframe</p>
+     * @param {object} properties The data of the new added user settings entry.
+     * @param {string} [properties.entryHelpID] The ID of the object.
+     * @param {string} properties.title The title of the entry to be presented in the list in the user settings dialog box. We recommend using a string from the translation bundle.
+     * @param {string|function(): Promise<string>} properties.value A string to be presented as the sub title of the entry OR a function which resolves the sub title.
+     * @param {function(): Promise<sap.ui.core.Control>} properties.content A function that resolves the content which has to be a {@link sap.ui.core.Control}.
+     *      A SAPUI5 view instance can also be returned. The result will be displayed in the settings as content for this entry.
+     * @param {function} properties.onSave A callback which is called when the user clicks "save" in the user settings dialog. The function has to return a native promise.
+     *      If an error occurs, pass the error message via rejected promise. Errors are displayed in the common log.
+     * @param {function(): Promise} properties.onCancel A callback which is called when the user closes the user settings dialog without saving any changes.
+     * @param {boolean} [properties.provideEmptyWrapper=false] Set this value to <code>true</code> if you want that your content is displayed without the standard header.
+     * @param {string} [properties.groupingId] The ID of the group this entry should be included in.
+     * @param {string} [properties.groupingTabTitle] The tab title of the entry, when this entry is grouped.
+     * @param {string} [properties.groupingTabHelpId] The help ID for the grouped tab, when this entry is grouped.
+     * @returns {Promise} Resolves once the settings entry was added.
+     *
+     * @since 1.124.0
+     * @private
+     * @ui5-restricted sap.fe, sap.esh.search.ui
+     */
+    FrameBoundExtension.prototype.addGroupedUserSettingsEntry = async function (properties) {
+        const oRenderer = Container.getRendererInternal();
+        await ushellUtils.promisify(oRenderer.addUserPreferencesGroupedEntry(properties));
+    };
+
+    // ========================================== FloatingContainer ====================================================================
+
+    /**
+     * Returns the API for the FloatingContainer.
+     * <p><b>Restriction:</b> NOT available for apps running in an iframe</p>
+     * @returns {Promise<sap.ushell.services.FrameBoundExtension.FloatingContainer>} The FloatingContainer.
+     *
+     * @since 1.124.0
+     * @private
+     * @ui5-restricted
+     */
+    FrameBoundExtension.prototype.getFloatingContainer = async function () {
+        return new FloatingContainerArea();
+    };
+
+    FrameBoundExtension.hasNoAdapter = true;
+    return FrameBoundExtension;
+});

package/src/main/js/sap/ushell/services/LaunchPage.js

@@ -2,7 +2,7 @@
 
 /**
  * @fileoverview The Unified Shell's page builder service providing the data for the Fiori launchpad's classic Homepage.
- * @version 1.123.1
+ * @version 1.124.1
  * @deprecated since 1.120
  */
 sap.ui.define([
@@ -17,9 +17,13 @@ sap.ui.define([
      * @class
      * @classdesc A service for handling groups, tiles and catalogs.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("Extension")</code>. For details, see
-     * {@link sap.ushell.Container#getServiceAsync}.
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call {@link sap.ushell.Container#getServiceAsync}.
+     * <pre>
+     *   sap.ui.require(["sap/ushell/Container"], async function (Container) {
+     *     const LaunchPage = await Container.getServiceAsync("LaunchPage");
+     *     // do something with the LaunchPage service
+     *   });
+     * </pre>
      *
      * The functions that return the main objects are getGroups, getGroupTitle, getCatalogs and getCatalogTiles.
      * Since the implementation (i.e. adapter) is platform specific, do not call or access properties and functions of returned objects.

package/src/main/js/sap/ushell/services/Menu.js

@@ -2,7 +2,7 @@
 
 /**
  * @fileOverview The menu service provides the entries for the menu bar
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/ushell/Config",
@@ -31,9 +31,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's Menu service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("Menu")</code>. For details, see
-     * {@link sap.ushell.Container#getServiceAsync}.
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call {@link sap.ushell.Container#getServiceAsync}.
+     * <pre>
+     *   sap.ui.require(["sap/ushell/Container"], async function (Container) {
+     *     const Menu = await Container.getServiceAsync("Menu");
+     *     // do something with the Menu service
+     *   });
+     * </pre>
      *
      * @hideconstructor
      *
@@ -605,8 +609,8 @@ sap.ui.define([
                 // The data is read from the metatags which dos not use any cachebuster tokens.
                 var oScope = {
                     validity: "Infinity",
-                    keyCategory: oPersonalizationService.constants.keyCategory.FIXED_KEY,
-                    writeFrequency: oPersonalizationService.constants.writeFrequency.HIGH,
+                    keyCategory: oPersonalizationService.KeyCategory.FIXED_KEY,
+                    writeFrequency: oPersonalizationService.WriteFrequency.HIGH,
                     clientStorageAllowed: false
                 };
                 const oPersonalizer = await oPersonalizationService.getPersonalizer(oPersId, oScope);

package/src/main/js/sap/ushell/services/Message.js

@@ -2,7 +2,7 @@
 
 /**
  * @fileOverview The Unified Shell's message service.
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/base/Log",
@@ -50,9 +50,13 @@ sap.ui.define([
      * @class
      * @classdesc Message service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("Message")</code>. For details, see
-     * {@link sap.ushell.Container#getServiceAsync}.
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call {@link sap.ushell.Container#getServiceAsync}.
+     * <pre>
+     *   sap.ui.require(["sap/ushell/Container"], async function (Container) {
+     *     const Message = await Container.getServiceAsync("Message");
+     *     // do something with the Message service
+     *   });
+     * </pre>
      *
      * @augments sap.ushell.services.Service
      * @hideconstructor

package/src/main/js/sap/ushell/services/MessageBroker.js

@@ -2,7 +2,7 @@
 
 /**
  * @fileOverview This module exposes API endpoints for Generic Communication
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/ushell/services/_MessageBroker/MessageBrokerEngine",
@@ -17,9 +17,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's MessageBroker service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("MessageBroker")</code>. For details, see
-     * {@link sap.ushell.Container#getServiceAsync}.
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call {@link sap.ushell.Container#getServiceAsync}.
+     * <pre>
+     *   sap.ui.require(["sap/ushell/Container"], async function (Container) {
+     *     const MessageBroker = await Container.getServiceAsync("MessageBroker");
+     *     // do something with the MessageBroker service
+     *   });
+     * </pre>
      *
      * @hideconstructor
      *

package/src/main/js/sap/ushell/services/NavTargetResolution.js

@@ -4,31 +4,15 @@
  * @fileOverview The NavTargetResolution service.
  */
 sap.ui.define([
-    "sap/ushell/services/AppConfiguration",
-    "sap/ushell/utils",
-    "sap/ushell/utils/UrlParsing",
-    "sap/ushell/utils/UrlShortening",
-    "sap/ushell/utils/HttpClient",
-    "sap/ushell/navigationMode",
     "sap/ui/thirdparty/jquery",
-    "sap/ui/performance/Measurement",
-    "sap/base/util/deepExtend",
-    "sap/base/util/isPlainObject",
     "sap/base/Log",
-    "sap/ushell/Container"
+    "sap/ushell/Container",
+    "sap/ushell/services/NavTargetResolutionInternal"
 ], function (
-    appConfiguration,
-    utils,
-    UrlParsing,
-    UrlShortening,
-    HttpClient,
-    NavigationMode,
     jQuery,
-    Measurement,
-    deepExtend,
-    isPlainObject,
     Log,
     Container
+    /* NavTargetResolutionInternal - here to async preload the module */
 ) {
     "use strict";
 
@@ -37,9 +21,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's internal navigation target resolution service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("NavTargetResolution")</code>. For details, see
-     * {@link sap.ushell.Container#getServiceAsync}.
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call {@link sap.ushell.Container#getServiceAsync}.
+     * <pre>
+     *   sap.ui.require(["sap/ushell/Container"], async function (Container) {
+     *     const NavTargetResolution = await Container.getServiceAsync("NavTargetResolution");
+     *     // do something with the NavTargetResolution service
+     *   });
+     * </pre>
      *
      * Methods in this class deal with *internal* representations of the shell hash.
      *

package/src/main/js/sap/ushell/services/NavTargetResolutionInternal.js

@@ -37,9 +37,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's internal navigation target resolution service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("NavTargetResolutionInternal")</code>. For details, see
-     * {@link sap.ushell.Container#getServiceAsync}.
+     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call {@link sap.ushell.Container#getServiceAsync}.
+     * <pre>
+     *   sap.ui.require(["sap/ushell/Container"], async function (Container) {
+     *     const NavTargetResolutionInternal = await Container.getServiceAsync("NavTargetResolutionInternal");
+     *     // do something with the NavTargetResolutionInternal service
+     *   });
+     * </pre>
      *
      * Methods in this class deal with *internal* representations of the shell hash.
      *