@sapui5/sap.ushell_abap 1.94.1 → 1.97.0

package/src/main/js/sap/ushell_abap/pbServices/ui2/chipdefinition.xsd

@@ -0,0 +1,139 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- ${copyright} -->
+<xs:schema xmlns="http://schemas.sap.com/sapui2/services/Chip/1"
+           xmlns:xs="http://www.w3.org/2001/XMLSchema"
+           targetNamespace="http://schemas.sap.com/sapui2/services/Chip/1"
+           elementFormDefault="qualified">
+
+    <xs:element name="chip" type="ChipDescription"/>
+
+    <xs:complexType name="ChipDescription">
+        <xs:sequence>
+            <xs:element name="implementation" type="Implementation" maxOccurs="1" minOccurs="1"/>
+            <xs:element name="appearance" type="Appearance" maxOccurs="1" minOccurs="0"/>
+            <xs:element name="sources" type="Sources" maxOccurs="1" minOccurs="0"/>
+            <xs:element name="propertyPaths" type="PropertyPaths" maxOccurs="1" minOccurs="0"/>
+            <xs:element name="contracts" type="Contracts" maxOccurs="1" minOccurs="0"/>
+            <xs:element name="parameters" type="ParameterList" maxOccurs="1" minOccurs="0"/>
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="Implementation">
+        <xs:choice minOccurs="1" maxOccurs="1">
+            <xs:element name="sapui5" type="SAPUI5ChipImplementation"/>
+        </xs:choice>
+    </xs:complexType>
+
+    <xs:complexType name="ChipImplementation" abstract="true">
+    </xs:complexType>
+
+    <xs:complexType name="SAPUI5ChipImplementation">
+        <xs:complexContent>
+            <xs:extension base="ChipImplementation">
+                <xs:sequence>
+                    <xs:element name="basePath" type="xs:string" maxOccurs="1" minOccurs="0" default="."/>
+                    <xs:choice minOccurs="1" maxOccurs="1">
+                        <xs:element name="componentName" type="ComponentName"/>
+                        <xs:element name="viewName" type="ViewName"/>
+                    </xs:choice>
+                </xs:sequence>
+            </xs:extension>
+        </xs:complexContent>
+    </xs:complexType>
+
+    <xs:complexType name="ComponentName">
+        <xs:sequence>
+            <xs:element name="componentName" type="xs:string" maxOccurs="1" minOccurs="0"/>
+        </xs:sequence>
+        <xs:attribute name="virtualNamespace" type="xs:boolean"/>
+    </xs:complexType>
+
+    <xs:complexType name="ViewName">
+        <xs:sequence>
+            <xs:element name="viewName" type="xs:string" maxOccurs="1" minOccurs="0"/>
+        </xs:sequence>
+        <xs:attribute name="virtualNamespace" type="xs:boolean"/>
+    </xs:complexType>
+
+    <xs:complexType name="Sources">
+        <xs:sequence>
+            <!-- the limit of 999 is arbitrary, but "unbounded" isn't accepted by Fortify -->
+            <xs:element name="source" type="Source" maxOccurs="999" minOccurs="0"/>
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="Source">
+        <xs:sequence>
+            <xs:element name="location" type="xs:string" maxOccurs="1" minOccurs="1"/>
+            <xs:element name="base" type="xs:string" maxOccurs="1" minOccurs="1"/>
+        </xs:sequence>
+        <xs:attribute name="id" type="xs:string" use="required"/>
+    </xs:complexType>
+
+    <xs:complexType name="PropertyPaths">
+        <xs:sequence>
+            <!-- the limit of 999 is arbitrary, but "unbounded" isn't accepted by Fortify -->
+            <xs:element name="properties" type="Properties" maxOccurs="999" minOccurs="0"/>
+        </xs:sequence>
+        <xs:attribute name="source" type="xs:string"/>
+    </xs:complexType>
+
+    <xs:complexType name="Properties">
+        <xs:sequence>
+            <!-- the limit of 999 is arbitrary, but "unbounded" isn't accepted by Fortify -->
+            <xs:element name="property" type="Property" maxOccurs="999" minOccurs="0"/>
+        </xs:sequence>
+        <xs:attribute name="usage" type="xs:string" use="required"/>
+        <xs:attribute name="source" type="xs:string"/>
+    </xs:complexType>
+
+    <xs:complexType name="Property">
+        <xs:simpleContent>
+            <xs:extension base="xs:string">
+                <xs:attribute name="name" type="xs:string" use="required"/>
+                <xs:attribute name="source" type="xs:string"/>
+                <xs:attribute name="initialvalue" type="xs:string"/>
+                <xs:attribute name="true" type="xs:string"/>
+                <xs:attribute name="false" type="xs:string"/>
+            </xs:extension>
+        </xs:simpleContent>
+    </xs:complexType>
+
+    <xs:complexType name="Appearance">
+        <xs:sequence>
+            <xs:element name="title" type="xs:string" maxOccurs="1" minOccurs="0"/>
+            <xs:element name="description" type="xs:string" maxOccurs="1" minOccurs="0"/>
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="Contracts">
+        <xs:sequence>
+            <!-- the limit of 100 is arbitrary, but "unbounded" isn't accepted by Fortify -->
+            <!-- "100 contracts should be enough for every CHIP." :-) -->
+            <xs:element name="consume" type="ConsumedContractInfo" maxOccurs="100" minOccurs="0"/>
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="ConsumedContractInfo">
+        <xs:sequence>
+            <xs:element name="parameters" type="ParameterList" maxOccurs="1" minOccurs="0"/>
+        </xs:sequence>
+        <xs:attribute name="id" type="xs:string" use="required"/>
+    </xs:complexType>
+
+    <xs:complexType name="ParameterList">
+        <xs:sequence>
+            <!-- the limit of 100 is arbitrary, but "unbounded" isn't accepted by Fortify -->
+            <xs:element name="parameter" type="Parameter" maxOccurs="100" minOccurs="1"/>
+        </xs:sequence>
+    </xs:complexType>
+
+    <xs:complexType name="Parameter">
+        <xs:simpleContent>
+            <xs:extension base="xs:string">
+                <xs:attribute name="name" type="xs:string" use="required"/>
+            </xs:extension>
+        </xs:simpleContent>
+    </xs:complexType>
+
+</xs:schema>

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

