@sapui5/sap.ushell_abap 1.94.1 → 1.97.0

package/src/main/js/sap/ushell_abap/pbServices/ui2/contracts/preview.js

@@ -0,0 +1,289 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>preview</code> contract.
+ */
+ sap.ui.require([
+    "sap/ushell_abap/pbServices/ui2/Chip"
+], function (
+    Chip
+) {
+    "use strict";
+
+    if (typeof jQuery === "function" && jQuery.sap) {
+        jQuery.sap.declare("sap.ui2.srvc.contracts.preview");
+    }
+
+    sap.ui2 = sap.ui2 || {};
+    sap.ui2.srvc = sap.ui2.srvc || {};
+    sap.ui2.srvc.contracts = sap.ui2.srvc.contracts || {};
+    sap.ui2.srvc.contracts.preview = sap.ui2.srvc.contracts.preview || {};
+    /**
+    * Allows the page builder to set the global type of environment for the preview contract to either runtime or design time.
+    * Based on this a CHIP can decide what preview to be shown. For example, in preview mode at design time, no HTTP request should be made,
+    * while in preview mode at runtime the CHIP may request a minimum of data to make the CHIP identifiable.
+    *
+    * By default the environment is unspecified (null).
+    *
+    * @param {string} sEnvironment
+    *  Specified if the page builder is a design time or an runtime. Accepts only the values 'runtime' or 'designtime'.
+    *
+    * @since 1.71.0
+    * @public
+    * @see chip.preview.getEnvironmentType
+    */
+    sap.ui2.srvc.contracts.preview.setEnvironmentType = function (sEnvironment) {
+        if (sEnvironment !== "runtime" && sEnvironment !== "designtime") {
+            throw new Error("setEnvironmentType only accepts the values 'runtime' or 'designtime'");
+        }
+
+        this.environment = sEnvironment;
+    };
+
+    /**
+     * Returns the global type of environment for the preview contract. Based on this a CHIP can decide what
+     * preview to be shown. For example, in preview mode at design time, no HTTP request should be made,
+     * while in preview mode at runtime the CHIP may request a minimum of data to make the CHIP identifiable.
+     *
+     * By default the environment is unspecified (null).
+     *
+     * @returns {string} Returns null, which means unspecified, 'runtime' or 'designtime'.
+     *
+     * @since 1.71.0
+     * @private
+     *
+     * @see #setEnvironmentType
+     */
+    sap.ui2.srvc.contracts.preview.getEnvironmentType = function () {
+        return this.environment;
+    };
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>preview</code> contract, which
+     * allows to display the CHIP in a preview mode.
+     * @name chip.preview
+     * @since 1.11.0
+     */
+    Chip.addContract("preview", /* @returns {object} */ function (oChipInstance) {
+        var bEnabled = false,
+            sPreviewIconUrl,
+            sPreviewSubtitle,
+            sPreviewTitle,
+            sTargetUrl;
+
+        /**
+         * Returns this CHIP's description. May be used by the CHIP for the UI it shows in preview
+         * mode.
+         *
+         * @name chip.preview.getDescription
+         * @function
+         * @since 1.11.0
+         * @returns {string}
+         *   the CHIP description
+         */
+        this.getDescription = function () {
+            return oChipInstance.getChip().getDescription();
+        };
+
+        /**
+         * Returns this CHIP's title. May be used by the CHIP for the UI it shows in preview mode.
+         *
+         * @name chip.preview.getTitle
+         * @function
+         * @since 1.11.0
+         * @returns {string}
+         *   the CHIP title
+         */
+        this.getTitle = function () {
+            return oChipInstance.getTitle();
+        };
+
+        /**
+         * Tells whether preview mode is enabled. Note that this value is constant throughout
+         * a CHIP's lifetime. If preview mode is enabled, CHIPs should provide a target URL for the
+         * embedding application to trigger navigation, see {@link chip.preview.setTargetUrl}.
+         * They should not display live data for performance reasons.
+         *
+         * @name chip.preview.isEnabled
+         * @function
+         * @since 1.11.0
+         * @returns {boolean}
+         *   whether preview mode is enabled
+         */
+        this.isEnabled = function () {
+            return bEnabled;
+        };
+
+        /**
+         * Returns the type of environment in which the preview mode maybe displayed.
+         *
+         * Based on this a CHIP can decide what preview to be shown. For example, in preview
+         * mode at design time, no HTTP request should be made, while in preview mode at runtime
+         * the CHIP may request a minimum of data to make the CHIP identifiable.
+         *
+         * @returns {string} Returns null, which means unspecified, 'runtime' or 'designtime'.
+         *
+         * @since 1.71.0
+         * @public
+         *
+         * @see sap.ui2.srvc.contracts.preview#setEnvironmentType
+         *  @since 1.71.0
+         */
+        this.getEnvironmentType = function () {
+            return sap.ui2.srvc.contracts.preview.getEnvironmentType();
+        };
+
+        /**
+         * Determines the preview icon to be used by the embedding application for this CHIP.
+         *
+         * @name chip.preview.setPreviewIcon
+         * @function
+         * @since 1.11.0
+         * @param {string} sNewPreviewIconUrl
+         *   the preview icon URL. It is recommended that this URL follows the rules defined for the
+         *   <code>src</code> attribute of <code>sap.ui.core.Icon</code>.
+         */
+        this.setPreviewIcon = function (sNewPreviewIconUrl) {
+            sPreviewIconUrl = sNewPreviewIconUrl;
+        };
+
+        /**
+         * Determines the preview subtitle to be used by the embedding application for this CHIP.
+         *
+         * @name chip.preview.setPreviewSubtitle
+         * @function
+         * @since 1.40.0
+         * @param {string} sNewPreviewSubtitle
+         *   the preview subtitle.
+         */
+        this.setPreviewSubtitle = function (sNewPreviewSubtitle) {
+            sPreviewSubtitle = sNewPreviewSubtitle;
+        };
+
+        /**
+         * Determines the preview title to be used by the embedding application for this CHIP. If the
+         * CHIP has no specific preview title e.g. based on its configuration it may return the title
+         * from the <code>getTitle</code> method of this contract.
+         *
+         * @name chip.preview.setPreviewTitle
+         * @function
+         * @since 1.11.0
+         * @param {string} sNewPreviewTitle
+         *   the preview title.
+         *
+         * @see chip.preview.getTitle
+         */
+        this.setPreviewTitle = function (sNewPreviewTitle) {
+            sPreviewTitle = sNewPreviewTitle;
+        };
+
+        /**
+         * Determines the target URL for navigation from this CHIP. May be used by the embedding
+         * application to trigger navigation to the CHIP's underlying application.
+         *
+         * @name chip.preview.setTargetUrl
+         * @function
+         * @since 1.11.0
+         * @param {string} sNewTargetUrl
+         *   the target URL for navigation triggered in this CHIP
+         */
+        this.setTargetUrl = function (sNewTargetUrl) {
+            sTargetUrl = sNewTargetUrl;
+        };
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>preview</code> contract, which allows you to display a CHIP in preview
+         * mode and to retrieve the URL of the CHIP's underlying application.
+         * "Preview mode" means that a CHIP does not retrieve and display live data, but displays a
+         * static preview in order to improve performance.
+         * The embedding application has two alternatives to display a CHIP preview:
+         * Either it embeds the CHIP UI and relies on the CHIP not rendering live data or it
+         * retrieves preview attributes like title and icon from the CHIP to create the preview UI
+         * itself.
+         *
+         * @name contract.preview
+         * @since 1.11.0
+         */
+        return {
+            /**
+             * Returns the URL of the preview icon for this CHIP.
+             *
+             * @name contract.preview.getPreviewIcon
+             * @function
+             * @returns {string}
+             *   the preview icon's URL
+             * @since 1.11.0
+             *
+             * @see chip.preview.setPreviewIcon
+             */
+            getPreviewIcon: function () {
+                return sPreviewIconUrl;
+            },
+
+            /**
+             * Returns the preview subtitle for this CHIP.
+             *
+             * @name contract.preview.getPreviewSubtitle
+             * @function
+             * @returns {string}
+             *   the preview subtitle
+             * @since 1.40.0
+             *
+             * @see chip.preview.setPreviewSubtitle
+             */
+            getPreviewSubtitle: function () {
+                return sPreviewSubtitle;
+            },
+
+            /**
+             * Returns the preview title for this CHIP.
+             *
+             * @name contract.preview.getPreviewTitle
+             * @function
+             * @returns {string}
+             *   the preview title
+             * @since 1.11.0
+             *
+             * @see chip.preview.setPreviewTitle
+             */
+            getPreviewTitle: function () {
+                return sPreviewTitle;
+            },
+
+            /**
+             * Returns the target URL for the CHIP's underlying application.
+             *
+             * @name contract.preview.getTargetUrl
+             * @function
+             * @returns {string}
+             *   target URL
+             * @since 1.11.0
+             *
+             * @see chip.preview.setTargetUrl
+             */
+            getTargetUrl: function () {
+                return sTargetUrl;
+            },
+
+            /**
+             * Determines whether preview mode for this CHIP instance is enabled by the page builder.
+             * <b>Note:</b> Changing this setting after <code>getImplementationAsSapui5()</code> has been
+             * called probably violates the contract of <code>chip.preview.isEnabled()</code>!
+             *
+             * @param {boolean} bNewEnabled
+             *   whether preview mode for this CHIP instance is enabled by the page builder
+             *
+             * @name contract.preview.setEnabled
+             * @function
+             * @since 1.11.0
+             *
+             * @see sap.ushell_abap.pbServices.ui2.ChipInstance#getImplementationAsSapui5()
+             * @see chip.preview.isEnabled
+             */
+            setEnabled: function (bNewEnabled) {
+                bEnabled = bNewEnabled;
+            }
+        };
+    });
+});

