Integration Cards API

Card API is used by the host environment to:

Handling "action" Event

A card instance 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. Currently the types of actions are limited to Navigation. Actions are defined inside the card manifest. For more information, see actions in Learn section

For all supported parameters, see action event API.

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=".onActionLog" />
</mvc:View>

action handler code in the controller.

...
onActionLog: function (oEvent) {
	console.log(oEvent.getParameter("type")); // The type of the action
	console.log(JSON.stringify(oEvent.getParameter("parameters"), null, 2)); // The action parameters passed from the card to the host environment
	console.log(oEvent.getParameter("actionSource")); // The source of the action
}
...

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>

Handling "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

A card developer can add parameters to the cards manifest. Such parameters are often optional and allow to 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

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

When using <ui-integration-card> custom element

var parameters = {
	"city": "Walldorf, DE"
};
var 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
var oCard = sap.ui.getCore().byId("myCard");
oCard.setDataMode("Inactive");
setTimeout(function () {
	oCard.setDataMode("Active");
}, 10000);

When using <ui-integration-card> custom element

// Make card inactive for 10 seconds
var card = document.getElementById("myCard");
card.dataset.mode = "Inactive";
setTimeout(function () {
	card.dataset.mode = "Inactive";
}, 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 () {
	var 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 () {
	var 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>