Create a UI5 Integration Card that Displays Data from the SAP Gateway Demo System
- How to create a card for SAP Build Work Zone using SAP Business Application Studio (BAS)
- What the main elements of the Integration card are and understand their roles
Prerequisites
- Please note that if you are following this tutorial as part of a workshop, you can skip these prerequisites.
- You have an account on the SAP Gateway Demo System. See Create an Account on the SAP Gateway Demo System.
- You have connected the SAP BTP to your SAP Gateway Demo System Account. See Connect SAP BTP to Your SAP Gateway Demo System Account (ES5).
- You have created a dev space. See Create a Dev Space for SAP Fiori Apps.
- To deploy a UI5 Integration card in the SAP Build Work Zone, you should have a subaccount in SAP BTP that includes a subscription to the SAP Build Work Zone service. Additionally, you have to configure a destination for SAP Build Work Zone instance See Creating a Destination to the Content Repository.
IMPORTANT: SAP Build Work Zone is not available in a trial account. If you only have a trial account and you want to learn more about the Integration cards you can follow this tutorial from steps 1 to 5.
Integration cards are UI elements which display concise pieces of information in a limited-space container. Cards are small previews of application content, and each card represents a specific topic, task, or perspective. As a card developer, you only need to configure a descriptor (manifest.json
file) and as a result you get fully functional and reusable card.
- Step 1
If you are following this tutorial as part of a workshop, please skip this step.
In SAP Business Application Studio, stop the dev space if it is not already stopped.
Edit the dev space by selecting the Edit button.
Ensure that the Development Tools for SAP Build Work Zone extension is checked and save the changes.
Log in to complete tutorial - Step 2
Open the dev space (If the dev space is not running, you first have to start it).
Select Start from template.
Choose the UI Integration Card template and select Start.
Fill-in the required project details. Use the Highlight Card template, which creates an Integration card of type List and select Finish.
If you are following this tutorial as part of a workshop, please give your card a unique name. Your card name should be
#uid_products_by_category_card
where#uid
is your unique identifier.Description Value Project Name products_by_category_card
If you’re taking part in a workshop, please add your unique identifier to the project name like this:<your unique identifier>_products_by_category_card
.Name Space ns
Select a Card Sample (dropdown menu) Highlight Card
Title Products by Category Card
Subtitle UI5 Integration Card of Type List
Compatible with SAP Mobile Cards (dropdown menu) False
To see the card, right-click on
manifest.json
and select UI Integration Card: Preview.Currently the card displays only static data:
Open the
manifest.json
file. Everything needed to render the card is described in this file.The
manifest.json
is a simple JSON file and has the following structure (check the picture below to see where each part is located):sap.app
namespace declaration. Thetype: card
defines that this is a manifest for a card. Each card has a unique ID.sap.card
section:- Card type (List): Defines how the card is displayed. It could be one of the available content types - Adaptive, Component, Analytical, List, etc.
- Header: Displays general information about the card. Using its properties, you can configure the title, subtitle, status text, and icon.
- Content: This is the main section of the displayed card.
- Card type (List): Defines how the card is displayed. It could be one of the available content types - Adaptive, Component, Analytical, List, etc.
data
sections: Define how the card handles its data. It can provide static data (see thejson
object below) or define required parameters for a data request to a backend system. Can be set on different levels (card, header, filter-definition, or content). The inner level data sections take precedence. In the example below the data section is defined on content level.
In the next steps you edit the
manifest.json
file to configure the card.Log in to complete tutorial - Step 3
By connecting your card to the SAP Gateway Demo System (ES5), you’re enabling the card to display dynamic data. Card destinations are used for outbound communication to a remote resource and contain the required connection information.
-
To set a destination, add the following
configuration
section in thesap.card
section after thetype
subsection. Note, that the card destination is pointing to the same (ES5) destination that is set on the subaccount level.JSONCopy"configuration": { "destinations": { "ES5": { "name": "ES5", "defaultUrl": "/sap/opu/odata/sap/EPM_REF_APPS_SHOP_SRV/" } } },
-
To configure a data request pointing to the SAP Gateway Demo System, add a new
data
section after theconfiguration
. In this way thedata
section will be defined on a card level. Note, that our destination is referred here using the double-bracket syntax{{destinations.ES5}}
.JSONCopy"data": { "request": { "url": "{{destinations.ES5}}/sap/opu/odata/sap/EPM_REF_APPS_SHOP_SRV/Products", "withCredentials": true }, "path": "/d/results" },
-
To display the dynamically requested data, replace the static
content
section with the following one. Thetitle
,description
,icon
, andinfo
properties are now dynamically requested.JSONCopy"content": { "item": { "title": "{Name}", "description": "{Description}", "icon": { "src": "{ImageUrl}" }, "info": { "value": "{AverageRating}", "state": "{= ${AverageRating} > 3.5 ? 'Success' : 'Warning' }" } }, "maxItems": 5 }
Results after Step 3:
The application displays dynamic data loaded from the SAP Gateway Demo System (ES5). Note, that the actual displayed products may differ depending on the current data in the ES5 demo system. You can also check the manifest.json file at this step. To learn more, see the Destinations and Data sections in the Card Explorer.
If you would like to deploy the card and see how it looks on SAP Build Work Zone, you can skip to Step 6 and deploy it. In the next steps you add card capabilities that can make your card more interactive.
Log in to complete tutorial -
- Step 4
Manifest parameters provide dynamic values for card attributes. They are replaced during manifest processing and can be used with the double-bracket syntax like:
{{parameters.city}}
. As an example, in this step you will add parameters to set the header (title
andsubTitle
) properties and the number (maxItems
) of displayed items in the content.If you are following this tutorial as part of a workshop and run out of time, you can skip steps 4,5,6 and create a simpler card. You can later read the steps you missed.
-
To define parameters - add the following
parameters
subsection in themanifest.json
in theconfiguration
section (note the comma which divides the entries).JSONCopy, "parameters": { "title" : { "value": "List Card with Top {{parameters.maxItems}} Products" }, "subTitle": { "value": "These are the top sellers this month" }, "maxItems": { "value": 4 } }
-
To use the new
maxItems
parameter, replace themaxItems: 5
static value in thecontent
section with the (maxItems
) parameter as shown below:JSONCopy"maxItems": "{{parameters.maxItems}}"
-
Let’s also use the new parameters in the
header
section. Use the double-bracket syntax and edit (or replace) the header, so it looks like this:JSONCopy"header": { "title": "{{parameters.title}}", "subTitle": "{{parameters.subTitle}}", "icon": { "src": "sap-icon://desktop-mobile" }, "status": { "text": "{{parameters.maxItems}} of 20" } },
Results after Step 4:
In this step you have learned how to declare configurable parameters and use them to achieve desired dynamic behavior. The application now displays a list of 4 items according to the
parameters
property (maxItems value: 4
).To learn more, see the Manifest Parameters section in the Card Explorer.
Log in to complete tutorial -
- Step 5
You can make the card even more dynamic when using filters. Filters appear as a dropdown under the card header, and users can interact to customize the data shown by the card. The value of each filter can be used inside a data request definition by using the
{filters>/myFilter/value}
placeholder. When the end user selects different value from the dropdown - a new data request is made with the updated value. As an example, in this step you will add a filter that enables users to filter products by a selected category.-
Add a
filters
subsection in theconfiguration
section. It defines a dropdown list with product categories, which are received by a data request.JSONCopy, "filters": { "mainCategory": { "value": "{{parameters.selectedCategoryName}}", "type": "string", "label": "Main Category", "description": "Filter products by main category.", "item": { "path": "/d/results", "template": { "key": "{Id}", "title": "{Name}" } }, "data": { "request": { "url": "{{destinations.ES5}}/sap/opu/odata/sap/EPM_REF_APPS_SHOP_SRV/MainCategories", "withCredentials": true } } } }
-
Add
selectedCategoryName
subsection in theparameters
section. This is the category that is initially selected in the filter. Later, the user can change it from the dropdown list.JSONCopy, "selectedCategoryName": { "value": "Computer Systems" }
-
Add
parameters
in the maindata
section >request
subsection, after theurl
property as shown below. The$filter
parameter will be used in a data request for the category withMainCategoryName
that is equal to the one selected by the user in the filter’s dropdown list.JSONCopy"parameters": { "$filter": "MainCategoryName eq '{filters>/mainCategory/value}'" },
-
Finally replace the title in the
header
adding the{filters>/supplier/selectedItem/title}
parameter, which will show the selected category:JSONCopy"title": "Products filtered by {filters>/mainCategory/selectedItem/title} category",
Results after Step 5:
If you have any issues you can check the manifest.json file at this step. It is configured with destinations, parameters, and a filter.
The application displays the products from the selected category:
IMPORTANT: Due to an issue with the UI Integration Card: Preview option, it may not be able to correctly display the products that are filtered!
To learn more, see the Filters section in the Card Explorer.
Log in to complete tutorial -
- Step 6
Select the
dt/configuration.js
file (in the Explorer view on the left).Replace the content with the code below:
JSONCopysap.ui.define(["sap/ui/integration/Designtime"], function ( Designtime ) { "use strict"; return function () { return new Designtime({ "form": { "items": { "maxItems": { "manifestpath": "/sap.card/configuration/parameters/maxItems/value", "type": "integer", "label": "Maximum Items", "translatable": false, "description": "Defines how many items will be displayed at most." } } }, "preview": { "modes": "LiveAbstract" } }); }; });
The
dt/configuration.js
now looks like:Log in to complete tutorial - Step 7
-
Right-click on the
manifest.json
file (in the Explorer view on the left) and select the UI Integration Card:Deploy to SAP Build Work Zone option from the dropdown menu. -
Select the target SAP Build Work Zone destination.
-
In the right-bottom corner, confirm to Continue and wait to see the successful message.
Now the basic UI5 card deployment is done!
To learn more about the Integration cards and their functionalities, see the Card Explorer page.
In which parts (sections) of the card you can define a Data section? Only one option is correct.
Log in to complete tutorial -