Getting started with UI Integration Cards

Introduction

I was scrolling through my Facebook newsfeed the other day and I happened to notice how so much information is neatly arranged and displayed with the help of cards. Each card is different and has its own properties. Images, text, maps, etc. all combined into one piece of the card looks nothing less beautiful than the mouth-watering dish served at the finest restaurants in which individual items are arranged on the plate in a specific way that makes the dish look appetizing. Then the next card comes up with another set of information – this too beautifully presented.

Not only Facebook but there are also so many other applications in the market that makes use of card design. SAP has also adopted the card design in many applications. The most prominent being the Overview Page Layout which makes use of cards. Another such application of card design in SAP applications is SAP UI Integration Cards. SAP UI Integration Cards offers a way in which we can present our app content using cards without any need to write any UI code for the cards. In this blog post, I shall demonstrate how to use integration cards in a simple UI5 application developed in SAP Business Application Studio.

Sample cards

Benefits of using cards

We can all say that nowadays cards are widely used across mobile and website app UIs. There are many reasons for it.

1. Card designs are minimalistic – simple, aesthetically pleasing, and intuitive. This improves the user’s comprehension of a website or content.
2. They can be used to build responsive websites – no matter which device you are on – the cards resize on their own and you can see all your content neatly presented.
3. Card UI designs are scannable. They can be used to display just a birds-eye view of the entire content to the user. For eg. Headlines of news. Once the user clicks on the card, it navigates to the detailed page.
4. Cards are user-friendly. They can easily figure out how to use the cards and achieve their purpose. They are naturally intuitive as they represent physical cards with units of information.

SAP UI Integration Cards

Integration cards provide a way to expose application content to the end-user in a unified way. Depending on the scenario cards can be embedded in a host environment – such as an application, dashboard, or any HTML page. A variety of card types can be configured by a simple JSON configuration without the need to write a single line of code for UI rendering. Thus, users without programming skills can also create new cards and make use of them as per their needs.

How this works?

The card developer has written all the UI-related code for a general template card which can be configured in a variety of flexible ways depending on the scenario.

The host developer can simply configure and use these cards developed by the card developer without the need of developing the card from scratch. This really speeds up the application development and the host developer can focus more on the problem statement. When we make use of integration cards, we are the host developer in this scenario.

Card Developer vs Host Developer

Using Integration Cards in UI5 app

Now, I shall demonstrate how to configure a single integration cards and use them in our UI5 application.

Step 1: Create a UI5 project in  SAP Business Application Studio

Start your Dev Space in SAP Business Application Studio and launch the generator to create a UI5 application

Floorplan Selection

For this demo, I shall directly define my JSON Data when configuring the card so I am selecting Data Source as “None”.

Data Source

Enter a View Name for the UI5 application

View Name

Provide necessary project details. Click on Finish.

Project Details

The project is created.

Project is created

Step 2: Configure your card by creating a manifest file

In order to use our card in the app, first, we need to configure it by creating a manifest file for the card in JSON format. Do not confuse this with the manifest.json file for our UI5 application which provides the necessary settings and configuration for our app. Create a new file by right-clicking on webapp folder > New File. Give a name to this file. As we may have multiple cards on our application let’s number them or give some unique description to it.

Create a manifest file for your card

There are many card types available to choose from. Please refer to this link to see the available card types: Card Types

For this demo, I shall demonstrate how to use a List Card so we shall create our manifest file for the card accordingly. I will write the below code in the file that we have just created.

{
	"sap.app": {
		"id": "my.new.card",
		"type": "card",
		"applicationVersion": {
		  "version": "1.0.0"
		}
	},
	"sap.card": {
        "type": "List",
        "header": {
			"title": "My Reading List",
			"subTitle": "Books I would love to read",
			"icon": {
				"src": "sap-icon://education"
            },
            "actions": [
				{
					"type": "Navigation",
					"url": "https://www.goodreads.com/"
				}
            ]
            
        },
        "content": {
			"data": {
				"json": [
					{
						"Name": "Harry Potter and the Deathly Hallows",
                        "Author": "JK Rowling"
					},
					{
						"Name": "The Lord of the Rings",
						"Author": "J.R.R Tolkien"
					},
					{
						"Name": "The Alchemist",
						"Author": "Paulo Coelho"
					}
				]
			},
			"item": {
				"title": {
					"value": "{Name}"
				},
				"description": {
					"value": "{Author}"
                }
            }
        }
	}
}

Few important things to note in the above piece of code :

1. In sap.app property, the type is card. Unlike sap.app property of our application manifest.json file where type is application.
2. As I am trying to create a List Card, the type property of sap.card is set to List.
3. sap.card > header property is responsible fo the content to be displayed in Header section of the card.
4. sap.card > content property is responsible for the Content section of the card.
5. actions property is used for navigation purposes. For eg. I have written a code to navigate to Goodreads website once I click on the header area.

Step 3: Embedding the card in our application view

In order to embed the card in our application view, we have to write the below piece of code inside the content area.

<mvc:View
    controllerName="carddemo.controller.View1"
    xmlns:mvc="sap.ui.core.mvc"
    displayBlock="true"
    xmlns="sap.m"
    xmlns:w="sap.ui.integration.widgets"
>
	<Shell id="shell">
		<App id="app">
			<pages>
				<Page id="page" title="{i18n>title}">
					<content>
                     <w:Card manifest="./manifest_card1.json" width="25%"/>
                    </content>
				</Page>
			</pages>
		</App>
	</Shell>
</mvc:View>

Few important things to note in the above piece of code :

1. We have to make use of library sap.ui.integration.widgets. 
2. While using the Card element, we have to mention the path of our card manifest file for the manifest property.
3. We can assign a width to our card as per our requirements.

Step 4: Running our application

So now let’s test our application and check how it looks. After running our application, we see the below results in the browser.

App Preview

So we can see that our card is embedded in our UI5 application and we can see the header and content area of the card. Let’s check the Navigation functionality. If I click on the header area of the card, another tab opens up and the GoodReads website opens.

GoodReads website

Conclusion

So in this way we have achieved the purpose of our development.

There are many other samples to test and try out in the following link: Developing Cards

I shall try explaining a few advanced scenarios in my upcoming blog posts.

Please stay tuned 🙂

References

Images

Sample Cards – https://openui5nightly.hana.ondemand.com/

Card Developer vs Host Developer – https://openui5nightly.hana.ondemand.com/

GoodReads website – https://www.goodreads.com/

For more info on Integration Cards:  please check this link: Card Explorer