@sapui5/sap.ushell 1.123.1 → 1.124.1

package/src/main/js/sap/ushell/services/Navigation/compatibility.js

@@ -0,0 +1,229 @@
+// Copyright (c) 2009-2023 SAP SE, All Rights Reserved
+/**
+ * @fileOverview This module helps to transform the parameters and responses to be
+ * compatible with the CrossApplicationNavigation service.
+ * This shall only be used for the AppRuntime to enable 1.x inner shell running in 2.x host.
+ *
+ * @version 1.124.1
+ */
+
+sap.ui.define([
+    "sap/base/util/isPlainObject",
+    "sap/ushell/Container",
+    "sap/ushell/services/Navigation/utils",
+    "sap/ushell/TechnicalParameters",
+    "sap/ushell/utils",
+    "sap/ushell/utils/type"
+], function (
+    isPlainObject,
+    Container,
+    navigationUtils,
+    TechnicalParameters,
+    ushellUtils,
+    typeUtils
+) {
+    "use strict";
+
+    const compatibility = {};
+
+    /**
+     * Original Method: {@link sap.ushell.services.CrossApplicationNavigation#getLinks}
+     *  - public
+     *  - since 1.38
+     *  - deprecated since 1.120
+     *  - successor: {@link sap.ushell.services.Navigation#getLinks}
+     *  - return value was a {@link jQuery.Promise}.
+     *
+     * @param {object|Array<Array<object>>} [vArgs] Either a single object or an array of arrays containing the parameters for the getLinks method.
+     *
+     * @returns {Promise<Array<object>|Array<Array<Array<object>>>} The links for the provided parameters.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    compatibility.getLinks = async function (vArgs = {}) {
+        const Navigation = await Container.getServiceAsync("Navigation");
+
+        // single object case
+        // {arg1} => [{link1-1}, {link1-2}, ...]
+        if (isPlainObject(vArgs)) {
+            const [aLinks] = await Navigation.getLinks([vArgs]);
+            return aLinks;
+        }
+
+        // array case
+        // [[{arg1}], [{arg2}], ...] => [[[{link1-1}, {link1-2}, ...]], [[{link2-1}, {link2-2}, ...]], ...]
+        // first we transform the args to the flat format
+        const aFlatArgs = vArgs.reduce((aFlatArgs, [oArg]) => {
+            aFlatArgs.push(oArg);
+            return aFlatArgs;
+        }, []);
+
+        const aResults = await Navigation.getLinks(aFlatArgs);
+
+        // now we have to transform the results to the extended format
+        const aExpandedResults = aResults.reduce((aExpandedResults, aLinks) => {
+            aExpandedResults.push([aLinks]);
+            return aExpandedResults;
+        }, []);
+
+        return aExpandedResults;
+    };
+
+    /**
+     * Original Method: {@link sap.ushell.services.CrossApplicationNavigation#getAppStateData}
+     *  - ui5-restricted: SAP Internal usage / WebDynpro
+     *  - since 1.32
+     *  - deprecated since 1.120
+     *  - successor: {@link sap.ushell.services.Navigation#getAppStateData}
+     *  - return value was a {@link jQuery.Promise}.
+     *
+     * @param {string|Array<Array<any>>} vAppStateKey Either a single app state key or an array of arrays containing the parameters for the getAppStateData method.
+     *
+     * @returns {Promise<object|Array<Array<object>>>} The app state data for the provided keys.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    compatibility.getAppStateData = async function (vAppStateKey) {
+        const Navigation = await Container.getServiceAsync("Navigation");
+
+        // single object case
+        // key1 => {data1}
+        if (typeof vAppStateKey === "string") {
+            const [oAppStateData] = await Navigation.getAppStateData([vAppStateKey]);
+            return oAppStateData;
+        }
+
+        // array case
+        // [[key1], [key2], ...] => [[{data1}], [{data2}], ...]
+        // first we transform the args to the flat format
+        const aFlatArgs = vAppStateKey.reduce((aFlatArgs, [sKey]) => {
+            aFlatArgs.push(sKey);
+            return aFlatArgs;
+        }, []);
+
+        const aResults = await Navigation.getAppStateData(aFlatArgs);
+
+        // now we have to transform the the extended format
+        const aExpandedResults = aResults.reduce((aExpandedResults, oAppStateData) => {
+            aExpandedResults.push([oAppStateData]);
+            return aExpandedResults;
+        }, []);
+
+        return aExpandedResults;
+    };
+
+    /**
+     * Original Method: {@link sap.ushell.services.CrossApplicationNavigation#getSemanticObjectLinks}
+     *  - public
+     *  - since 1.19.0
+     *  - deprecated since 1.38
+     *  - successor: {@link sap.ushell.services.CrossApplicationNavigation#getLinks}
+     *  - return value was a {@link jQuery.Promise}.
+     *
+     * @param {string|Array<Array<any>>} vSemanticObjectOrMultipleArgs Either a single semantic object or an array of arrays containing the parameters for the getLinks method.
+     * @param {object} [oParameters] The Map of parameters.
+     * @param {boolean} [bIgnoreFormFactor=false] Whether the form factor should be ignored.
+     * @param {sap.ui.core.Component} [oComponent] The root component of the application.
+     * @param {string} [sAppStateKey] The application state key.
+     * @param {boolean} [bCompactIntents] Whether the returned intents should be compacted.
+     *
+     * @returns {Promise<Array<object>|Array<Array<Array<string>>>>} The links for the provided semantic objects.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    compatibility.getSemanticObjectLinks = async function (vSemanticObjectOrMultipleArgs, oParameters, bIgnoreFormFactor, oComponent, sAppStateKey, bCompactIntents) {
+        const Navigation = await Container.getServiceAsync("Navigation");
+        // require lazy to avoid circular dependency
+        const [ AppLifeCycleAI ] = await ushellUtils.requireAsync(["sap/ushell/components/applicationIntegration/AppLifeCycle"]);
+
+        let oParametersPlusSapSystem = await navigationUtils.injectStickyParameters({
+            args: { params: oParameters },
+            appLifeCycle: AppLifeCycleAI,
+            technicalParameters: TechnicalParameters,
+            type: typeUtils
+        });
+        oParametersPlusSapSystem = Navigation.getTargetWithCurrentSystem(oParametersPlusSapSystem, oComponent).params;
+        oParametersPlusSapSystem = Navigation.amendTargetWithSapUshellEncTestParameter({ params: oParametersPlusSapSystem }).params;
+
+        const NavTargetResolutionInternal = await Container.getServiceAsync("NavTargetResolutionInternal");
+
+        // single string case
+        // rest of the parameters are provided directly
+        // arg1, arg2, ... => [link1, link2, ...]
+        if (!Array.isArray(vSemanticObjectOrMultipleArgs)) {
+            const oDeferred = NavTargetResolutionInternal.getLinks({
+                semanticObject: vSemanticObjectOrMultipleArgs,
+                params: oParametersPlusSapSystem,
+                ignoreFormFactor: bIgnoreFormFactor,
+                ui5Component: oComponent,
+                appStateKey: sAppStateKey,
+                compactIntents: !!bCompactIntents
+            });
+            return ushellUtils.promisify(oDeferred);
+        }
+
+        // array case
+        // [[arg1-1, arg1-2, ...], [arg2-1, arg2-2, ...]] => [[[link1-1, link1-2, ...]], [[link2-1, link2-2, ...]]]
+        return Promise.all(vSemanticObjectOrMultipleArgs.map(async (aArgs) => {
+            const [ semanticObject, params, ignoreFormFactor, ui5Component, appStateKey, compactIntents ] = aArgs;
+            const oDeferred = NavTargetResolutionInternal.getLinks({
+                ignoreFormFactor: !!ignoreFormFactor,
+                compactIntents: !!compactIntents,
+                semanticObject,
+                params,
+                ui5Component,
+                appStateKey
+            });
+            const aLinks = await ushellUtils.promisify(oDeferred);
+            return [aLinks];
+
+        }));
+    };
+
+    /**
+     * Original Method: {@link sap.ushell.services.CrossApplicationNavigation#isIntentSupported}
+     *  - public
+     *  - since 1.19.1
+     *  - deprecated since 1.31
+     *  - successor: {@link sap.ushell.services.CrossApplicationNavigation#isNavigationSupported}
+     *  - return value was a {@link jQuery.Promise}.
+     *
+     * @param {string[]} aIntents The intents to check.
+     * @param {sap.ui.core.Component} [oComponent] The root component of the application.
+     *
+     * @returns {Promise<Object<string, { supported: boolean }>>} A map of intents to their supported status.
+     *
+     * @since 1.124.0
+     * @private
+     */
+    compatibility.isIntentSupported = async function (aIntents, oComponent) {
+        const Navigation = await Container.getServiceAsync("Navigation");
+
+        // Add sap-system to intents
+        const oIntentMap = {};
+        const aIntentsWithSapSystem = aIntents.map((sOriginalIntent) => {
+            const sIntentWithSystem = Navigation.getTargetWithCurrentSystem(sOriginalIntent, oComponent);
+            oIntentMap[sIntentWithSystem] = sOriginalIntent;
+            return sIntentWithSystem;
+        });
+
+        const NavTargetResolutionInternal = await Container.getServiceAsync("NavTargetResolutionInternal");
+
+        const oDeferred = NavTargetResolutionInternal.isNavigationSupported(aIntentsWithSapSystem);
+        const aResults = await ushellUtils.promisify(oDeferred);
+
+        // Map result back to original intents
+        return aResults.reduce((oResult, oIntentSupported, iIndex) => {
+            const sIntentWithSystem = aIntentsWithSapSystem[iIndex];
+            const sOriginalIntent = oIntentMap[sIntentWithSystem];
+            oResult[sOriginalIntent] = oIntentSupported;
+            return oResult;
+        }, {});
+    };
+
+
+    return compatibility;
+});

