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);