@sapui5/sap.ushell_abap 1.94.1 → 1.97.0

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

@@ -0,0 +1,165 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>configuration</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.configuration");
+    }
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>configuration</code> contract, which allows
+     * you to read configuration parameters.
+     * @name chip.configuration
+     * @since 1.2.0
+     */
+    Chip.addContract("configuration", function (oChipInstance) {
+        var fnUpdatedHandler;
+
+        /**
+         * Returns the value of the configuration parameter with the given name as a
+         * string.
+         *
+         * Note: Use <code>JSON.parse(sParameterValue)</code> for values which represent
+         * objects or arrays, use <code>parseInt(sParameterValue, 10)<code> for values
+         * which represent integers, etc.
+         *
+         * @name chip.configuration.getParameterValueAsString
+         * @function
+         * @since 1.2.0
+         * @param {string} sParameterName
+         *   the parameter's name
+         * @returns {string}
+         *   the parameter's value
+         */
+        this.getParameterValueAsString = function (sParameterName) {
+            return oChipInstance.getConfigurationParameter(sParameterName);
+        };
+
+        /**
+         * Usually the Page Builder does not know about the internals of a CHIP, but there are special
+         * CHIPs (e.g. SAP Fiori Launchpad app launcher tiles, also serving as bookmark tiles) the
+         * Page Builder knows about the internals. In certain cases the Page Builder changes the configuration
+         * data of the CHIP and is able to notify the CHIP Instance what configuration properties have been updated,
+         * so the CHIP instance can update based on the new data.
+         *
+         * Note: The event must be explicitly triggered by the Page Builder. There is no automatic mechanism.
+         *
+         * @name chip.configuration.attachConfigurationUpdated
+         * @function
+         * @param {function(string[])} fnHandler
+         *   Handler which is called if the Page Builder updates one or multiple configuration properties on
+         *   the CHIP instance. fnHandler receives as first parameter an array containing keys of all first level
+         *   configuration properties which have been updated.
+         * @since 1.46.0
+         * @private
+         * @see contract.configuration.fireConfigurationUpdated
+         */
+        this.attachConfigurationUpdated = function (fnHandler) {
+            // Back channel for FLP bookmark tiles, as they are managed by the FLP Bookmark Service.
+            // The FLP directly changes the configuration data of the bookmark tile and can notify the bookmark
+            // tiles afterwards about the changes, so the bookmark tiles can update themselves with the new data.
+            if (typeof fnHandler !== "function") {
+                throw new SrvcError("The given handler is not a function",
+                    "chip.configuration");
+            }
+            fnUpdatedHandler = fnHandler;
+        };
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>configuration</code> contract.
+         * @name contract.configuration
+         * @private
+         */
+        return { // contract - private as only used by Fiori Launchpad
+            /**
+             * Allows the page builder to inform the CHIP about changes of certain configuration properties.
+             * Note: Usually the page builder should not care about the content of the CHIP's configuration; however,
+             * for bookmark tiles in SAP Fiori Launchpad this is required as the SAP Fiori Launchpad manages them.
+             *
+             * @name contract.configuration.fireConfigurationUpdated
+             * @function
+             * @param {string[]} aUpdatedConfigKeys
+             *   array of first-level configuration property keys which have been updated by the page builder
+             * @since 1.46.0
+             * @private
+             * @see chip.configuration.attachBagsUpdated
+             */
+            fireConfigurationUpdated: function (aUpdatedConfigKeys) {
+                if (!Utils.isArray(aUpdatedConfigKeys) || aUpdatedConfigKeys.length < 1) {
+                    throw new SrvcError("At least one configuration property key must be given",
+                        "contract.configuration");
+                }
+                if (fnUpdatedHandler) {
+                    fnUpdatedHandler(aUpdatedConfigKeys);
+                }
+            }
+        };
+    });
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>writeConfiguration</code> contract which
+     * allows you to write configuration parameters.
+     * @name chip.writeConfiguration
+     * @since 1.7.0
+     */
+    Chip.addContract("writeConfiguration", function (oChipInstance) {
+        /**
+         * Sets the values of the given configuration parameters and persists the updated chip
+         * instance. All parameters that actually were defined in the CHIP definition XML are accepted.
+         * All others will raise a warning to the log.
+         * <p>
+         * The configuration is maintained as JSON string in a single property. This has the following
+         * consequences regarding the scopes:
+         * <ul>
+         * <li>If the CHIP instance has never been persisted in the current scope, the configuration is
+         *   inherited from lower scopes. If there are no changes either, the properties have their
+         *   default values from the CHIP definition.
+         * <li>When persisting the CHIP instance in a given scope for the first time (may it be due to
+         *   configuration changes or title changes...), the configuration changes are merged with
+         *   inherited changes from lower scopes and persisted in the current scope. Subsequent changes
+         *   in lower scopes will then remain invisible.
+         * <li>A property for which never an update was supplied has the default value from the CHIP
+         *   definition. This also applies if you delete the update again by setting it to
+         *   <code>undefined</code>.
+         * </ul>
+         * <b>Example:</b><br>
+         * The CHIP has two properties: <code>a</code> with default value "foo" and <code>b</code> with
+         * default value "bar". The administrator changes <code>a</code> to "baz" in scope CUST. Later
+         * a user changes <code>b</code> in PERS. Then the administrator decides to change
+         * <code>a</code> back to "foo", but our user will never see this again, because the system
+         * persisted both <code>a</code> and <code>b</code> in PERS.
+         *
+         * @name chip.writeConfiguration.setParameterValues
+         * @function
+         * @since 1.7.0
+         * @param {map<String,String>} mConfigurationUpdates
+         *   The configuration updates. The values must be strings. You can however set a value to
+         *   <code>undefined</code>. This removes it from the list of updated properties and effectively
+         *   resets it to the default value.
+         * @param {function ()} [fnSuccess]
+         *   no-args success handler
+         * @param {function (string, object=)} [fnFailure]
+         *   error handler taking an error message and, since version 1.28.6, an
+         *   optional object containing the complete error information as delivered
+         *   by the ODataService. See fnFailure parameter of {@link sap.ushell_abap.pbServices.ui2.ODataWrapper#onError}
+         *   for more details.
+         *   The default error handler is provided by the page builder
+         */
+        this.setParameterValues = function (mConfigurationUpdates, fnSuccess, fnFailure) {
+            oChipInstance.updateConfiguration(mConfigurationUpdates, fnSuccess, fnFailure);
+        };
+    });
+});

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

