The Best Open Source Email & Collaboration Software

WebApp: Managing settings

In the previous blog post, we described how plugins can offer the user some settings to configure the plugin's behavior.  However, we then focused only on adding new user interface components to the Settings interface. In this blogpost then, we will go deeper into working with settings, and show how they can be used by the plugin.

When Zarafa WebApp loads, all settings for the user are loaded into the Zarafa.settings.SettingsModel. This class is the main interface that can be used to retrieve and save the settings values. The main Zarafa.settings.SettingsModel instance can be requested from the `container` global variable using:

var settings = container.getSettingsModel();

The settings are stored in a hierarchical, tree-like structure. The best way to view the structure of this hierarchy is to go to the "Advanced" category in the Settings interface of Zarafa WebApp. The root in which all settings can be found is `zarafa` -> `v1`. From there on, the settings are separated in groups. All general settings which can be used anywhere within the WebApp can be found beneath the `main` group. The context specific settings, like mail and calendar, can be found in `contexts` -> `mail` and `contexts` -> `calendar` respectively. The `state` group contains all settings that reflect the state properties of the WebApp (e.g. dialog sizes and selected views) which should be remembered between sessions. The group `widgets` contains the settings for the widgets which are currently present in the sidebar or on the Zarafa tab. Finally, the group 'plugins' is specifically for plugins. Beneath this group, the settings for each individual plugin is stored in a seperate group. Within such a group, a plugin can arrange the settings in the way that is best suited for the plugin.

As an example, we will show how to obtain the setting that indicates if the ZDeveloper plugin has been enabled by the user. As explained above, the settings path is hierarchical; this means that the ZDeveloper related settings can be found in `zarafa` -> `v1` -> `plugins` -> `zdeveloper`. When looking in the "Advanced" category in the Settings interface, we can see that a setting exists in this group, called `enable`. This means that the name via which the setting value can be retrieved from the SettingsModel is: `zarafa/v1/plugins/zdeveloper/enable`. To obtain the value of this setting, you can call:

var settings = container.getSettingsModel();
var enable = settings.get('zarafa/v1/plugins/zdeveloper/enable');

To change the setting, we can call 'set()':

var settings = container.getSettingsModel(); 
settings.set('zarafa/v1/plugins/zdeveloper/enable', true);

The argument passed to the 'set()' function can be of any type that is useful for settings. However, passing Objects are treated a bit specially, since the Object keys will be transformed into new settings. This is done to simplify the way to save multiple settings at once. Consider the following example where an object is saved into the settings:

var obj = {
    enable : 'true',
    display_name : 'My Plugin',
    index : 4
var settings = container.getSettingsModel();
settings.set('zarafa/v1/plugins/example', obj);

There are now 2 methods of accessing the object which is saved to the settings. You can  request the individual keys:

console.log(settings.get('zarafa/v1/plugins/example/enable')); // True
console.log(settings.get('zarafa/v1/plugins/example/display_name')); // My Plugin
console.log(settings.get('zarafa/v1/plugins/example/index')); // 4

Alternatively, it is also possible to request the entire object from the settings. Then, for safety, requesting objects must be done explicitly by passing `true` for the second argument to the 'get()' function:

var object = settings.get('zarafa/v1/plugins/example', true);
console.log(object['enable']) // True
console.log(object['display_name']) // My Plugin
console.log(object['index']) // 4

Each time the function 'set()' is called, a request is made to the server to save the settings. Therefore, when changing multiple settings, it is recommended to make only a single request to the server. This will reduce the number of calls made to the server, leading to better performance. This can be done with a so-called edit block using 'beginEdit()' and 'endEdit()':

var settings = container.getSettingsModel();
settings.set('zarafa/v1/plugins/example/enable', true);
settings.set('zarafa/v1/plugins/example/display_name', 'My Plugin');
settings.set('zarafa/v1/plugins/example/index', 4);

Once endEdit() is called, all modified settings will be sent to the server in a single request.

Finally, it is also possible to delete existing settings when they are no longer needed. For this, the 'delete()' function can be used. This function requires only the path of the setting to be deleted; this can be either a single setting or an entire group of settings:

var settings = container.getSettingsModel();
// The following line deletes only the 'enable' setting
// The following line deletes all the example settings

Working with settings should be relatively easy. But when you start working with settings for the first time, it is recommended to carefully look at how your settings appear in the "Advanced" category of the Settings interface. This way, you can ensure that it looks like it was intended.

The Example Plugin from the last blog post (in which the Settings Categories and Settings Widgets were described) has been updated with the SettingsModel interaction to load and update the settings.





Post new comment


Jobs at Zarafa

View zarafa tour 2013 video

Zarafa customers