Host Configuration Capabilities

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 configuration 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 configuration 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 configuration to show a selection of available contexts
	host.getContext = function() {
		return Promise.resolve(host.context);
	};

Embedding a Configuration Editor in a Host Environment

A host environment can embed the Configuration Editor in different modes depending on the logged in persona.

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


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


<!-- Translator Configuration Editor -->
<ui-integration-card-editor
	id="translationEditor"
	mode="translation"
	card='{"manifest":"manifest.json","baseUrl":"..","manifestChanges":[...]}'
	language="de">
</ui-integration-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: {manifest:"url", baseUrl:"baseUrl", manifestChanges:[]},
	mode: "admin"
});

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

// for the translation mode a language is needed
var oEditor = new CardEditor({
	card: {manifest:"url", baseUrl:"baseUrl", manifestChanges:[]},
	mode: "translation",
	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 Configuration 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 Configuration Editor.

Getting changes from the Configuration Editor

// Administrator Configuration 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 Configuration Editor
var editor = document.getElementById("contentEditor");
var contentSettings = editor.getCurrentSettings();
// store the settings contentSettings in the host for the edited instance

// Translator Configuration Editor
var editor = document.getElementById("translationEditor");
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"); // stringified JSON
var contentChanges = myHostEnvImplementation.getChanges(cardid, "content");// stringified JSON
var translationChanges = myHostEnvImplementation.getChanges(cardid, "translation", 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);