@@ -0,0 +1,330 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>configurationUi</code> contract.
+ */
+ sap.ui.define([
+    "sap/ushell_abap/pbServices/ui2/Chip",
+    "sap/ushell_abap/pbServices/ui2/Error"
+], function (
+    Chip,
+    SrvcError
+) {
+    "use strict";
+
+    if (typeof jQuery === "function" && jQuery.sap) {
+        jQuery.sap.declare("sap.ui2.srvc.contracts.configurationUi");
+    }
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>configurationUi</code> contract, which
+     * allows you to provide a CHIP-specific configuration UI with all related functionality.
+     * @name chip.configurationUi
+     * @since 1.11.0
+     */
+
+    Chip.addContract("configurationUi", function (oChipInstance) {
+        var fnCancelHandler,
+            fnDisplayHandler,
+            fnDirtyProvider,
+            bEnabled = false,
+            fnSaveHandler,
+            fnUiProvider;
+
+        /**
+         * Attaches the given event handler to the "cancel" event which is fired whenever the user
+         * chooses to cancel configuration. You can inform the user about unsaved changes by
+         * setting a "dirty" provider.
+         *
+         * 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, it will not be possible to cancel the configuration UI
+         * for this CHIP.
+         *
+         * @name chip.configurationUi.attachCancel
+         * @function
+         * @since 1.11.0
+         * @param {function} fnEventHandler
+         *   event handler for canceling configuration
+         *
+         * @see chip.configurationUi.attachSave
+         * @see chip.configurationUi.setDirtyProvider
+         */
+        this.attachCancel = function (fnEventHandler) {
+            if (typeof fnEventHandler !== "function") {
+                throw new SrvcError("Cancel event handler is not a function",
+                    "chip.configurationUi");
+            }
+            fnCancelHandler = fnEventHandler;
+        };
+
+        /**
+         * Attaches the given event handler to the "save" event which is fired whenever the user
+         * chooses to save the current configuration. The event handler should return a
+         * <code>jQuery.Deferred</code> object's promise to inform the caller whether the save
+         * operation has been successful or not. In the latter case an error message is provided.
+         *
+         * 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, it will not be possible to save configurations for this
+         * CHIP.
+         *
+         * @name chip.configurationUi.attachSave
+         * @function
+         * @since 1.11.0
+         * @param {function} fnEventHandler
+         *   event handler for saving the current configuration; returns a <code>jQuery.Deferred</code>
+         *   object's promise
+         *
+         * @see chip.configurationUi.attachCancel
+         */
+        this.attachSave = function (fnEventHandler) {
+            if (typeof fnEventHandler !== "function") {
+                throw new SrvcError("Save event handler is not a function",
+                    "chip.configurationUi");
+            }
+            fnSaveHandler = fnEventHandler;
+        };
+
+        /**
+         * Inform the embedding application that the user has triggered configuration of this CHIP.
+         * The embedding application will get this CHIP's configuration UI from the callback determined
+         * via <code>chip.configurationUi.setUiProvider()</code> and display it with
+         * additional "save" and "cancel" buttons. If these are pressed, the CHIP instance is informed
+         * via the corresponding "save" and "cancel" events.
+         *
+         * @name chip.configurationUi.display
+         * @function
+         * @since 1.11.0
+         *
+         * @see chip.configurationUi.attachCancel
+         * @see chip.configurationUi.attachSave
+         * @see chip.configurationUi.setUiProvider
+         */
+        this.display = function () {
+            if (fnDisplayHandler) {
+                fnDisplayHandler();
+            }
+        };
+
+        /**
+         * Tells whether configuration of CHIPs is enabled. Note that this value is constant throughout
+         * a CHIP's lifetime. If configuration is enabled, CHIPs should provide a way for the user to
+         * trigger configuration and should not display live data (as administrators will not have the
+         * corresponding permissions). This trigger should then inform the embedding application to
+         * display the configuration UI.
+         *
+         * @name chip.configurationUi.isEnabled
+         * @function
+         * @since 1.11.0
+         * @returns {boolean}
+         *   whether configuration is enabled
+         *
+         * @see chip.configurationUi.display
+         */
+        this.isEnabled = function () {
+            return bEnabled;
+        };
+
+        /**
+         * Tells whether this CHIP is readOnly.
+         * Before calling this method please ensure that it is available.
+         * (Extension of an already existing contract)
+         *
+         * @name chip.configurationUi.isReadOnly
+         * @function
+         * @returns {boolean}
+         *   whether this CHIP instance is readOnly
+         * @since 1.32.0
+         */
+        this.isReadOnly = function () {
+            return oChipInstance.isReadOnly();
+        };
+
+        /**
+         * Determines the callback function which provides the configuration UI's "dirty" state for
+         * this CHIP. The callback has to return a <code>boolean</code> value telling whether this
+         * CHIP's configuration UI is currently in a "dirty" state, i.e. contains unsaved changes.
+         *
+         * An embedding application calls this function each time the user wants to cancel the CHIP's
+         * configuration UI. A confirmation dialog will be presented to the user in case the UI is
+         * "dirty".
+         *
+         * Use <code>Function.prototype.bind()</code> to determine the callback's <code>this</code> or
+         * some of its arguments.
+         *
+         * Note: Without such a callback, it will not be possible to inform the user about unsaved
+         * changes.
+         *
+         * @name chip.configurationUi.setDirtyProvider
+         * @function
+         * @since 1.11.0
+         * @param {function} fnProvider
+         *   a callback which returns a <code>boolean</code> value telling whether this CHIP's
+         *   configuration UI is currently in a "dirty" state
+         *
+         * @see chip.configurationUi.attachCancel
+         */
+        this.setDirtyProvider = function (fnProvider) {
+            fnDirtyProvider = fnProvider;
+        };
+
+        /* eslint-disable valid-jsdoc*/ // &lt; &gt; are confusing eslint
+        /**
+         * Determines the callback function which provides the configuration UI for this CHIP. The
+         * callback has to return an SAPUI5 control (<code>sap.ui.core.Control</code>), which, for
+         * example, can be a view or a component wrapped into a
+         * <code>sap.ui.core.ComponentContainer</code>.
+         *
+         * An embedding application calls this function each time it wants to display the CHIP's
+         * configuration UI. Once the user chooses to save or cancel the configuration, the UI will be
+         * removed from the embedding application's UI, but not destroyed! Use the event handlers for
+         * the corresponding "save" and "cancel" events to clean up the UI as necessary (e.g. destroy
+         * it).
+         *
+         * Use <code>Function.prototype.bind()</code> to determine the callback's <code>this</code> or
+         * some of its arguments.
+         *
+         * Note: Without such a callback, it will not be possible to configure this CHIP.
+         *
+         * @name chip.configurationUi.setUiProvider
+         * @function
+         * @since 1.11.0
+         * @param {function (Object<string,string>)} fnProvider
+         *   a callback which returns an SAPUI5 control (<code>sap.ui.core.Control</code>)
+         *   representing this CHIP's configuration UI.
+         *   Since 1.21.0 an optional parameter map can be passed to the UI provider. This map can be
+         *   used for example to pass default configuration values to the UI.
+         *
+         * @see chip.configurationUi.attachCancel
+         * @see chip.configurationUi.attachSave
+         */
+        this.setUiProvider = function (fnProvider) {
+            fnUiProvider = fnProvider;
+        };
+        /* eslint-enable valid-jsdoc*/
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>configurationUi</code> contract, which allows you to use a CHIP-specific
+         * configuration UI with all related functionality.
+         * @name contract.configurationUi
+         * @since 1.11.0
+         */
+        return {
+            /**
+             * Attaches the given event handler to the "display" event which is fired by the
+             * CHIP instance whenever the user has triggered configuration of this CHIP.
+             *
+             * @param {function} fnEventHandler
+             *   the event handler for the "display" event
+             *
+             * @name contract.configurationUi.attachDisplay
+             * @function
+             * @since 1.11.0
+             *
+             * @see chip.configurationUi.display
+             */
+            attachDisplay: function (fnEventHandler) {
+                if (typeof fnEventHandler !== "function") {
+                    throw new SrvcError("Display event handler is not a function",
+                        "ChipInstance");
+                }
+                fnDisplayHandler = fnEventHandler;
+            },
+
+            /**
+             * Fires the "cancel" event on this CHIP instance's configuration UI.
+             *
+             * @name contract.configurationUi.fireCancel
+             * @function
+             * @since 1.11.0
+             *
+             * @see chip.configurationUi.attachCancel
+             */
+            fireCancel: function () {
+                if (fnCancelHandler) {
+                    fnCancelHandler();
+                }
+            },
+
+            /**
+             * Fires the "save" event on this CHIP instance's configuration UI.
+             *
+             * @returns {object}
+             *   a <code>jQuery.Deferred</code> object's promise as returned by the "save" event handler
+             *
+             * @name contract.configurationUi.fireSave
+             * @function
+             * @since 1.11.0
+             *
+             * @see chip.configurationUi.attachSave
+             */
+            fireSave: function () {
+                return fnSaveHandler ? fnSaveHandler() : undefined;
+            },
+
+            /* eslint-disable valid-jsdoc*/ // &lt; &gt; are confusing eslint
+            /**
+             * Returns this CHIP's configuration UI, if available.
+             *
+             * @param {Object<string,string>} [mParameters]
+             *   Since 1.21.0 an optional parameter map can be passed to the UI provider. This map can be
+             *   used for example to pass default configuration values to the UI.
+             *
+             * @returns {sap.ui.core.Control}
+             *   this CHIP's configuration UI or <code>undefined</code>
+             *
+             * @name contract.configurationUi.getUi
+             * @function
+             * @since 1.11.0
+             *
+             * @see chip.configurationUi.setUiProvider
+             */
+            getUi: function (mParameters) {
+                return fnUiProvider ? fnUiProvider(mParameters) : undefined;
+            },
+            /* eslint-enable valid-jsdoc*/
+
+            /**
+             * Tells whether this CHIP's configuration UI is currently in a "dirty" state (contains
+             * unsaved changes).
+             *
+             * @returns {boolean}
+             *   whether this CHIP's configuration UI is currently in a "dirty" state; returns
+             *   <code>undefined</code> in case the CHIP instance has not set a corresponding provider
+             *   function
+             *
+             * @name contract.configurationUi.isDirty
+             * @function
+             * @since 1.11.0
+             *
+             * @see chip.configurationUi.setDirtyProvider
+             */
+            isDirty: function () {
+                return fnDirtyProvider ? fnDirtyProvider() : undefined;
+            },
+
+            /**
+             * Determines whether this CHIP instance's configuration UI is enabled by the page builder.
+             * <b>Note:</b> Changing this setting after <code>getImplementationAsSapui5()</code> has been
+             * called violates the contract of <code>chip.configurationUi.isEnabled()</code>!
+             *
+             * @param {boolean} bNewEnabled
+             *   whether this CHIP instance's configuration UI is enabled by the page builder
+             *
+             * @name contract.configurationUi.setEnabled
+             * @function
+             * @since 1.11.0
+             *
+             * @see sap.ushell_abap.pbServices.ui2.ChipInstance#getImplementationAsSapui5()
+             * @see chip.configurationUi.isEnabled
+             */
+            setEnabled: function (bNewEnabled) {
+                bEnabled = bNewEnabled;
+            }
+        };
+    });
+});

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

