Host Design-time Capabilities

Overview

The host environment needs to add support the editing of Cards. It is responsible to

Provide Host implementation

sap.ui.require(["sap/ui/integration/Host"], function(Host) {
	// Create a new Host environment with id "host"
	var host = new Host("host");

	//define a list of known destinations
	host.destinationList = [
		{"name": "destination1"},
		{"name": "destination2"},
	];

	//define the current context structure with design-time information
	host.context = {
		"sap.workzone": {
			"currentUser": {
				"id": {
					"label": "Id of the Work Zone user",
					"placeholder": "Work Zone user id",
					"description": "The value will change based on the logged on user",
					"value": "MyCurrentUserId"
				}
			}
		}
	};

	//called by runtime to resolve the destination to a real URL
	host.resolveDestination = function(name) {
		return this.getDestinations().then(function(destinationList) {
			return "https://.../dynamic_dest/" + name;
		})
		return destination.realUrl
	};

	//called by the design-time to show a list of available destinations
	host.getDestinations = function(name) {
		return Promise.resolve(this.destinationList);
	}

	//called by runtime to resolve a context value by path. example: "/sap.workzone/currentUser/id/value"
	host.getContextValue = function(path) {
		return this.getContext().then(function (node) {
			var parts = path.split("/"),
				i = 0;
			while (node && parts[iIndex]) {
				node = node[parts[iIndex]];
				i++;
			}
			return node;
		});
	};

	//called by the design-time to show a selection of available contexts
	host.getContext = function() {
		return Promise.resolve(host.context);
	};

Embedding a Card Editor in a host environment

A host environment can embed the card editor in different modes depending on the logged in persona.

HTML Embedding

<!-- Administrator Card Editor -->
<ui-integration-card-editor
	id="adminEditor"
	mode="admin"
	card='{"manifest":"manifest.json", "baseUrl":"..","manifestChanges":[...]}'>
</ui-indegration-card-editor>


<!-- Content Card Editor -->
<ui-integration-card-editor
	id="contentEditor"
	mode="content"
	card='{"manifest":"manifest.json","baseUrl":"..","manifestChanges":[...]}'>
</ui-indegration-card-editor>


<!-- Translator Card Editor -->
<ui-integration-card-editor
	id="translationEditor"
	mode="translator"
	card='{"manifest":"manifest.json","baseUrl":"..","manifestChanges":[...]}'
	language="de" >
</ui-indegration-card-editor>

Embedding in UI5 environments

Samples for the different personas can be found here


//if no card instance is available, pass the settings of the card in the part property
var oEditor = new CardEditor({
   card: {manifes:"url", baseUrl:"baseUrl", manifestChanges:[]},
   mode: "admin"
});

//create a new card instance or use an existing one. Often a Card is already on the page
var oEditor = new CardEditor({
card: new Card({manifes:"url", baseUrl:"baseUrl", manifestChanges:[]}),
   mode: "tranlation" language="fr"
});

//for the translation mode a language is needed
var oEditor = new CardEditor({
card: {manifes:"url", baseUrl:"baseUrl", manifestChanges:[]},
mode: "tranlation" language="fr"
});
				

Handling of Changes

After the user made changes to the Card configuration, those need to be stored by the host environment. Normally the Card Editor is embedded into a UI of the host environment. Here the host should define an action for the user to save his changes.
To retrieve the changes the host can ask the Card Editor.

Getting changes from the Card Editor


// Administrator Card Editor
var editor = document.getElementById("adminEditor");
var adminSettings = editor.getCurrentSettings();
// store the settings adminSettings in the host. These settings should be applied during runtime for all card instances
//based on this Card template


// Content Card Editor
var editor = document.getElementById("contentEditor");
var contentSettings = editor.getCurrentSettings();
// store the settings contentSettings in the host for the edited instance

// Translator Card Editor
var editor = document.getElementById("contentEditor");
var language = editor.getAttribute("language");
var translationSettings = editor.getCurrentSettings();
//store the settings translationSettings in the host for the language given in the language attribute during editor creation

Apply changes to the Card instance at runtime

//read the changes
var adminChanges = myHostEnvImplementation.getChanges(cardid, "admin"); //stringifiedJSON
var contentChanges = myHostEnvImplementation.getChanges(cardid, "content");//stringifiedJSON
var translationChanges = myHostEnvImplementation.getChanges(cardid, "trans", currentuserslanguage);//stringifiedJSON

var el = document.createElement("div");
el.innerHTML = `
<ui-integration-card
   id="cardInstance"
   manifest="manifest.json"
   baseUrl="..."
   manifestChanges='[` + adminChanges + `, ` + contentChanges + `, ` + translationChanges + `]'>
</ui-integration-card>`;

document.getElementById("contentarea").appendChild(el.firstChild);