FirstZimletUsingZDesktop
Introduction
Here we are going to develop a RSS Zimlet using Yahoo! Zimbra Desktop. This is not a hello-world Zimlet and the idea is to demonstrate how easy it is to write a relatively feature-rich Zimlet and also to show various aspects and apis of Zimlet development.
Pre-requisits:
1. Have basic Javascript knowledge and know what a 'callback' and 'closure' mean.
2. Have the Zimbra development environment setup via Zimbra Desktop(or by building source-code).
3. Have have Proxy-Zimlet that opens-up all domains deployed.
The RSS Example Zimlet(com_zimbra_rssexample) Requirements
This Zimlet's objective is to get an RSS feed from news.yahoo.com and display the result in a dialog box. It will also have an option to show the result in the mini-calendar(aka mini-cal) area. User can right-click on the panel-item and change the preference to show the information in either dialog-box or in mini-cal area.
If mini-cal area is chosen, Single-clicking(or double-clicking) on the panel-item should show the rss-feed in mini-cal area and while its displayed single-clicking on the panel-item another time should hide-it(and show the mini-calendar back).
Zimlet files
Now we have the requirements, lets start developing it. Remember we will be developing the RSS Zimlet in _dev folder so that we don't have to worry about deploying-restart-undeploying cycle. Now, Lets look at the files we might need.
Since we are writing a JavaScript-based Zimlet, we need the following files:
1. A Zimlet Description file (e.g. com_zimbra_rssexample.xml) - This is where we describe Zimlet information, things like: Zimlet name, Zimlet version, user properties.
Note: If the Zimlet is written mainly using xml-api, this will be the primary file you will work with.
2. Zimlet JavaScript file (e.g. rssexample.js) - This is the main file that does all the hard work.
3. A configuration file (config_template.xml) - Contains configuration information like "alloweddomains". This is used to indicate that a specific domain is OK to access.
Note: This is not required if your Zimlet doesn't talk to any services but an Extension-Zimlet like: email-reminder, colored-emails etc.
4. A panel-icon image(e.g. rssexample.png) - Usually a 16x16 panel icon for the Zimlet.
Note: This is not required if your Zimlet doesn't provide any preferences and/or not user-triggered(via Singleclick or double-click) Zimlet.
Zimlet Description file
This is where we describe Zimlet information, things like: Zimlet name, Zimlet version, user properties. And below is how the completed file looks like.
<zimlet name="com_zimbra_rssexample" version="0.1" description="displays rss feeds from yahoo!"> <include>rssexample.js</include> <includeCSS>rssexample.css</includeCSS> <handlerObject>com_zimbra_rssexample</handlerObject> <zimletPanelItem label="RSS Example" icon="rssexample-panelIcon"> <toolTipText>displays rss feeds from yahoo</toolTipText> <contextMenu> <menuItem label="Zimlet Preferences" id="smseg_preferences" /> </contextMenu> </zimletPanelItem> <userProperties> <property type="string" name="rsseg_showFeedsInMiniCal" value="false"/> </userProperties> </zimlet>
Lets dig deeper and see what they all mean.
To start with, we need to describe the Zimlet's name, version and description.
<zimlet name="com_zimbra_rssexample" version="0.1" description="displays rss feeds from yahoo!">
Since we are developing JavaScript(rssexample.js), we need to tell Zimbra to upload/include the JavaScript file.
<include>rssexample.js</include>
One of the requirements is to show the RSS feed information in a dialog box. To make it look good lets use a CSS file where we can describe all the style information.
<includeCSS>rssexample.css</includeCSS>
Create a handler object to suggest that we are using JavaScript-api and to call the Zimlet during login or init time.
<handlerObject>com_zimbra_rssexample</handlerObject>
This Zimlet needs a panel-item so that we can click to show information in dialog-box or show/hide it in mini-calendar area. zimletPanelItem says what the label("RSS Example") of the overview-panel should be and what icon should be used"rssexample-panelIcon".
- It has <toolTipText> to show information of what the Zimlet does when a user mouse-overs the panel-item.
- It also has <contextMenu> to describe what should happen when user right-clicks on panel item. In our case we need this to allow user to choose show-in-dialogbox vs show-in-minical preference. so lets describe a menuItem whose name/label is "Zimlet Preferences".
<zimletPanelItem label="RSS Example" icon="rssexample-panelIcon"> <toolTipText>displays rss feeds from yahoo</toolTipText> <contextMenu> <menuItem label="Zimlet Preferences" id="smseg_preferences" /> </contextMenu> </zimletPanelItem>
One last thing thats required for our Zimlet is a way to store user's preference b/w show-in-dialogbox vs show-in-minical. Zimlet will store and retrieve this information to obey the choice for subsequent sessions or sign-ins.
Lets give a unique name to this property "rsseg_showFeedsInMiniCal" and set its type to string. Since this is a boolean, we can also use boolean instead.
<userProperties> <property type="string" name="rsseg_showFeedsInMiniCal" value="false"/> </userProperties>