package/src/main/js/sap/ushell_abap/pbServices/ui2/contracts/refresh.js

@@ -0,0 +1,43 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>refresh</code> contract.
+ */
+ sap.ui.require([
+    "sap/ushell_abap/pbServices/ui2/Chip"
+], function (
+    Chip
+) {
+    "use strict";
+
+    if (typeof jQuery === "function" && jQuery.sap) {
+        jQuery.sap.declare("sap.ui2.srvc.contracts.refresh");
+    }
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>refresh</code> contract, which allows you to
+     * handle refresh events.
+     * @name chip.refresh
+     * @since 1.2.0
+     */
+    Chip.addContract("refresh", function (oChipInstance) {
+        /**
+         * Attaches the given event handler to the "refresh" event which is fired
+         * whenever the user requests a refresh of this CHIP's content.
+         *
+         * Use <code>Function.prototype.bind()</code> to determine the event handler's
+         * <code>this</code> or some of its arguments.
+         *
+         * Note: Without such an event handler, the CHIP will be recreated to enforce a refresh!
+         *
+         * @name chip.refresh.attachRefresh
+         * @function
+         * @since 1.2.0
+         * @param {function} fnEventHandler
+         *   the event handler for the "refresh" event
+         */
+        this.attachRefresh = function (fnEventHandler) {
+            oChipInstance.attachRefresh(fnEventHandler);
+        };
+    });
+});

