WebApp Plug-in Framework Explained: zdeveloper

This is the first installment of a series of blog posts about WebApp plug-in development.

In this edition, we'll take a look at a fine little plug-in called 'zdeveloper'. This plug-in allows plug-in developers to visibly identify locations where the WebApp UI can be extended using so-called "insertion points."

Insertion points are hooks with unique identifiers for locations where UI components can be added within the general interface of the WebApp. For example, the Spreed plug-in uses the "context.mail.contextmenu.options" insertion point to create a new action in the context menu for e-mails:

this.registerInsertionPoint('context.mail.contextmenu.options', ...);

The name of an insertion point is hierarchical, so most things specifically related to e-mail will start with "context.mail" and have a more precise indication of the location after that.

Now, while we do not have a list of insertion points in the documentation, it is possible to get an overview of them by enabling the zdeveloper plug-in. Do this by navigating to Settings > Advanced, select Settings / zarafa / v1 / plugins / zdeveloper, and double-click the "false" to show a checkbox, check it to turn the plug-in on, and click Apply. Then, log out and back in again. You will immediately notice why it is disabled by default.

WebApp now shows little text boxes containing the names of all existing insertion points. See the screenshot for an example. So, for example, next to the "Reload" button in the main tool bar, there is a label with the text "main.toolbar.actions". This means that if you register to that insertion point, the result will be put there, in the toolbar, as a button.

this.registerInsertionPoint('main.toolbar.actions', this.addCustomAction, this);
addCustomAction : function(insertionpoint) {
return {
xtype : 'button',
tooltip : _('Custom Action'),
iconCls : 'icon_customAction'
}
}

In this case, the function "addCustomAction" is defined in your plug-in and returns an instance of Ext.Button, which is also suitable for inclusion in a tool bar like this. Other insertion points require different types of objects, please refer to the API documentation for the object type that the insertion point expects.

So, using the zdeveloper plug-in, you can quickly identify where you can add user interface elements to WebApp. Moreover, if you already know where to look, you can use it to get the exact name of the insertion point that you need. For all the rest, you still need the API reference documentation.

Useful links:

The WebApp API documentation

The WebApp developers manual