Integration Cards API

Card API is used by the host environment to:

Set manifest URL or manifest object and base URL to create the card
Provide handlers for different user interaction events
Pass parameters needed by the card
Manage card state
Set width and height which would work for the layout used in the host environment

The Card API should not be confused with the Host API. The Card API is always used on specific card instance, while the Host controls many cards at once and its API affects all those cards. Both APIs also differ by the purpose they serve.

Handling Events

"action" Event

Each card can trigger action event. This event should be handled by the host environment to make the card interactions fully functional. The type of action event, determines the purpose of the action. The actions of each card are defined in its manifest. For more information, see actions in Learn section

For all available event parameters, see Card action event.

When using UI5

Adding handler for action event in the XML View

<mvc:View xmlns:w="sap.ui.integration.widgets">
	<w:Card manifest="./manifest.json" action=".onCardAction" />
</mvc:View>

action handler code in the controller.

onCardAction: function (oEvent) {
	console.log(oEvent.getParameter("type")  + " action triggered for card with ID 'cardWithActions'");
}

When using <ui-integration-card> custom HTML element

<body>
	<ui-integration-card id="cardWithActions" manifest="./some/location/my/card/manifest.json"></ui-integration-card>
	<script>
		document.getElementById("cardWithActions").addEventListener("action", function (event) {
			console.log(event.detail.getParameter("type") + " action triggered for card with ID 'cardWithActions'");
		});
	</script>
</body>

"configurationChange" Event

When some configuration settings are changed as a result of user interaction (for example - filter value is changed) the card instance triggers configurationChange event.

For all supported parameters, see configurationChange event API.

When using UI5

Adding handler for configurationChange event in the XML View

<mvc:View xmlns:w="sap.ui.integration.widgets">
	<w:Card manifest="./manifest.json" configurationChange=".onConfigurationChangeLog" />
</mvc:View>

configurationChange handler code in the controller.

...
onConfigurationChangeLog: function (oEvent) {
	console.log(oEvent.getParameter("changes"));
}
...

When using <ui-integration-card> custom HTML element

<body>
	<ui-integration-card id="card" manifest="./some/location/my/card/manifest.json"></ui-integration-card>
	<script>
		document.getElementById("card").addEventListener("configurationChange", function (event) {
			console.log(event.detail.getParameter("changes"));
		});
	</script>
</body>

Passing Parameters

The card developer can add parameters to the cards manifest. Such parameters are often optional and they influence the cards content. Some parameters are mandatory, because the card relies on this information to work properly. If a card needs to load data, one parameter might be the URL that should be used to trigger a data request. Parameters are card specific and are declared in the corresponding cards manifest. For an example with parameters usage in a manifest, see parameters in Explore section.

When using UI5

const oCard = new Card();
// This manifest expects a city parameter to render a card with information for that city.
oCard.setManifest("./manifest.json");
const oParameters = {
	"city": "Walldorf, DE"
};
oCard.setParameters(oParameters);

When using <ui-integration-card> custom element

const parameters = {
	"city": "Walldorf, DE"
};
const card = document.createElement("ui-integration-card");
card.setAttribute("id", "myCard");
card.setAttribute("manifest", "./some/location/my/card/manifest.json");
card.setAttribute("parameters", JSON.stringify(parameters));
document.body.appendChild(card);

Managing Card State

Card Data Mode

To control if the card should make requests or not the developer can set the dataMode property of the card. If the dataMode is set to Active the card will be able to load its manifest, resources and data. Setting the dataMode to Inactive will stop any further requests and loading. Some cards can refresh their data in a certain interval. This property provides control to the host environment to disable/enable any further requests. Setting the dataMode to Auto will stop manifest loading until the card enters the viewport.

For more information, see dataMode property API.

When using UI5

// Make card inactive for 10 seconds
const oCard = Element.getElementById("myCard");
oCard.setDataMode("Inactive");
setTimeout(function () {
	oCard.setDataMode("Active");
}, 10000);

When using <ui-integration-card> custom element

// Make card inactive for 10 seconds
const card = document.getElementById("myCard");
card.dataMode = "Inactive";
setTimeout(function () {
	card.dataMode = "Active";
}, 10000);

Refreshing Cards

In certain cases, the host environment detects that the card is no longer displaying up-to-date information and a card refresh is needed. To do that, the developer must call the refresh function of the card. It rerenders the card, reapplies the manifest and retriggers all data requests. This functionality depends on the dataMode property of the card, and only works if set to Active.

For more information, see refresh method API.

When using UI5

oCard.refresh();

When using <ui-integration-card> custom element

customElements.whenDefined("ui-integration-card").then(function () {
	const oCard = document.getElementById("myCard");
	oCard.refresh();
});

Refreshing Data

When you want to refresh the card data without rerendering the whole card, but only the part which shows the new data, you can call the refreshData function of the card. It retriggers all data requests.

For more information, see refreshData method API.

When using UI5

oCard.refreshData();

When using <ui-integration-card> custom element

customElements.whenDefined("ui-integration-card").then(function () {
	const oCard = document.getElementById("myCard");
	oCard.refreshData();
});

Configuring Card Dimensions

To configure the height and width of the card, you can set any value that the CSS properties height and width would accept.

When using UI5

To modify the height and width of the Card, set its respective attributes height and width.

<mvc:View xmlns:w="sap.ui.integration.widgets">
	<w:Card manifest="./manifest.json" width="360px" height="auto"/>
</mvc:View>

When using <ui-integration-card> custom element

Set the height and width using CSS as you would usually style any other aspect of your web application. The default display property of the custom element is inline-block.

The attributes height and width are not available on the custom element.

.myCard {
	width: 380px;
	height: 16rem;
}
...
<ui-integration-card class="myCard" manifest="./manifest.json"></ui-integration-card>