@@ -0,0 +1,70 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>fullscreen</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.fullscreen");
+    }
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>fullscreen</code> contract, which allows you
+     * to deal with toggling of fullscreen mode.
+     * @name chip.fullscreen
+     * @since 1.2.0
+     */
+    Chip.addContract("fullscreen", function (oChipInstance) {
+        /**
+         * Tells whether fullscreen mode is currently turned on.
+         *
+         * @name chip.fullscreen.getFullscreen
+         * @function
+         * @since 1.2.0
+         * @returns {boolean}
+         *   whether fullscreen mode is turned on
+         */
+        this.getFullscreen = function () {
+            return oChipInstance.getFullscreen();
+        };
+
+        /**
+         * Turns fullscreen mode on as specified.
+         *
+         * @name chip.fullscreen.setFullscreen
+         * @function
+         * @since 1.2.0
+         * @param {boolean} bOn
+         *   whether fullscreen mode is turned on
+         */
+        this.setFullscreen = function (bOn) {
+            oChipInstance.setFullscreen(bOn);
+        };
+
+        /**
+         * Attaches the given event handler to the "fullscreen" event which is fired
+         * whenever fullscreen mode is toggled.
+         *
+         * 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 simply continue to display the
+         * same content, no matter whether fullscreen mode is on or off.
+         *
+         * @name chip.fullscreen.attachFullscreen
+         * @function
+         * @since 1.2.0
+         * @param {function} fnEventHandler
+         *   the event handler for the "fullscreen" event
+         */
+        this.attachFullscreen = function (fnEventHandler) {
+            oChipInstance.attachFullscreen(fnEventHandler);
+        };
+    });
+});

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

