Card Extension

Cards provide a rich set of capabilities out of the box. The Extension JavaScript module provides means for the card developers to define custom logic where additional functionality is needed. The module needs to be part of the card bundle and allows for:

Functionality	Description	Responsibility of
Custom logic for fetching data	In case you need specific handling for the data retrieval, when direct request to a data service endpoint is not enough, you can provide a custom function that will collect and provide the data to the card.	Extension, Manifest
Custom formatters	Define custom formatters and then use them in the manifest the same way as the already predefined formatters which the card provides.	Extension, Manifest
Custom actions	In the extension you can define custom actions, which will appear in the header of the card.	Extension

Manifest Properties

Property	Type	Required	Default	Description	Schema Version	Since
extension	string	No		The path to the extension module. It is resolved relatively to the card.	1.23	1.79

Extension Lifecycle

The extension lifecycle is bound to the card that uses it. The below listed hooks can be used to react on key card events.

Name	Description
init	Called when the extension is instantiated.
exit	Called when the extension is destroyed.
onCardReady	Called after the card is initialized. After this `getCard()` returns an interface to the card. Read more in the Extension API.
loadDependencies	Called during the preparation of the card content, before it is displayed for the first time. Use it to load critical libraries or resources, without which the data in the content cannot be displayed. It is important to return a `Promise`, which will be awaited by the card. Until the promise is resolved, the card content displays a loading animation. For performance optimization the dependencies loading happens in parallel with data loading, therefore your data loading method shouldn't depend on this hook. Note: This hook can only be used in conjunction with the card content (`"sap.card"/content`), not with the card header, footer, or other part. Note: This hook is experimental since 1.108 and may change!

Extension API

In the Extension JavaScript module you can use getCard() method, which provides an interface to the card API. For example you can resolve destinations or get access to the card parameters. For detailed information about all the available methods, read the sap.ui.integration.Extension API.

Extension Requirements

The extension should be defined in a UI5 Module and extend the sap.ui.integration.Extension class.
For optimal loading performance it is recommended to avoid any dependencies that are not part of the sap.ui.integration library.

Note: Each card can have only one extension.

Shared extensions allow one extension to be reused by multiple cards.

Prerequisite: The extension must be part of a UI5 library and this library has to be registered by the host developers. This library may also include other modules which are used in the extension if needed. To use an extension from a shared library first define this library as dependency of the card:

"sap.ui5": {
	"dependencies": {
		"libs": {
			"my.lib.cards": {}
		}
	}
}

Then you can refer to the extension from this library with the following syntax:

"sap.card"{
	"extension": "module:my/lib/cards/CommonExtension"
}

Try it Out

Examples

Manifest

{
	"sap.app": {
		"id": "card.explorer.cardWithExtension",
		"type": "card",
		"applicationVersion": {
			"version": "1.0.0"
		}
	},
	"sap.card": {
		"extension": "./SampleExtension",
		"data": {
			"extension": {
				"method": "myGetDataMethod"
			}
		}
		"header": {
			...
		},
		"content": {
			...
		}
	}
}

Extension

sap.ui.define(["sap/ui/integration/Extension"], function (Extension) {

	const SampleExtension = Extension.extend("card.explorer.cardWithExtension.SampleExtension");

	SampleExtension.prototype.myGetDataMethod = function () {
		const oData1 = { user: "John" }; // this data can be fetched from data service
		const oData2 = { user: "Peter" }; // this data can be fetched from another data service

		// in the end data from both data services is combined into a single array
		return Promise.resolve([oData1, oData2]);
	};

	return SampleExtension;
});