package/src/main/js/sap/ushell_abap/pbServices/ui2/contracts/search.js

@@ -0,0 +1,115 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>search</code> contract.
+ */
+sap.ui.define([
+    "sap/ushell_abap/pbServices/ui2/Chip",
+    "sap/ushell_abap/pbServices/ui2/Error",
+    "sap/ushell_abap/pbServices/ui2/Utils"
+], function (
+    Chip,
+    SrvcError,
+    Utils
+) {
+    "use strict";
+
+    if (typeof jQuery === "function" && jQuery.sap) {
+        jQuery.sap.declare("sap.ui2.srvc.contracts.search");
+    }
+
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>search</code> contract with
+     * CHIP search-related functionality. With this contract, the CHIP can provide CHIP-specific
+     * search keywords. In addition, it can highlight words from the search in its UI.
+     * @name chip.search
+     * @since 1.11.0
+     */
+    Chip.addContract("search", function (oChipInstance) {
+        var fnHighlight,
+            aKeywords;
+
+        /**
+         * Determines specific keywords with which the CHIP wants to be found in a search over all
+         * CHIPs from the page builder. If not set, the page builder executing a CHIP search can only
+         * search based on CHIP metadata like the CHIP title.
+         *
+         * @name chip.search.setKeywords
+         * @function
+         * @since 1.11.0
+         * @param {string[]} aNewKeywords
+         *   the keywords of this CHIP
+         */
+        this.setKeywords = function (aNewKeywords) {
+            if (!Utils.isArray(aNewKeywords)) {
+                throw new SrvcError("Not an array: " + aNewKeywords, "chip.search");
+            }
+            aKeywords = aNewKeywords.slice();
+        };
+
+        /**
+         * Attaches the given event handler to the "highlight" event which is fired whenever the user
+         * executes a search over all CHIPs using specific search terms. The event handler takes a
+         * string array as parameter, containing the highlight words. These are derived from the
+         * search terms. The CHIP can then highlight these in its UI.
+         *
+         * @name chip.search.attachHighlight
+         * @function
+         * @since 1.11.0
+         * @param {function (string[])} fnEventHandler
+         *   event handler for highlighting words in the CHIP UI which takes a string array with the
+         *   highlight words as parameter
+         */
+        this.attachHighlight = function (fnEventHandler) {
+            if (typeof fnEventHandler !== "function") {
+                throw new SrvcError("Not a function: " + fnEventHandler,
+                    "chip.search");
+            }
+            fnHighlight = fnEventHandler;
+        };
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>search</code> contract. This contract interface allows the pagebuilder to get
+         * the CHIP-specific search keywords. In addition, it can have the CHIP highlight words
+         * in its UI based on the search terms used.
+         * @name contract.search
+         * @since 1.11.0
+         */
+        return {
+            /**
+             * Returns the CHIP-specific search keywords.
+             *
+             * @name contract.search.getKeywords
+             * @function
+             * @since 1.11.0
+             * @returns {string[]}
+             *   CHIP-specific search keywords. Empty array if the CHIP has not set any keywords.
+             *
+             * @see chip.search.setKeywords
+             */
+            getKeywords: function () {
+                return aKeywords ? aKeywords.slice() : [];
+            },
+
+            /**
+             * Fires the "highlight" event which takes a string array with the words to
+             * be highlighted as parameters.
+             *
+             * @name contract.search.fireHighlight
+             * @function
+             * @since 1.11.0
+             * @param {string[]} aHighlightWords
+             *   words to be highlighted
+             *
+             * @see chip.search.attachHighlight
+             */
+            fireHighlight: function (aHighlightWords) {
+                if (fnHighlight) {
+                    fnHighlight(aHighlightWords);
+                }
+            }
+        };
+    });
+});

