Accessing the "configurationUi" Contract
This contract allows you to provide a CHIP-specific configuration UI where an administrator can set parameters for the CHIP.
As a prerequisite, you have to consume the configurationUi contract in the CHIP definition XML.
The configurationUi property is then available in the CHIP API object. It provides the following methods:
- chip.configurationUi.attachCancel()
You can use this method to register an event handler to be notified when the user cancels the configuration.
- chip.configurationUi.attachSave()
You can use use this method to register an event handler to be notified when the user triggers a save action for the current configuration. The purpose of the event handler is to persist the configuration asynchronously (the configuration is not persisted by the embedding application, this is the responsibility of the CHIP). The event handler must return a jQuery.Deferred object's promise to inform the embedding application whether the save operation has been successful. If it has not been successful, an error message is provided.
- chip.configurationUi.display()
You can use this method to inform the embedding application that the user has triggered configuration of this CHIP.
- chip.configurationUi.isEnabled()
You can use this method to find out whether configuration of CHIPs is enabled.
- chip.configurationUi.setDirtyProvider()
You can use this method to to define the callback function which provides the configuration UI's "dirty" state for this CHIP. The callback function has to return a boolean value telling whether this CHIP's configuration UI is currently in a "dirty" state, that is, whether it contains unsaved changes.
- chip.configurationUi.setUiProvider()
You can use this method to define the callback function which provides the configuration UI for this CHIP. Since version 1.21.0, the function might get a map of parameters that can be used to set some default configuration values, for example.
Example:
onInit: function() {
varoChipApi = this.getView().getViewData().chip;
if(oChipApi.configurationUi.isEnabled()) {
oChipApi.configurationUi.setUiProvider(function(mParameters) {
// get configuration UI as sap.ui.core.Control
var oConfigurationUi = ...;
// make sure cancel/save handlers are attached now
oChipApi.configurationUi.attachCancel(function() {
});
oChipApi.configurationUi.attachSave(function() {
var oDeferred = newjQuery.Deferred();
// either reject or resolve, maybe later
return oDeferred.promise();
});
oChipApi.configurationUi.setDirtyProvider(function() {
return false; // tell about unsaved changes here!
});
return oConfigurationUi;
});
// enable some trigger to start configuration:
// oTrigger.attachPress(function () {
// oChipApi.configurationUi.display();
// }); // Note: do NOT use to display live data etc.!
}
}In this example, the CHIP instance checks whether configuration is enabled in its onInit method. If configuration is enabled, it sets a callback function which will later provide the configuration UI. That callback is the last point in time to make sure that cancel/save handlers are attached and a "dirty" provider is set - of course this can also be done earlier. In addition, the CHIP enables a trigger (for example, click on the CHIP) for the user to request the configuration UI to be displayed. This trigger should call oChipApi.configurationUi.display() when invoked.
Example:
<?xmlversion="1.0"encoding="UTF-8"?> <!-- Copyright (c) 2013 SAP SE, All Rights Reserved --> <chip xmlns="http://schemas.sap.com/sapui2/services/Chip/1"> <implementation> <sapui5> <viewName>foo.Bar.view.xml</viewName> </sapui5> </implementation> <appearance> <title>Configuration UI</title> </appearance> <contracts> <consumeid="configurationUi"/> </contracts> </chip>