Handle Actions

Host environment can listen for actions dispatched by the cards and handle them. Some actions like the "Navigation" should be handled entirely by the host environment. Each hosted card instance can dispatch action events of different types. The type determines the purpose of the action. For more information about what action types to expect from cards, as well as their parameters, see actions in Learn section.

Listen for the Action Event

The actions of all cards associated with a given host are dispatched to the sap.ui.integration.Host instance, so attaching a single event listener to it is enough.

The example below shows how to listen for the action event.

1. Create the cards

<mvc:View xmlns:w="sap.ui.integration.widgets" controllerName="hostController">
	<w:Card id="card1" manifest="./manifest1.json" />
	<w:Card id="card2" manifest="./manifest2.json" />
</mvc:View>

2. Create the host, set the host association of the cards and implement action event handler

sap.ui.define([
	"sap/ui/core/mvc/Controller",
	"sap/ui/integration/library",
	"sap/ui/integration/Host"
], function (Controller, integrationLibrary, Host) {
	"use strict";

	return Controller.extend("hostController", {
		onInit: function () {
			const oHost = new Host({
				action: this.onAction.bind(this)
			});
			this.byId("card1").setHost(oHost);
			this.byId("card2").setHost(oHost);
		},
		onAction: function (oEvent) {
			const sType = oEvent.getParameter("type"); // The type of the action. One of "Navigation", "Submit", "Custom", etc.
			const oParameters = oEvent.getParameter("parameters"); // The action parameters. The different actions types have different parameters
			const bHandled = false; // Flag indicating if the action is handled

			if (sType === integrationLibrary.CardActionType.Navigation) {
				// handle Navigation action
				...
				bHandled = true;
			} else if (sType === integrationLibrary.CardActionType.Submit) {
				// handle Submit action if needed
				...
				bHandled = true;
			} else if (...) {
				...
			}

			// Prevent the default behavior of the handled actions
			if (bHandled) {
				oEvent.preventDefault();
			}
		}
	});
});

For all available event parameters, see Host action event.

Handle Navigation Action

Navigation action can be to open a URL or intent-based. This can be determined by the event parameters - when there is ibnTarget provided, then the card requires an intent-based navigation, otherwise it requires navigation to a URL.

The intent-based navigation does not have a default implementation, so it has to be handled by the host.

This example shows how intent-based navigation can be handled in the context of SAP Fiori Launchpad, with the help of sap.ushell.services.Navigation.

...
// Container required from "sap/ushell/Container"
onAction: function (oEvent) {
	const sType = oEvent.getParameter("type");

	// handle Navigation action
	if (sType !== integrationLibrary.CardActionType.Navigation) {
		return;
	}

	const oParameters = oEvent.getParameter("parameters");

	if (oParameters.ibnTarget) {
		oEvent.preventDefault(); // as the action will be handled by the host, prevent its default behavior

		// possible variant how to perform intent-based navigation
		Container.getServiceAsync("Navigation").then(function (NavigationService) {
			NavigationService.navigate({
				target: oParameters.ibnTarget,
				params: oParameters.ibnParams
			});
		});
	}
}