package/src/main/js/sap/ushell_abap/pbServices/ui2/contracts/types.js

@@ -0,0 +1,9 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview Dummy file, The <code>types</code> contract is in the file contracts/actions.js !
+ * @since 1.32.0
+ */
+(function () {
+    "use strict";
+}());

package/src/main/js/sap/ushell_abap/pbServices/ui2/contracts/url.js

@@ -0,0 +1,105 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>url</code> contract.
+ */
+ sap.ui.define([
+    "sap/ushell_abap/pbServices/ui2/Chip"
+], function (
+    Chip
+) {
+    "use strict";
+
+    if (typeof jQuery === "function" && jQuery.sap) {
+        jQuery.sap.declare("sap.ui2.srvc.contracts.url");
+    }
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>url</code> contract, which allows you
+     * convert relative URLs into absolute ones.
+     * @name chip.url
+     * @since 1.2.0
+     */
+    Chip.addContract("url", function (oChipInstance) {
+        /**
+         * Makes the given server-relative service URL point to the system given as parameter
+         * <code>sSystem</code> or to the system of this CHIP's catalog if <code>sSystem</code>
+         * is empty.
+         * <em>Server-relative URL</em> means a URL starting with exactly one "/" (also known as
+         * absolute-path URL).
+         * <p>
+         * The function is typically used if the CHIP has been loaded from a remote catalog. In this
+         * case, a CHIP wants to perform service calls to the system providing the remote catalog:
+         * it must convert the corresponding URLs via this method. The function may also be used for
+         * CHIPs loaded from a local catalog to perform service calls to a different system.
+         * <p>
+         * The system is added via segment parameter <code>o</code> to the last URL segment of the
+         * service URL. It is also possible to make this function put the system to a different
+         * URL path segment of the service URL by specifying the empty segment parameter
+         * <code>o</code>. If both <code>sSystem</code> is empty and the CHIP is loaded from a local
+         * catalog, no system is added and the empty segment parameter <code>o</code> is removed.
+         * <br/>
+         * <b>Example 1:</b> <code>/sap/opu/odata/MyService/?p1=v1</code> is converted to
+         * <code>/sap/opu/odata/MyService;o=SYS/?p1=v1</code> if the corresponding CHIP has been loaded
+         * via a remote catalog with system ID &quot;SYS&quot;.
+         * However it remains unchanged if the CHIP has been loaded from the logon system <em>and</em>
+         * the parameter <code>sSystem</code> is empty.<br/>
+         * <b>Example 2:</b> <code>/sap/opu/odata/MyService;o=/MyEntities/$count?p1=v1</code> is
+         * converted to <code>/sap/opu/odata/MyService;o=sid(SYS.123)/MyEntities/$count?p1=v1</code> if
+         * parameter <code>sSystem</code> is set to &quot;sid(SYS.123)&quot;</code>.
+         * <p>
+         * The URL is in no way normalized.
+         *
+         * @name chip.url.addSystemToServiceUrl
+         * @function
+         * @since 1.19.1
+         * @param {string} sServiceUrl
+         *   a server-relative service URL (to be used when addressing the system directly)
+         * @param {string} [sSystem]
+         *   a system specification like &quot;SYS&quot; or &quot;sid(SYS.123)&quot;; if empty the
+         *   system of the CHIP's catalog is used
+         * @returns {string}
+         *   the service URL pointing to the system specified in parameter <code>sSystem</code> or to
+         *   the system from which the CHIP's catalog has been loaded
+         * @throws Error if the URL is not server-relative such as <code>./something</code>,
+         *   <code>http://foo.bar/something</code>, ...)
+         */
+        this.addSystemToServiceUrl = function (sServiceUrl, sSystem) {
+            return oChipInstance.getChip().getCatalog().addSystemToServiceUrl(sServiceUrl, sSystem);
+        };
+
+        /**
+         * Returns the system of this CHIP's catalog where application data for this CHIP is typically
+         * located. This API is needed in scenarios where a CHIP navigates to another application and
+         * needs to transfer system information so that the application can use the same application
+         * system.
+         *
+         * @name chip.url.getApplicationSystem
+         * @function
+         * @since 1.19.1
+         * @returns {string}
+         *   the system of this CHIP's catalog or <code>undefined</code> if there is no such catalog
+         * @see chip.url.addSystemToServiceUrl
+         */
+        this.getApplicationSystem = function () {
+            return oChipInstance.getChip().getCatalog().getSystemAlias();
+        };
+
+        /**
+         * Makes the given relative URL absolute. URLs containing host and/or protocol
+         * and URLs with an absolute path remain unchanged. The URL is in no way
+         * normalized; the function takes the URL of the CHIP definition XML as base.
+         *
+         * @name chip.url.toAbsoluteUrl
+         * @function
+         * @since 1.2.0
+         * @param {string} sUrl
+         *   the (possibly server-relative) URL
+         * @returns {string}
+         *   the absolute URL
+         */
+        this.toAbsoluteUrl = function (sUrl) {
+            return oChipInstance.getChip().toAbsoluteUrl(sUrl);
+        };
+    });
+});

