The Best Open Source Email & Collaboration Software

Deutsch Deutsch down

WebApp Plug-in Framework Explained: Create new Category in Settings Context

At some point in the development of a plug-in, you'll likely want to allow the user to configure something. If you are creating a widget, then that process is explained in detail in the WebApp Developers' Manual. However, for plugins, the configuration is done through the "Settings" tab of the WebApp. There, besides the availability of the "Advanced Settings", plugins can add additional user interface components into the main Settings interface.

By now, we all are very well familiar with the fact that WebApp can be extended easily because of the insertion-point mechanism. The Settings tab allows the user to change various configuration properties. The settings user interface consists of a group of tabs (called Settings Categories), which contain various "Setting Widgets". Each widget is intended to configure settings for various components, it allows a logical grouping of settings per component. The Settings Categories are available at the left side of setting context. For plugins, there is a special "Plugins" Settings Category, in which plugin developers are allowed to add their plugin related settings. Additionally, it also allows a plugin developer to insert a new Settings Category for their plugin.

To see this in action, you can enable the "ZDeveloper" plugin, so all the insertion points are displayed. This process is explained in an earlier blog post.

Using the various insertion points populated by SettingContext, the user can insert Setting Widgets as well as Settings Categories. In both of these, the end user can change plugin related configurations.

 

Two ways to add settings to settings context

  1. Add new Settings Widgets into an existing Settings Category.
  2. Create a new Settings Category for the plugin and add any amount of Settings Widgets into it.

We will give examples of how to use both of these.

1. Add SettingsWidgets into the "Plugins" Settings Category

There is a settings category tab named "Plugins", which is a common tab that can be used by all plugins. So first off, we will describe how to insert SettingsWidgets into the "Plugins" SettingsCategory. If you select the "Plugins" tab from the left panel of the settings context, you will find the insertion point named "context.settings.category.plugins" from the tab content area as shown in the screenshot below:

 

Now, in the code, you can register the insertion point to insert a custom SettingsWidget as implemented like this:

 

this.registerInsertionPoint('context.settings.category.plugins',
    this.putFacebookSettingsWidgets, this);
putFacebookSettingsWidgets : function()
{
    return {
        xtype : 'zarafa.zfacebookpluginsettingswidget'
    }
}

 

This will return an instance of "Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsWidget" which extends "Zarafa.settings.ui.SettingsWidget".

 

What follows is an example from a hypothetical Facebook plugin, that has an option to enable or disable chat functionality.

 

Ext.namespace('Zarafa.plugins.facebookplugin');

/**
 * @class Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsWidget
 * @extends Zarafa.settings.ui.SettingsWidget
 * @xtype zarafa.zfacebookpluginsettingswidget
 *
 * The {@link Zarafa.settings.ui.SettingsWidget widget} for configuring
 * the general plugin options in the {@link Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsCategory plugin category}.

 */
Zarafa.plugins.Facebookplugin.ZFacebookPluginSettingsWidget = Ext.extend(Zarafa.settings.ui.SettingsWidget, {
    /**
     * @constructor
     * @param {Object} config Configuration object
     */
    constructor : function(config)
    {
       config = config || {};
    
        Ext.applyIf(config, {
            title : _('ZFacebookPlugin settings'),
            layout : {
                type : 'form',
               align : 'stretch'
           },
            items : [
               {              
                    xtype: 'fieldset',
                   title: 'Chat :',
                    flex: 1,
                    border : false,
                    items :[
                        {
                            xtype : 'checkbox',
                            fieldLabel : _('Allow chat'),
                            name: 'chatStatus',
                           inputValue : '0'
                        }
                    ]
                }]                             
        });
   Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsWidget.superclass.constructor.call(this, config);
    }
});
Ext.reg('zarafa.zfacebookpluginsettingswidget', Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsWidget);

You can see that the constructor updates the configuration object with a WidgetSettings configuration object. The latter consists of a form panel that contains various configuration components; in this case a checkbox. Then, it will call the parent class constructor inside this constructor. Finally, it registers a new 'xtype' of this class called "zarafa.zfacebookpluginsettingswidget", this can be used to later refer to it.

After implementing as described above, it will display the SettingsWidget as in the screenshot below:

 

2. Create a new SettingsCategory and add SettingsWidgets into it

As the second approach, we present a way to insert a category into the Settings Context. In that case, any settings related to the plugin would be displayed separately in that particular Category. With the zdeveloper plugin enabled, select the "Settings" context from the upper right corner, and find the insertion point which is visible in the "settings category" tab at the left side of the screen - as displayed in the screenshot:

 

Here, we are going to add a new Settings Category. There are three main points to consider when creating new settings category. First of all, when you register to the settings insertion point to add a user interface for configuring your plugin's settings, then you need to extend two classes: 'Zarafa.settings.ui.SettingsCategory' and 'Zarafa.settings.ui.SettingsWidget'.

this.registerInsertionPoint('context.settings.categories', this.putFacebookPluginSettings, this);
putFacebookPluginSettings : function()
{
    return {
        xtype : 'zarafa.zfacebookpluginsettingscategory',
    }
}

Now, the above code snippet registers for the insertion point and it will call the function 'putFacebookPluginSettings'.  The latter returns an instance of 'zarafa.zfacebookpluginsettingscategory'. It contains the "Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsCategory" class which extends "Zarafa.settings.ui.SettingsCategory".

The following code snippet shows the 'Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsCategory' class.

Ext.namespace('Zarafa.plugins.facebookplugin');
/**
 * @class Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsCategory
 * @extends Zarafa.settings.ui.SettingsCategory
 * @xtype zarafa.zfacebookpluginsettingscategory
 *
 * The FacebookPlugin category for users which will
 * allow the user to configure FacebookPlugin related settings
 */

Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsCategory = Ext.extend(Zarafa.settings.ui.SettingsCategory, {
    /**
     * @constructor
     * @param {Object} config Configuration object
     */
    constructor : function(config)
    {
        config = config || {};
        Ext.applyIf(config, {
            title : _('ZFacebookPlugin'),
            iconCls : 'icon_exampleplugin_icon',
            items : [{
                xtype : 'zarafa.zfacebookpluginsettingswidget'
            }]
        });
     Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsCategory.superclass.constructor.call(this, config);
    }
});

Ext.reg('zarafa.zfacebookpluginsettingscategory', Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsCategory);

You can see that you have to define a constructor that will define a title and items as configuration objects. The title will be shown on the left hand side of the Settings Context as a Category Tab title. Finally, the items configuration contains widgets that will create the user interface of the settings for your plugin.

To create a user interface of the settings, you need to extend the class "Zarafa.settings.ui.SettingsWidget" and use this extended class in the items configuration option of "Zarafa.settings.ui.SettingsCategory".

"Zarafa.plugins.facebookplugin.ZFacebookPluginSettingsWidget" is already explained in the first part of this blog post.

At the very end, after successfully implementing the steps as mentioned above, the plugin will show the SettingsCategory tab named "ZFacebookPlugin" in the main Settings panel. When you click on it, it will show the content, as you can see in the screenshot above.

Like last week, to help plug-in developers use the knowledge presented in this article, we have put the example code in a simple plugin, which is available from our git tree. This will combine the two approaches of getting a Settings Widget in the Settings context.

Next week, we will address saving and retrieving settings values. This is obviously the next step when dealing with settings. Stay tuned!

 

Useful links:

WebApp Developers' Manual

SettingsCategory API documentation

SettingsWidget API documentation

Sample plugin containing the code of this post


Share:

Comments

Post new comment

 

Jobs at Zarafa

View zarafa tour 2013 video

Zarafa customers