FirstZimletUsingZDesktop: Difference between revisions

(New page: == 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 relative...)
 
Line 40: Line 40:


== Zimlet Description file ==
== 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.
This is where we describe Zimlet information, things like: Zimlet name, Zimlet version, user properties. And below is how the completed file looks like.  


<pre>
<pre>
Line 86: Line 86:
<pre>
<pre>
<handlerObject>com_zimbra_rssexample</handlerObject>
<handlerObject>com_zimbra_rssexample</handlerObject>
</pre>
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".
<pre>
  <zimletPanelItem label="RSS Example" icon="rssexample-panelIcon">
    <toolTipText>displays rss feeds from yahoo</toolTipText>
<contextMenu>
<menuItem label="Zimlet Preferences" id="smseg_preferences" />
</contextMenu>
  </zimletPanelItem>
</pre>
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.
<pre>
<userProperties>
<property type="string" name="rsseg_showFeedsInMiniCal" value="false"/>
</userProperties>
</pre>
</pre>

Revision as of 23:05, 16 March 2009

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>
Jump to: navigation, search