@@ -0,0 +1,50 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>navigation</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.navigation");
+    }
+
+    var oNavigationHandle;
+    if (typeof sap.ui2.shell === "object"
+        && typeof sap.ui2.shell.getNavigationHandle === "function") {
+        oNavigationHandle = sap.ui2.shell.getNavigationHandle();
+        if (typeof oNavigationHandle === "object"
+            && typeof oNavigationHandle.navigateToUrl === "function") {
+            /**
+             * @namespace The namespace for the CHIP API's <code>navigation</code> contract, which allows
+             * you to navigate to a launchpad URL in a surrounding shell.
+             * @name chip.navigation
+             * @since 1.2.0
+             */
+
+            Chip.addContract("navigation", function (oChipInstance) {
+                /**
+                 * Navigates to the given URL using the optional settings.
+                 *
+                 * @name chip.navigation.navigateToUrl
+                 * @function
+                 * @since 1.2.0
+                 * @param {string} sUrl
+                 *   the URL to navigate to
+                 * @param {object} [oSettings]
+                 *   the settings
+                 *
+                 * @see <code>sap.ui2.shell.getNavigationHandle().navigateToUrl()<code>
+                 */
+                this.navigateToUrl = function (sUrl, oSettings) {
+                    oNavigationHandle.navigateToUrl.apply(oNavigationHandle, arguments);
+                };
+            });
+        }
+    }
+});