Use Integration Cards In Apps

There are two ways to consume a card:

• Pass a URL from where to load the manifest.
• Pass a manifest object and a base URL. The base URL is needed to resolve relative URLs of card static resources like translations and icons.

Consumption in UI5

Using manifest URL

Consumption in an XML View

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

Consumption in JS

// Card required from "sap/ui/integration/widgets/Card"
const oCard = new Card({
	manifest: "./mycardbundle/manifest.json",
	width: "400px"
});
someContainer.addContent(oCard);

Using manifest object and base URL

Consumption in an XML View

For the example below the manifest object is saved inside a model with name "myModel", which is then used with the standard UI5 binding syntax.
Note: Unnamed models can not be used for this scenario. Same applies for model names which are internally created by the card as "parameters", "filters", "i18n", etc.

<mvc:View xmlns:w="sap.ui.integration.widgets">
	<w:Card manifest="{myModel>/manifestObject}" baseUrl="./mycardbundle/" width="400px"/>
</mvc:View>

Consumption in JS

// Card required from "sap/ui/integration/widgets/Card"
const oManifest = {
	"sap.app": {
		"i18n": "i18n/i18n.properties",
		"type": "card",
		"id": "my.card"
	},
	"sap.card": {
		"type": "List",
		"header": {
			...
		},
		"content": {
			...
		}
	}
};
const oCard = new Card({
	manifest: oManifest,
	baseUrl: "./mycardbundle/"
});
someContainer.addContent(oCard);

How baseUrl Resolves URLs

When a card uses a manifest object, the baseUrl serves as the base path for resolving relative URLs in the card manifest. This includes data requests, icon paths, i18n resource bundles, and extension modules.

URL resolution behavior:

• Relative paths such as "./images/icon.png" or "./data.json" are resolved relative to the baseUrl.
• Absolute URLs such as "https://example.com/data.json" are used as-is without resolution.
• Root-absolute paths such as "/images/icon.png" are resolved relative to the host application root.
  Note: Card developers should avoid root-absolute paths. Use relative paths, destinations, or absolute URLs instead.

When using a manifest URL instead of a manifest object, the baseUrl is automatically derived from the manifest's location. If both a manifest URL and an explicit baseUrl are provided, the explicit baseUrl takes precedence.

Consumption in HTML

Cards can also be consumed in HTML. To do that you should load the integration card bundle which includes a minimalistic UI5 Core and all other components which are needed to render a card. There are two resource bundles depending if your application has jQuery or not:

• With jQuery https://{YourUI5Location}/resources/sap-ui-integration.js
• Without jQuery https://{YourUI5Location}/resources/sap-ui-integration-nojQuery.js

After the bundle is loaded "ui-integration-card" custom element is created.

Loading the integration bundle

• Set the URL to the integration bundle
• Set the ID to be "sap-ui-bootstrap"
• Set the compatibility version to "edge"
• Set a theme. The recommended one is "sap_horizon"

<script src="https://ui5.sap.com/resources/sap-ui-integration.js"
	id="sap-ui-bootstrap"
	data-sap-ui-compatVersion="edge"
	data-sap-ui-theme="sap_horizon">
</script>

Using manifest URL

<body>
	<ui-integration-card manifest="./some/location/my/card/manifest.json"></ui-integration-card>
</body>

Using manifest object and base URL

<body>
	<ui-integration-card
		base-url='./some/location/my/card/'
		manifest='{
			"sap.app": {
				"type": "card",
				"id": "tableCardAsAttribute"
			},
			"sap.card": {
				"type": "Table",
				"header": {
					...
				},
				"content": {
					...
				}
			}
		}'>
	</ui-integration-card>
</body>