Difference between revisions of "FirstZimletUsingZDesktop"

(Zimlet Description file)
Line 28: Line 28:
 
- This is the main file that does all the hard work.  
 
- This is the main file that does all the hard work.  
  
3. A configuration file (config_template.xml)
+
3. A Zimlet configuration file (config_template.xml)
 
- Contains configuration information like "alloweddomains". This is used to indicate that a specific domain is OK to access.  
 
- Contains configuration information like "alloweddomains". This is used to indicate that a specific domain is OK to access.  
  
Line 39: Line 39:
  
  
== Zimlet Description file ==
+
== Zimlet Description file (com_zimbra_rssexample.xml)==
 
This is where we describe Zimlet information, things like: Zimlet name, Zimlet version, user properties. And below is how the completed file looks like.  
 
This is where we describe Zimlet information, things like: Zimlet name, Zimlet version, user properties. And below is how the completed file looks like.  
  
Line 111: Line 111:
 
<property type="string" name="rsseg_showFeedsInMiniCal" value="false"/>
 
<property type="string" name="rsseg_showFeedsInMiniCal" value="false"/>
 
</userProperties>
 
</userProperties>
 +
</pre>
 +
 +
 +
 +
 +
== Zimlet configuration file (config_template.xml) ==
 +
Contains configuration information like "alloweddomains". This is used to indicate that a specific domain is OK to access. We need this because our Zimlet talks to external sites directly via javascript. Note: You can skip this if your Zimlet talks to external sites via jsp.
 +
<zimletConfig name="com_zimbra_rssexample" version="0.1">
 +
    <global>
 +
        <property name="allowedDomains">rss.news.yahoo.com</property>
 +
    </global>
 +
</zimletConfig>
 +
 +
 +
== The CSS file (rssexample.css) ==
 +
This is the file where you would write all the necessary style-sheet details required by the Zimlet's panel-item, dialogbox, menu etc.
 +
 +
When we were describing the zimlet's panelItem in ZimletDescription.xml file (<zimletPanelItem label="RSS Example" icon="rssexample-panelIcon">), we had mentioned icon="rssexample-panelIcon". This is actually the CSS classname. Zimbra prepends "Img" to the classname to make it "Imgrssexample-panelIcon"  and then uses the image "rssexample.gif" described within the resulting css class and plugs it as Zimlet panel icon.
 +
 +
<pre>
 +
.Imgrssexample-panelIcon {
 +
  background: url("rssexample.gif") no-repeat 0 0;
 +
  width: 16px;
 +
  height: 16px;
 +
  overflow: hidden;
 +
}
 +
</pre>
 +
 +
 +
Once we get RSS results back and show them in dialog, we need to show the feed url(in our case news url) and feed details(news details). The below styles are to simply show the url in yellowish-background and details in whitish-background.
 +
<pre>
 +
.rsseg_sectionDiv{
 +
background:#FFFFFF;
 +
border-bottom:1px solid #A7A194;border-right:1px solid #A7A194;
 +
}
 +
.rsseg_HdrDiv{
 +
background:#FFFF99;
 +
border-bottom:1px solid #A7A194;border-right:1px solid #A7A194;
 +
font-size:200%;
 +
}
 +
</pre>
 +
 +
 +
== Main Javascript file (rssexample.js) ==
 +
: - This is the main file that does all the hard work.
 +
 +
We will start-off with writing a constructor. And make the object a "Zimlet" by subclassing it to ZmZimletBase()
 +
<pre>
 +
function com_zimbra_rssexample() {
 +
}
 +
 +
com_zimbra_rssexample.prototype = new ZmZimletBase();
 +
com_zimbra_rssexample.prototype.constructor = com_zimbra_rssexample;
 
</pre>
 
</pre>

Revision as of 23:30, 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 Zimlet 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 (com_zimbra_rssexample.xml)

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>



Zimlet configuration file (config_template.xml)

Contains configuration information like "alloweddomains". This is used to indicate that a specific domain is OK to access. We need this because our Zimlet talks to external sites directly via javascript. Note: You can skip this if your Zimlet talks to external sites via jsp. <zimletConfig name="com_zimbra_rssexample" version="0.1">

   <global>
       <property name="allowedDomains">rss.news.yahoo.com</property>
   </global>

</zimletConfig>


The CSS file (rssexample.css)

This is the file where you would write all the necessary style-sheet details required by the Zimlet's panel-item, dialogbox, menu etc.

When we were describing the zimlet's panelItem in ZimletDescription.xml file (<zimletPanelItem label="RSS Example" icon="rssexample-panelIcon">), we had mentioned icon="rssexample-panelIcon". This is actually the CSS classname. Zimbra prepends "Img" to the classname to make it "Imgrssexample-panelIcon" and then uses the image "rssexample.gif" described within the resulting css class and plugs it as Zimlet panel icon.

.Imgrssexample-panelIcon {
  background: url("rssexample.gif") no-repeat 0 0;
  width: 16px;
  height: 16px;
  overflow: hidden;
}


Once we get RSS results back and show them in dialog, we need to show the feed url(in our case news url) and feed details(news details). The below styles are to simply show the url in yellowish-background and details in whitish-background.

.rsseg_sectionDiv{
background:#FFFFFF;
border-bottom:1px solid #A7A194;border-right:1px solid #A7A194;
}
.rsseg_HdrDiv{
background:#FFFF99;
border-bottom:1px solid #A7A194;border-right:1px solid #A7A194;
font-size:200%;
}


Main Javascript file (rssexample.js)

- This is the main file that does all the hard work.

We will start-off with writing a constructor. And make the object a "Zimlet" by subclassing it to ZmZimletBase()

function com_zimbra_rssexample() {
}

com_zimbra_rssexample.prototype = new ZmZimletBase();
com_zimbra_rssexample.prototype.constructor = com_zimbra_rssexample;
Jump to: navigation, search