@@ -0,0 +1,244 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>actions</code> contract.
+ *               since 1.32 the <code>types</code> contract.
+ */
+sap.ui.define([
+    "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.actions");
+        jQuery.sap.declare("sap.ui2.srvc.contracts.types");
+    }
+
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>actions</code> contract, which
+     * allows you to provide a CHIP's actions with all related functionality.
+     * @name chip.actions
+     * @since 1.25.0
+     */
+    Chip.addContract("actions", function (oChipInstance) {
+        var fnActionsProvider;
+
+        /**
+         * Determines the callback function which provides the internal actions for this CHIP. The
+         * callback has to return an array of actions. Action is an object with the following
+         * properties: text, icon and targetURL or a press handler.
+         * @example:
+         * <code>[
+         *        {
+         *            text: "Some Action",
+         *            icon: "sap-icon://action",
+         *            targetURL: "#SemanticObject-Action"
+         *        },
+         *        {
+         *            text: "Settings",
+         *            icon: "sap-icon://action-settings",
+         *            press: function (oEvent){
+         *                //Open settings UI
+         *            }
+         *        }
+         *       ]
+         * </code>.
+         *
+         * An embedding application calls this function each time it wants to display the CHIP's
+         * actions.
+         *
+         * Use <code>Function.prototype.bind()</code> to determine the callback's <code>this</code> or
+         * some of its arguments.
+         *
+         * @name chip.actions.setActionsProvider
+         * @function
+         * @since 1.25.0
+         * @param {function} fnProvider
+         *   a callback which returns an array of action objects representing this CHIP's internal actions.
+         */
+        this.setActionsProvider = function (fnProvider) {
+            if (typeof fnProvider !== "function") {
+                throw new SrvcError("CHIP actions provider is not a function", "chip.actions");
+            }
+            fnActionsProvider = fnProvider;
+        };
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>actions</code> contract, which allows you to get a CHIP's actions with all related functionality.
+         * @name contract.actions
+         * @since 1.25.0
+         */
+        return {
+            /**
+             * Returns this CHIP's internal actions, if available.
+             *
+             * @returns {Array}
+             *   this CHIP's internal actions array
+             *
+             * @name contract.actions.getActions
+             * @function
+             * @since 1.25.0
+             *
+             * @see chip.actions.setActionsProvider
+             */
+            getActions: function () {
+                if (fnActionsProvider) {
+                    return fnActionsProvider();
+                }
+                return [];
+            }
+        };
+    });
+
+    // the "contracts" mechanism requires a host to provide the functionality
+    // (it is not "optional")
+    // When the EP uses the ABAP JS sources, the contract should be made available.
+    // thus we make the contract available in this *file* to avoid
+    // having to have a separate script tag within the EP resource
+    // (note that contracts due to ancient design can not be required)
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>types</code> contract, which allows the CHIP
+     * to offer multiple visualizations from which the page builder can choose.
+     * @name chip.types
+     * @since 1.32.0
+     */
+    Chip.addContract("types", function (oChipInstance) {
+        var sCurrentType,
+            fnSetTypeHandler;
+
+        /**
+         * Attaches the given event handler to the change event which is fired whenever the page builder
+         * wants to change the current type of visualization. The CHIP has to react accordingly and
+         * change the visualization after the handler is called. The event handler should return a
+         * <code>jQuery.Deferred</code> object's promise to inform the caller whether the visualization
+         * has been changed (or failed). In the latter case an error message should be provided.
+         * In case the type was changed before the handler was attached, the handler gets called
+         * immediately after registration. This also works when the handler is overwritten by a
+         * different one.
+         *
+         * 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 change the visualization of
+         * the CHIP during runtime.
+         *
+         * @name chip.types.attachTypeChange
+         * @function
+         *
+         * @param {function (string)} fnHandler
+         *   the handler for changing the visualization type of the CHIP. The first argument will be
+         *   the set type. The function <b>must</b> return a <code>jQuery.Deferred</code>
+         *   object's promise.
+         *
+         * @throws Error if <code>fnHandler</code> is not a function or if fnHandler.
+         * @throws If fnHandler is directly called (because a type was cached) and throws an error.
+         *
+         * @since 1.32.0
+         * @see contract.types.setType
+         * @see chip.types.getAvailableTypes
+         */
+        this.attachSetType = function (fnHandler) {
+            if (typeof fnHandler !== "function") {
+                throw new SrvcError("Change event handler is not a function",
+                    "chip.types");
+            }
+            if (fnSetTypeHandler === fnHandler) {
+                // nothing to do, especially do not call the handler again (assumption: better performance)
+                return;
+            }
+            fnSetTypeHandler = fnHandler;
+
+            // a type was already set, so fire the new handler directly
+            if (sCurrentType) {
+                // do not catch errors here -> fail early (the CHIP throws the error so it has to catch it)
+                fnSetTypeHandler(sCurrentType);
+            }
+        };
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>types</code> contract, which allows you to change the CHIP's type of visualization.
+         * @name contract.types
+         * @since 1.32.0
+         */
+        return { // contract
+            /**
+             * Returns the list of available types of visualization. The types are always lower case.
+             *
+             * @name chip.types.getAvailableTypes
+             * @function
+             * @returns {string[]}
+             *   the available tile types in lower case, e.g. <code>["tile", "link"]</code>
+             * @since 1.32.0
+             */
+            getAvailableTypes: function () {
+                // note: getAvailableTypes does a toLowerCase
+                return oChipInstance.getChip().getAvailableTypes();
+            },
+
+            /**
+             * Returns the default visualization type of the chip instance
+             *
+             * @returns {string}
+             *  The default visualization type
+             *
+             * @since 1.86.0
+             */
+            getDefaultType: function () {
+                return oChipInstance.getChip().getDefaultType();
+            },
+            /**
+             * Informs the CHIP to change it's visualization type to <code>sType</code>. In case the CHIP
+             * has not attached an handler for this event yet, the contract will call the handler directly
+             * while attaching it.
+             *
+             * @param {string} sType
+             *   The type to be set.
+             *   Note: Before comparison <code>sType.toLowerCase()</code> will be used.
+             *
+             * @throws Error if <code>sType</code> is not valid.
+             *
+             * @name contract.types.setType
+             * @function
+             * @since 1.32.0
+             *
+             * @see chip.types.attachSetType
+             * @see chip.types.getAvailableTypes
+             */
+            setType: function (sType) {
+                var sTypeLowerCase;
+                if (typeof sType !== "string" || sType === "") {
+                    throw new SrvcError("The given type is not a string",
+                        "contract.types");
+                }
+                sTypeLowerCase = sType.toLowerCase();
+                if (this.getAvailableTypes().indexOf(sTypeLowerCase) < 0) {
+                    throw new SrvcError("The CHIP does not support type '" + sTypeLowerCase + "'",
+                        "contract.types");
+                }
+
+                // type is valid. cache it in case a (new) handler is registered
+                sCurrentType = sTypeLowerCase;
+
+                if (!fnSetTypeHandler) {
+                    return;
+                }
+                try {
+                    fnSetTypeHandler(sTypeLowerCase);
+                } catch (e) {
+                    Log.error("Could not set CHIP type '" + sTypeLowerCase + "': "
+                        + (e.message || e.toString()), null, "chip.types");
+                }
+            }
+        };
+    });
+});

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

