@sapui5/sap.ushell 1.132.1 → 1.134.0

package/src/main/js/sap/ushell/components/applicationIntegration/ApplicationContainer.js

@@ -0,0 +1,272 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+/**
+ * @fileOverview The UI integration's SAPUI5 control which supports application embedding.
+ * @version 1.134.0
+ */
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ui/core/Control",
+    "sap/ushell/components/applicationIntegration/ApplicationContainerRenderer",
+    "sap/ushell/Config",
+    "sap/ushell/library", // css style dependency
+    "sap/ushell/utils"
+], (
+    Log,
+    Control,
+    ApplicationContainerRenderer,
+    Config,
+    ushellLibrary,
+    ushellUtils
+) => {
+    "use strict";
+
+    if (Config.last("/core/navigation/enableAppLifeCycleFallback")) {
+        return {};
+    }
+
+    // shortcut for sap.ushell.components.applicationIntegration.contracts.StatefulType
+    const StatefulType = ushellLibrary.components.applicationIntegration.contracts.StatefulType;
+
+    // shortcut for sap.ushell.components.container.ApplicationType
+    const ApplicationType = ushellLibrary.components.container.ApplicationType;
+
+    /**
+     * @alias sap.ushell.components.applicationIntegration.ApplicationContainer
+     * Creates a new container control embedding the application with the given URL. The default
+     * application type is "URL" and allows to embed web applications into an <code>IFRAME</code>.
+     * By default, the container is visible and occupies the whole width and height of its parent.
+     *
+     * @class
+     * @classdesc A container control capable of embedding a variety of application types.
+     *
+     * <b>Note:</b> The browser does not allow to move an <code>IFRAME</code> around in the DOM
+     * while keeping its state. Thus every rerender of the control is blocked.
+     *
+     * @extends sap.ui.core.Control
+     * @since 1.15.0
+     */ // eslint-disable-next-line max-len
+    const ApplicationContainer = Control.extend("sap.ushell.components.applicationIntegration.ApplicationContainer", /** @lends sap.ushell.components.applicationIntegration.ApplicationContainer.prototype */ {
+        metadata: {
+            properties: {
+                /**
+                 * The container's height as a CSS size. This attribute is provided to the browser "as is"!
+                 * <b>Note:</b> The HTML 4.01 specification allows pixels and percentages,
+                 * but the HTML 5 specification allows pixels only!
+                 */
+                height: { defaultValue: "100%", type: "sap.ui.core.CSSSize" },
+                /**
+                 * The container's width as a CSS size. This attribute is provided to the browser "as is"!
+                 * <b>Note:</b> The HTML 4.01 specification allows pixels and percentages,
+                 * but the HTML 5 specification allows pixels only!
+                 */
+                width: { defaultValue: "100%", type: "sap.ui.core.CSSSize" },
+
+                active: { defaultValue: true, type: "boolean" },
+                currentAppUrl: { defaultValue: "", type: "string" },
+                currentAppId: { defaultValue: "", type: "string" },
+                shellUIService: { type: "object" },
+                statefulType: { defaultValue: StatefulType.NotSupported, type: "sap.ushell.components.applicationIntegration.contracts.StatefulType" },
+                beforeAppCloseEvent: { type: "object" },
+                isKeepAlive: { defaultValue: false, type: "boolean" },
+                isFetchedFromCache: { defaultValue: false, type: "boolean" },
+                capabilities: { defaultValue: {}, type: "object" },
+
+                // todo: [FLPCOREANDUX-10024] rework this
+                iframeReusedForApp: { defaultValue: false, type: "boolean" },
+
+                // todo: [FLPCOREANDUX-10024] rework this
+                isInvalidIframe: { defaultValue: false, type: "boolean" },
+                isIframeValidTime: { defaultValue: { time: 0 }, type: "object" },
+
+                currentAppTargetResolution: { type: "object" },
+
+                // ==========================================
+                // ========== ResolvedHashFragment ==========
+
+                // appFrameworkId from app capabilities
+                frameworkId: { defaultValue: "", type: "string" },
+
+                /**
+                 * The type of the embedded application.
+                 */
+                applicationType: { defaultValue: ApplicationType.URL, type: "sap.ushell.components.container.ApplicationType" },
+                openWithPostByAppParam: { defaultValue: true, type: "boolean" },
+                reservedParameters: { type: "object" },
+                systemAlias: { defaultValue: "", type: "string" },
+                targetNavigationMode: { defaultValue: "", type: "string" },
+                /**
+                 * The URL to the embedded application.
+                 */
+                url: { defaultValue: "", type: "string" }
+            },
+            events: {
+                /**
+                 * Event which is fired when the <code>ApplicationContainer</code> control is rendered. The
+                 * event holds a technology specific configuration object for the embedded application.
+                 * As of now, only configuration for an embedded <em>SAPUI5 component</em> is supported.
+                 */
+                applicationConfiguration: { // todo: [FLPCOREANDUX-10024] make this event used consistently
+                    parameters: {
+                        /**
+                         * The technology specific configuration object of the embedded application.
+                         * <code>undefined</code>, if the <code>ApplicationContainer</code> control does not
+                         * provide a configuration for the technology of the embedded application or if there is a
+                         * rendering issue with the application.<br/>
+                         * For SAPUI5 components, the <code>config</code> property of the component metadata is
+                         * provided.
+                         */
+                        configuration: { type: "object" }
+                    }
+                }
+            },
+            library: "sap.ushell"
+        },
+        renderer: ApplicationContainerRenderer
+    });
+
+    // we have to cache the UI5 version first to have it available sync for the renderer
+    ApplicationContainer.ui5version = null;
+    ApplicationContainer.ui5versionPromise = ushellUtils.getUi5Version().then((sVersion) => {
+        Log.debug(`Using ui5-version: ${sVersion}`, null, "sap.ushell.components.applicationIntegration.ApplicationContainer");
+        ApplicationContainer.ui5version = sVersion;
+    });
+
+    ApplicationContainer.prototype.getUi5Version = function () {
+        return ApplicationContainer.ui5version;
+    };
+
+    /**
+     * Initialization of <code>ApplicationContainer</code> instance.
+     */
+    ApplicationContainer.prototype.init = function () {
+
+        // set object default values again to prevent them from being "synced"
+        this.setProperty("capabilities", {}, true);
+    };
+
+    ApplicationContainer.prototype.invalidate = function () {
+        if (this.getDomRef()) {
+            //always prevent re-rendering of application container once it's rendered
+            return this;
+        }
+
+        return Control.prototype.invalidate.apply(this, arguments);
+    };
+
+    /**
+     * Method called by the appLifeCycle to post a "before close" message to the app
+     * running in the iframe before the iframe its destroyed.
+     * The message is sent only if the iframe registered to be informed with this message.
+     * This mechanism was added to solve the change made in Chrome to disallow Sync XHR on
+     * browser close.
+     *
+     * @returns {Promise}
+     *  A promise object in case a post message is sent, and "undefined" in case no message needs
+     *  to be sent. In case of real promise, it will be resolved when the iframe response back that
+     *  it processed the message.
+     *
+     * @private
+     */
+    ApplicationContainer.prototype.sendBeforeAppCloseEvent = async function () {
+        // can be implemented by sub classes
+    };
+
+    // todo: [FLPCOREANDUX-10024] remove this
+    ApplicationContainer.setHandleMessageEvent = function (inFnHandleMessageEvent) {
+        ApplicationContainer.handleMessageEvent = inFnHandleMessageEvent;
+    };
+
+    /**
+     * Determine if the source of a received postMessage can be considered as trusted. We consider
+     * the content window of the application container's iframe as trusted
+     *
+     * @param {object} oMessage
+     *   the postMessage event object
+     * @returns {boolean}
+     *   true if source is considered to be trustworthy
+     * @private
+     * @since 1.24
+     */
+    ApplicationContainer.prototype.isTrustedPostMessageSource = function (oMessage) {
+        // sub classes can override this method to implement their own logic
+        return false;
+    };
+
+    ApplicationContainer.prototype.getPostMessageTarget = function () {
+        // needs to be implemented by sub classes
+    };
+
+
+    ApplicationContainer.prototype.getPostMessageTargetOrigin = function () {
+        // needs to be implemented by sub classes
+        return "";
+    };
+
+    /**
+     * Merges the given capabilities into the existing blue box capabilities.
+     * Existing capabilities are overwritten.
+     * @param {{string}[]} aNewCapabilities The additional capabilities.
+     * @returns {this} this instance for method chaining
+     *
+     * @since 1.130.0
+     * @private
+     */
+    ApplicationContainer.prototype.addCapabilities = function (aNewCapabilities) {
+        const oCapabilities = this.getCapabilities();
+
+        aNewCapabilities.forEach((sCapability) => {
+            oCapabilities[`${sCapability}`.toLowerCase()] = true;
+        });
+        return this;
+    };
+
+    /**
+     * Removes the given capabilities from the existing blue box capabilities.
+     * If no capabilities are provided, all capabilities are removed.
+     * @param {string[]} [aCapabilitiesToRemove] The capabilities to remove.
+     * @returns {this} this instance for method chaining
+     *
+     * @since 1.130.0
+     * @private
+     */
+    ApplicationContainer.prototype.removeCapabilities = function (aCapabilitiesToRemove) {
+        const oCapabilities = this.getCapabilities();
+
+        if (!aCapabilitiesToRemove) {
+            this.setProperty("capabilities", {}, true);
+            return this;
+        }
+
+        aCapabilitiesToRemove.forEach((sCapability) => {
+            delete oCapabilities[`${sCapability}`.toLowerCase()];
+        });
+        return this;
+    };
+
+    /**
+     * Checks if this application container supports the given capabilities.
+     * @param {string[]} aRequiredCapabilities The capabilities to check.
+     * @returns {boolean} true if the blue box capabilities contain the given service and action
+     *
+     * @since 1.130.0
+     * @private
+     */
+    ApplicationContainer.prototype.supportsCapabilities = function (aRequiredCapabilities) {
+        const oCapabilities = this.getCapabilities();
+
+        return aRequiredCapabilities.every((sRequiredCapability) => {
+            return oCapabilities[`${sRequiredCapability}`.toLowerCase()];
+        });
+    };
+
+    // helper for tests
+    ApplicationContainer._setCachedUI5Version = function (sNewVersion) {
+        ApplicationContainer.ui5version = sNewVersion;
+        ApplicationContainer.ui5versionPromise = ApplicationContainer.ui5versionPromise.then(() => {
+            ApplicationContainer.ui5version = sNewVersion;
+        });
+    };
+
+    return ApplicationContainer;
+});

