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. BTW, this is more-or-less what we need for a typical JavaScript-api based Zimlet and not just this example.

<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>