package/src/main/js/sap/ushell/services/Navigation/utils.js

@@ -2,7 +2,7 @@
 /**
  * @fileOverview Navigation utility functions
  *
- * @version 1.123.1
+ * @version 1.124.1
  */
 
 

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

@@ -5,7 +5,7 @@
  * This file exposes an API to perform (invoke) Navigation for applications.
  * It exposes interfaces to perform a hash change and trigger a navigation.
  *
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/base/Log",
@@ -41,7 +41,7 @@ sap.ui.define([
     TechnicalParameters,
     UI5ComponentType,
     ushellUtils,
-    ushellType,
+    typeUtils,
     UrlParsing
 ) {
     "use strict";
@@ -53,9 +53,13 @@ sap.ui.define([
      * Allows navigating to "external" targets outside of the currently running app (but still in scope of the current Fiori launchpad)
      * or to create links to such external targets.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("Navigation")</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 Navigation = await Container.getServiceAsync("Navigation");
+     *     // do something with the Navigation service
+     *   });
+     * </pre>
      *
      * The Navigation service currently provides platform independent functionality.
      *
@@ -63,19 +67,16 @@ sap.ui.define([
      *
      * Usage:
      * <pre>
-     *   sap.ui.require(["sap/ushell/Container"], async (Container) => {
-     *     const oNavigationService = await Container.getServiceAsync("Navigation");
-     *     const sHref = await oNavigationService.getHref({
-     *       target : {
-     *         semanticObject: "Product",
-     *         action: "display"
-     *       },
-     *       params: {
-     *         "ProductID": "102343333"
-     *       }
-     *     }, oComponent);
-     *     // do something with the resolved sHref.
-     *   });
+     *   const sHref = await Navigation.getHref({
+     *     target : {
+     *       semanticObject: "Product",
+     *       action: "display"
+     *     },
+     *     params: {
+     *       "ProductID": "102343333"
+     *     }
+     *   }, oComponent);
+     *   // do something with the resolved sHref.
      * </pre>
      *
      * Parameter names and values are case sensitive.
@@ -117,6 +118,7 @@ sap.ui.define([
         }
 
         /**
+         * @typedef {string} sap.ushell.services.Navigation.TargetIntent
          *
          *  The target intent.
          *
@@ -148,11 +150,20 @@ sap.ui.define([
          * <li>innerAppRouteParameters: The inner app route parameters are optional parameters that are passed to the target application. The parameters are separated by the ampersand character (&).
          * The parameter name and value are separated by the equal sign (=). The parameter value must be URL-encoded.
          * </li>
-         * @typedef {string} sap.ushell.services.Navigation.TargetIntent
+
          * @since 1.121.0
          * @public
          */
 
+        /**
+         * @typedef {string} sap.ushell.services.Navigation.TargetIntentStrict
+         * The target intent in strict format.
+         * same as {@link sap.ushell.services.Navigation.TargetIntent} but with the following restriction:
+         * The intent must not start with a hash character (#).
+         * @since 1.124.0
+         * @public
+         */
+
         /**
          * @typedef {object} sap.ushell.services.Navigation.LinkFilter
          * @property {string} [semanticObject] Matches the semantic object of a link.
@@ -283,7 +294,7 @@ sap.ui.define([
          * @since 1.120.0
          * @private
          */
-        this._getTargetWithCurrentSystem = function (vTarget, oComponent) {
+        this.getTargetWithCurrentSystem = function (vTarget, oComponent) {
             if (typeof vTarget !== "string" && !isPlainObject(vTarget) && vTarget !== undefined) {
                 Log.error("Unexpected input type", null, "sap.ushell.services.Navigation");
                 return undefined;
@@ -336,7 +347,7 @@ sap.ui.define([
             }
 
             const vInjectedTarget = navigationUtils.injectParameters({
-                type: ushellType,
+                type: typeUtils,
                 inject: {
                     "sap-system": sSystem,
                     "sap-ushell-navmode": sNextNavMode,
@@ -362,7 +373,7 @@ sap.ui.define([
          * @since 1.120.0
          * @private
          */
-        this._amendTargetWithSapUshellEncTestParameter = function (vTarget) {
+        this.amendTargetWithSapUshellEncTestParameter = function (vTarget) {
             if (localStorage && localStorage["sap-ushell-enc-test"] === "false") {
                 return vTarget;
             }
@@ -387,7 +398,7 @@ sap.ui.define([
                     if (typeof oClonedTarget.target.shellHash === "string") {
                         // process shell hash as a string
                         if (oClonedTarget.target.shellHash !== "#" && oClonedTarget.target.shellHash !== "") {
-                            oClonedTarget.target.shellHash = this._amendTargetWithSapUshellEncTestParameter(
+                            oClonedTarget.target.shellHash = this.amendTargetWithSapUshellEncTestParameter(
                                 oClonedTarget.target.shellHash);
                         }
                     }
@@ -511,13 +522,10 @@ sap.ui.define([
          * The resulting href is fully encoded and cannot be used in other APIs expecting the internal decoded hash.
          *
          * <pre>
-         *   sap.ui.require(["sap/ushell/Container"], async (Container) => {
-         *     const oNavigationService = await Container.getServiceAsync("Navigation");
-         *     const sHref = await oNavigationService.getHref({
-         *       target: { shellHash: oLink.intent }
-         *     }, oComponent);
-         *     // do something with the resolved sHref.
-         *   });
+         *   const sHref = await Navigation.getHref({
+         *     target: { shellHash: oLink.intent }
+         *   }, oComponent);
+         *   // do something with the resolved sHref.
          * </pre>
          *
          * This API accepts a sap-xapp-state-data parameter that can be used generate a url that can be used to launch
@@ -565,14 +573,14 @@ sap.ui.define([
 
                 await navigationUtils.addXAppStateFromParameter(intent, "sap-xapp-state-data" /* parameter containing data */);
 
-                oArgsClone = this._getTargetWithCurrentSystem(intent, oComponent);
+                oArgsClone = this.getTargetWithCurrentSystem(intent, oComponent);
                 oArgsClone = await navigationUtils.injectStickyParameters({
                     args: oArgsClone,
                     appLifeCycle: AppLifeCycleAi,
                     technicalParameters: TechnicalParameters,
-                    type: ushellType
+                    type: typeUtils
                 });
-                oArgsClone = this._amendTargetWithSapUshellEncTestParameter(oArgsClone);
+                oArgsClone = this.amendTargetWithSapUshellEncTestParameter(oArgsClone);
                 oArgsClone = this._injectInnerAppRoute(oArgsClone, innerAppRoute);
 
                 const ShellNavigationInternal = await Container.getServiceAsync("ShellNavigationInternal");
@@ -711,14 +719,14 @@ sap.ui.define([
                 this._checkIfAppNeedsToBeReloaded(oNavTarget, oCurrentApplication, oIntent, ShellNavigationInternal.hashChanger);
                 await navigationUtils.addXAppStateFromParameter(intent, "sap-xapp-state-data" /* parameter containing data */);
 
-                oArgsClone = this._getTargetWithCurrentSystem(intent, oComponent);
+                oArgsClone = this.getTargetWithCurrentSystem(intent, oComponent);
                 oArgsClone = await navigationUtils.injectStickyParameters({
                     args: oArgsClone,
                     appLifeCycle: AppLifeCycleAi,
                     technicalParameters: TechnicalParameters,
-                    type: ushellType
+                    type: typeUtils
                 });
-                oArgsClone = this._amendTargetWithSapUshellEncTestParameter(oArgsClone);
+                oArgsClone = this.amendTargetWithSapUshellEncTestParameter(oArgsClone);
 
                 delete oArgsClone.writeHistory;
 
@@ -903,7 +911,7 @@ sap.ui.define([
                     args: oArgsClone,
                     appLifeCycle: AppLifeCycleAi,
                     technicalParameters: TechnicalParameters,
-                    type: ushellType
+                    type: typeUtils
                 });
 
                 let oParameterDefinition;
@@ -914,11 +922,11 @@ sap.ui.define([
                 }
 
                 // propagate sap-system into parameters
-                let oParametersPlusSapSystem = this._getTargetWithCurrentSystem(
+                let oParametersPlusSapSystem = this.getTargetWithCurrentSystem(
                     { params: oParameterDefinition }, oArgsClone.ui5Component
                 ).params;
 
-                oParametersPlusSapSystem = this._amendTargetWithSapUshellEncTestParameter({
+                oParametersPlusSapSystem = this.amendTargetWithSapUshellEncTestParameter({
                     params: oParametersPlusSapSystem
                 }).params;
                 if (oArgsClone.appStateKey) {
@@ -984,7 +992,7 @@ sap.ui.define([
             const aClonedIntents = deepClone(aTargets)
                 .map((oIntent) => {
                     const { intent } = this._extractInnerAppRoute(oIntent);
-                    return this._getTargetWithCurrentSystem(intent, oComponent); // returns only shallow clone
+                    return this.getTargetWithCurrentSystem(intent, oComponent); // returns only shallow clone
                 });
 
             const NavTargetResolutionInternal = await Container.getServiceAsync("NavTargetResolutionInternal");

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

@@ -8,7 +8,7 @@
  *
  * Configured with the ClientSideTargetResolutionAdapter.
  *
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/ushell/resources"
@@ -20,9 +20,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's NavigationDataProvider service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("NavigationDataProvider")</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 NavigationDataProvider = await Container.getServiceAsync("NavigationDataProvider");
+     *     // do something with the NavigationDataProvider service
+     *   });
+     * </pre>
      *
      * @hideconstructor
      *

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

@@ -17,9 +17,13 @@ sap.ui.define([
      * @classdesc UShell service for fetching user notification data from the Notification center/service<br>
      * and exposing them to the Unified Shell and Fiori applications UI controls.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("ClientSideTargetResolution")</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 Notifications = await Container.getServiceAsync("Notifications");
+     *     // do something with the Notifications service
+     *   });
+     * </pre>
      *
      * In order to get user notifications, Unified Shell notification service issues OData requests<br>
      * to the service defined by the configuration property <code>serviceUrl</code>,<br>

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

@@ -32,9 +32,13 @@ sap.ui.define([
      * @classdesc UShell service for fetching user notification data from the Notification center/service<br>
      * and exposing them to the Unified Shell and Fiori applications UI controls.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("NotificationsV2")</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 NotificationsV2 = await Container.getServiceAsync("NotificationsV2");
+     *     // do something with the NotificationsV2 service
+     *   });
+     * </pre>
      *
      * In order to get user notifications, Unified Shell notification service issues OData requests<br>
      * to the service defined by the configuration property <code>serviceUrl</code>,<br>
@@ -76,12 +80,14 @@ sap.ui.define([
          */
 
         /**
-         * Enumeration for the priority of a notification
+         * @alias sap.ushell.services.NotificationsV2.Priority
          * @enum {string}
+         * Enumeration for the priority of a notification
+         *
          * @since 1.120.0
          * @public
          */
-        Notifications.Priority = {
+        this.Priority = {
             /**
              * Low priority.
              * @public
@@ -99,12 +105,15 @@ sap.ui.define([
             HIGH: "HIGH"
         };
 
-        /** Enumaration for The nature of the notification
+        /**
+         * @alias sap.ushell.services.NotificationsV2.Nature
          * @enum {string}
+         * Enumeration for The nature of the notification
+         *
          * @since 1.120.0
          * @public
          */
-        Notifications.Nature = {
+        this.Nature = {
             /**
              * The Positive nature.
              * @public
@@ -1963,8 +1972,8 @@ sap.ui.define([
                 this.oUserSettingsPersonalizerPromise = sap.ushell.Container.getServiceAsync("PersonalizationV2")
                     .then((PersonalizationService) => {
                         const oScope = {
-                            keyCategory: PersonalizationService.constants.keyCategory.FIXED_KEY,
-                            writeFrequency: PersonalizationService.constants.writeFrequency.LOW,
+                            keyCategory: PersonalizationService.KeyCategory.FIXED_KEY,
+                            writeFrequency: PersonalizationService.WriteFrequency.LOW,
                             clientStorageAllowed: true
                         };
 

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

@@ -3,7 +3,7 @@
 /**
  * @fileOverview The Unified Shell's page building service.
  *
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/ui/thirdparty/jquery"
@@ -17,9 +17,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's page building service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("PageBuilding")</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 PageBuilding = await Container.getServiceAsync("PageBuilding");
+     *     // do something with the PageBuilding service
+     *   });
+     * </pre>
      *
      * @param {object} oAdapter The page building adapter for the logon system
      * @param {object} oContainerInterface The interface provided by the container

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

@@ -6,7 +6,7 @@
  * It provides the layout and tile data of pages in the pages runtime.
  * Only used on the ABAP platform and on local for testing.
  *
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([], function () {
     "use strict";
@@ -16,9 +16,13 @@ sap.ui.define([], function () {
      * @class
      * @classdesc The Unified Shell's PagePersistence service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("PagePersistence")</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 PagePersistence = await Container.getServiceAsync("PagePersistence");
+     *     // do something with the PagePersistence service
+     *   });
+     * </pre>
      *
      * @param {object} adapter
      *     the page persistency adapter for the frontend server

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

@@ -2,7 +2,7 @@
 
 /**
  * @fileOverview This module deals with page related referencing and dereferencing.
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/ushell/services/_PageReferencing/PageReferencer"
@@ -14,9 +14,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's PageReferencing service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("PageReferencing")</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 PageReferencing = await Container.getServiceAsync("PageReferencing");
+     *     // do something with the PageReferencing service
+     *   });
+     * </pre>
      *
      * @hideconstructor
      *

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

@@ -2,7 +2,7 @@
 
 /**
  * @fileOverview This module exposes a model containing the pages hierarchy to its clients.
- * @version 1.123.1
+ * @version 1.124.1
  */
 sap.ui.define([
     "sap/base/Log",
@@ -40,9 +40,13 @@ sap.ui.define([
      * @class
      * @classdesc The Unified Shell's Pages service.
      *
-     * <b>Note:</b> To retrieve a valid instance of this service, it is necessary to call
-     * <code>sap.ushell.Container.getServiceAsync("Pages")</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 Pages = await Container.getServiceAsync("Pages");
+     *     // do something with the Pages service
+     *   });
+     * </pre>
      *
      * @hideconstructor
      *