package/src/main/js/sap/ushell/components/applicationIntegration/ApplicationContainerCache.js

@@ -0,0 +1,229 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+sap.ui.define([
+    "sap/base/Log",
+    "sap/ushell/Config"
+], function (
+    Log,
+    Config
+) {
+    "use strict";
+
+    if (Config.last("/core/navigation/enableAppLifeCycleFallback")) {
+        return {};
+    }
+
+    class ApplicationContainerCache {
+        #aActiveContainers = [];
+        #aReusableContainers = {};
+
+        constructor () {
+            this.init();
+        }
+
+        init () {
+            // any active application containers
+            this.#aActiveContainers = [];
+            // containers that are ready for reuse
+            // ... also contains appruntime
+            this.#aReusableContainers = [];
+        }
+
+        setContainerActive (oApplicationContainer) {
+            if (!oApplicationContainer) {
+                return;
+            }
+
+            if (this.#aActiveContainers.includes(oApplicationContainer)) {
+                Log.warning("The container is already active");
+                return;
+            }
+
+            this.removeByContainer(oApplicationContainer);
+
+            this.#aActiveContainers.push(oApplicationContainer);
+        }
+
+        setContainerReadyForReuse (oApplicationContainer, sUrl) {
+            if (!oApplicationContainer) {
+                return;
+            }
+
+            if (!this.#aActiveContainers.includes(oApplicationContainer) && this.getById(oApplicationContainer.getId())) {
+                Log.warning("The container is already in pool");
+                return;
+            }
+
+            this.removeByContainer(oApplicationContainer);
+
+            this.#aReusableContainers.push({
+                url: sUrl,
+                key: this.#getKeyFromUrl(sUrl),
+                container: oApplicationContainer
+            });
+        }
+
+        findFreeContainerByUrl (sUrl) {
+            const sKey = this.#getKeyFromUrl(sUrl);
+
+            // use latest free container
+            const oFreeContainer = this.#aReusableContainers.reverse().find((oContainer) => {
+                return oContainer.key === sKey;
+            });
+
+            if (oFreeContainer) {
+                return oFreeContainer.container;
+            }
+        }
+
+        canBeReused (oApplicationContainer, sUrl) {
+            if (!oApplicationContainer) {
+                return false;
+            }
+
+            if (this.#aActiveContainers.includes(oApplicationContainer)) {
+                return false;
+            }
+
+            const sKey = this.#getKeyFromUrl(sUrl);
+            const oEntry = this.#aReusableContainers.find((oContainer) => {
+                return oContainer.container === oApplicationContainer;
+            });
+
+            return !!oEntry && oEntry.key === sKey;
+        }
+
+        getLength () {
+            return this.#aActiveContainers.length;
+        }
+
+        getPoolLength () {
+            return this.#aReusableContainers.length;
+        }
+
+        removeByContainer (oApplicationContainer) {
+            if (!oApplicationContainer) {
+                return;
+            }
+
+            this.#aActiveContainers = this.#aActiveContainers.filter((oContainer) => {
+                return oContainer !== oApplicationContainer;
+            });
+
+            this.#aReusableContainers = this.#aReusableContainers.filter((oContainer) => {
+                return oContainer.container !== oApplicationContainer;
+            });
+        }
+
+        getById (sId) {
+            let oApplicationContainerFound;
+            this.forEach((oApplicationContainer) => {
+                if (oApplicationContainer.getId() === sId) {
+                    oApplicationContainerFound = oApplicationContainer;
+                }
+            });
+
+            return oApplicationContainerFound;
+        }
+
+        getAll () {
+            return [
+                ...this.#aActiveContainers,
+                ...this.#aReusableContainers.map((oEntry) => oEntry.container)
+            ];
+        }
+
+        forEach (fnCallback) {
+            this.#aActiveContainers.forEach((oApplicationContainer) => {
+                fnCallback(oApplicationContainer);
+            });
+
+            this.#aReusableContainers.forEach((oEntry) => {
+                fnCallback(oEntry.container);
+            });
+        }
+
+        /**
+         * Builds a key of a reusable iframe that is not destroyed and can be reused.
+         * When a new application is opened, and it is hosted in an iframe, in order to
+         * check if an iframe for this app already exists, we will build the iframe key based
+         * on hard coded keys (The keys are always taken from the URL parameters).
+         *
+         * The structure of the string key:
+         * [url-origin]@hint:[sap-iframe-hint]@uiver:[sap-ui-version]@
+         *
+         * Example of an iframe key:
+         * http://www.test.com@hint:ABC@uiver:1.84.0@async:false@ka:[sap-keep-alive]@async:sap-async-loading@fesr:[sap-calm]@testid:[sap-testcflp-iframeid]
+         *
+         * NOTE: reusable iframes are kept in in "oCacheStorage" declared above.
+         *
+         * @param {string} sUrl application url
+         * @returns {string} iframe key.
+         * @private
+         */
+        #getKeyFromUrl (sUrl) {
+            let sOrigin;
+            let sIframeHint = "";
+            let sUI5Version = "";
+            let sUI5Async = "";
+            let sFESR = "";
+            let sTestUniqueId = "";
+
+            const oURL = new URL(sUrl, this._getWindowLocationHref());
+
+            sOrigin = oURL.origin;
+            if (oURL.port === "") {
+                if (oURL.protocol === "https:") {
+                    sOrigin = sOrigin + ":443";
+                } else if (oURL.protocol === "http:") {
+                    sOrigin = sOrigin + ":80";
+                }
+            }
+
+            const oSearchParams = oURL.searchParams;
+            if (oSearchParams.has("sap-iframe-hint")) {
+                sIframeHint = "@hint:" + oSearchParams.get("sap-iframe-hint");
+            }
+            if (oSearchParams.has("sap-ui-version")) {
+                sUI5Version = "@uiver:" + oSearchParams.get("sap-ui-version");
+            }
+            if (oSearchParams.has("sap-async-loading") && oSearchParams.get("sap-async-loading") !== "true") {
+                sUI5Async = "@async:" + oSearchParams.get("sap-async-loading");
+            }
+            if (oSearchParams.has("sap-enable-fesr") && oSearchParams.get("sap-enable-fesr") !== "false") {
+                sFESR = "@fesr:" + oSearchParams.get("sap-enable-fesr");
+            }
+            if (oSearchParams.has("sap-testcflp-iframeid")) {
+                sTestUniqueId = "@testid:" + oSearchParams.get("sap-testcflp-iframeid");
+            }
+
+            return sOrigin.toLowerCase() + sIframeHint + sUI5Version + sUI5Async + sFESR + sTestUniqueId;
+        }
+
+        _getWindowLocationHref () {
+            return window.location.href;
+        }
+
+        _getStorageForDebug () {
+            return {
+                activeContainers: this.#aActiveContainers,
+                reusableContainers: this.#aReusableContainers
+            };
+        }
+
+        /**
+         * For testing purposes only.
+         * Destroys all the application containers.
+         *
+         * @since 1.130.0
+         * @private
+         */
+        destroyAllContainers () {
+            this.forEach((oApplicationContainer) => {
+                this.removeByContainer(oApplicationContainer);
+                oApplicationContainer.destroy();
+            });
+        }
+    }
+
+    return new ApplicationContainerCache();
+});

package/src/main/js/sap/ushell/components/applicationIntegration/ApplicationContainerRenderer.js

@@ -0,0 +1,35 @@
+// Copyright (c) 2009-2025 SAP SE, All Rights Reserved
+
+
+sap.ui.define([
+    "sap/ushell/Config"
+], (
+    Config
+) => {
+    "use strict";
+
+    if (Config.last("/core/navigation/enableAppLifeCycleFallback")) {
+        return {};
+    }
+
+    const ApplicationContainerRenderer = {
+        apiVersion: 2
+    };
+
+    ApplicationContainerRenderer.waitForUI5Version = function (oContainer) {
+        const ApplicationContainer = oContainer.getMetadata().getClass();
+        // we have to cache the UI5 version first
+        if (ApplicationContainer.ui5version === null) {
+            ApplicationContainer.ui5versionPromise.then(() => {
+                oContainer.invalidate();
+            });
+            return true;
+        }
+    };
+
+    ApplicationContainerRenderer.render = function (oRenderManager, oContainer) {
+        // should be implemented by the extending renderer
+    };
+
+    return ApplicationContainerRenderer;
+});