Host Design-time Capabilities
Overview
The host environment needs to add support the editing of Cards. It is responsible to
- Provide Host implementation providing functionality
- to resolve destinations during runtime
- get a list of destinations during design-time
- to resolve available contexts during runtime
- get a context information during design-time
- Embed the Card Editor into it's configuration UI for the different personas
- Allow the administrator to use the Card Editor to configure connectivity
- Allow the page/content administrator to use the Card Editor to configure Card instances on pages
- Allow the translator to use the Card Editor to translate text
- Store the changes that were made from each persona
- Apply the changes of each persona during runtime and design-time
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);