@@ -0,0 +1,150 @@
+// Copyright (c) 2009-2021 SAP SE. All rights reserved.
+
+/**
+ * @fileOverview The <code>bag</code> contract.
+ */
+sap.ui.define([
+    "sap/ushell_abap/pbServices/ui2/Chip",
+    "sap/ushell_abap/pbServices/ui2/Utils",
+    "sap/ushell_abap/pbServices/ui2/Error"
+], function (
+    Chip,
+    Utils,
+    SrvcError
+) {
+    "use strict";
+
+    if (typeof jQuery === "function" && jQuery.sap) {
+        jQuery.sap.declare("sap.ui2.srvc.contracts.bag");
+    }
+
+    /**
+     * @namespace The namespace for the CHIP API's <code>bag</code> contract, which allows you to
+     * access property bags attached to a CHIP instance and read or write properties in these bags.
+     * @name chip.bag
+     * @since 1.5.0
+     */
+
+    Chip.addContract("bag", function (oChipInstance) {
+        var fnBagsUpdatedHandler;
+        /**
+         * Returns the associated property bag for a given ID. If no bag with the given ID exists, a
+         * new, empty bag is created on the fly.
+         *
+         * @name chip.bag.getBag
+         * @function
+         * @since 1.5.0
+         * @param {string} sBagId
+         *   The ID of the bag to be returned
+         * @returns {sap.ushell_abap.pbServices.ui2.Bag}
+         *   The associated bag
+         */
+        this.getBag = function (sBagId) {
+            return oChipInstance.getBag(sBagId);
+        };
+
+        /**
+         * Returns an array of IDs of all associated property bags which currently exist.
+         * Note that new bags are created on the fly if you call <code>getBag</code> with any other ID.
+         *
+         * @name chip.bag.getBagIds
+         * @function
+         * @since 1.5.0
+         * @returns {string[]}
+         *   IDs of associated bags
+         */
+        this.getBagIds = function () {
+            return oChipInstance.getBagIds();
+        };
+
+        /**
+         * Returns this CHIP instance's original language as BCP-47.
+         * If you are logged on in the same language or if the original language is empty, translatable
+         * texts can be created and modified for this CHIP instance and its bags.
+         * See {@link sap.ushell_abap.pbServices.ui2.Bag#setText}.
+         * <p>
+         * Note: Handling of translatable texts depends on the layer used. In some layers the original
+         * language is important; in others it does not matter. In the latter case the empty string
+         * (<code>""</code>) is returned, which indicates that the user is allowed to edit the
+         * translatable texts in any language.
+         * <p>
+         * The following code is a flexible way of checking the current situation without knowing the
+         * current language or layer:
+         * <pre>
+         *  if (oChipInstance.getOriginalLanguage() === "" || oChipInstance.getOriginalLanguage() ===
+         *      sap.ui.getCore().getConfiguration().getLanguage()) {
+         *    // create and modify the CHIP instance's texts
+         *  }
+         * </pre>
+         * <p>
+         *
+         * @name chip.bag.getOriginalLanguage
+         * @function
+         * @returns {string}
+         *   this CHIP instance's original language (BCP-47) or <code>""</code>
+         * @since 1.17.1
+         */
+        this.getOriginalLanguage = function () {
+            return oChipInstance.getPage() && oChipInstance.getPage().getOriginalLanguage();
+        };
+
+        /**
+         * 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 bag
+         * data of the CHIP and is able to notify the CHIP Instance what bag(s) have been updated,
+         * so the CHIP instance can update the view.
+         *
+         * Note: The event must be explicitly triggered by the Page Builder. There is no automatic mechanism.
+         *
+         * @name chip.bag.attachBagsUpdated
+         * @function
+         * @param {function(string[])} fnHandler
+         *   Handler which is called if the Page Builder updates one or multiple related bags. The
+         *   receives as first parameter an array containing all the IDs of the updated bags
+         * @since 1.34.0
+         * @private
+         * @see contract.bag.fireBagsUpdated
+         */
+        this.attachBagsUpdated = function (fnHandler) {
+            // Back channel for FLP bookmark tiles, as they are managed by the FLP Bookmark Service.
+            // The FLP directly changes the bag data of the bookmark tile and can notify the bookmark
+            // tiles afterwards about the changes, so the bookmark tiles can update their views with
+            // the new bag data
+            if (typeof fnHandler !== "function") {
+                throw new SrvcError("The given handler is not a function", "chip.bag");
+            }
+            fnBagsUpdatedHandler = fnHandler;
+        };
+
+        /**
+         * @namespace The namespace for the contract interface (to be used by a page builder) for
+         * the <code>bag</code> contract.
+         * @name contract.bag
+         * @private
+         */
+        return { // contract - private as only used by Fiori Launchpad
+            /**
+             * Allows the page builder to inform the CHIP about changes in certain bags.
+             * Note: Usually the page builder should not care about the content of the bags; however, for bookmark tiles
+             * in the Fiori Launchpad this is required as the Fiori Launchpad manages them.
+             *
+             * @name contract.bag.fireBagsUpdated
+             * @function
+             * @param {string[]} aUpdatedBagIds
+             *   array of bag IDs which have been updated by the page builder
+             * @since 1.34.0
+             * @private
+             * @see chip.bag.attachBagsUpdated
+             */
+            fireBagsUpdated: function (aUpdatedBagIds) {
+                if (!Utils.isArray(aUpdatedBagIds) || aUpdatedBagIds.length < 1) {
+                    throw new SrvcError("At least one bag ID must be given", "contract.bag");
+                }
+                if (fnBagsUpdatedHandler) {
+                    fnBagsUpdatedHandler(aUpdatedBagIds);
+                }
+            }
+        };
+    });
+});