package/src/main/js/sap/ushell_abap/pbServices/ui2/contracts/visible.js

@@ -0,0 +1,128 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>visible</code> contract.
+ */
+ sap.ui.require([
+    "sap/ushell_abap/pbServices/ui2/Chip",
+    "sap/ushell_abap/pbServices/ui2/Error",
+    "sap/base/Log"
+], function (
+    Chip,
+    SrvcError,
+    Log
+) {
+    "use strict";
+
+    if (typeof jQuery === "function" && jQuery.sap) {
+        jQuery.sap.declare("sap.ui2.srvc.contracts.visible");
+    }
+
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>visible</code> contract regarding the
+     * CHIP's current visibility within the page.
+     * @name chip.visible
+     * @since 1.17.1
+     */
+    Chip.addContract("visible", function (oChipInstance) {
+        var bVisible = true,
+            fnOnVisible;
+
+        /**
+         * Calls fnOnVisible with bVisible as parameter. Adds some some error handling ensuring that exceptions will
+         * not affect the page builder.
+         *
+         * @private
+         */
+        function callOnVisible () {
+            try {
+                fnOnVisible(bVisible);
+            } catch (e) {
+                Log.error(oChipInstance + ": call to visible handler failed: "
+                    + (e.message || e.toString()), null, "chip.visible");
+            }
+        }
+
+        /**
+         * Attaches the given event handler to the "visible" event which is fired whenever the CHIP's
+         * visibility has been changed. The event handler takes a boolean as parameter, representing
+         * the new visible state.
+         * (Since 1.42) fnEventHandler is called once initially with the current visibility making it
+         * unnecessary to check {#isVisible} when the CHIP is initialized. Attaching the same handler
+         * multiple times will only result in one call to it.
+         *
+         * @name chip.visible.attachVisible
+         * @function
+         * @since 1.17.0
+         * @param {function (boolean)} fnEventHandler
+         *   event handler for visibility changes
+         */
+        this.attachVisible = function (fnEventHandler) {
+            if (typeof fnEventHandler !== "function") {
+                throw new SrvcError("Not a function: " + fnEventHandler,
+                    "chip.visible");
+            }
+
+            // attaching the same handler multiple time should not end in multiple calls (see below)
+            if (fnOnVisible === fnEventHandler) {
+                return;
+            }
+            fnOnVisible = fnEventHandler;
+
+            // call the handler directly to stay compatible with previous behavior in the FLP.
+            // There the tiles where notified directly after instantiation (multiple tiles) so they
+            // did not need to check via isVisible() if they are visible or not.
+            callOnVisible();
+        };
+
+        /**
+         * Returns the CHIP's visibility within the page builder's page. The visibility is
+         * <code>true</code> initially.
+         *
+         * @name chip.visible.isVisible
+         * @function
+         * @since 1.17.0
+         * @returns {boolean}
+         *   the CHIP's visibility within the page builder's page.
+         * @see contract.visible.setVisible
+         */
+        this.isVisible = function () {
+            return bVisible;
+        };
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>visible</code> contract. This contract interface allows the pagebuilder to
+         * notify the CHIP when the CHIP's visibility has been changed.
+         *
+         * @name contract.visible
+         * @since 1.17.0
+         */
+        return {
+            /**
+             * Notifies the CHIP about its new visibility. The CHIP is only informed, if the
+             * visibility is different then before.
+             *
+             * @param {boolean} bNewVisible
+             *   the CHIP visibility
+             * @name contract.visible.setVisible
+             * @function
+             * @since 1.17.0
+             * @see chip.visible.isVisible
+             * @see chip.visible.attachVisible
+             */
+            setVisible: function (bNewVisible) {
+                if (bVisible === bNewVisible) {
+                    // nothing changed so do nothing
+                    return;
+                }
+
+                bVisible = bNewVisible;
+                if (fnOnVisible) {
+                    callOnVisible();
+                }
+            }
+        };
+    });
+});