Zimlet Developers Guide:Introduction

Revision as of 21:07, 11 December 2009 by Sposetti (talk | contribs)
Zdg-6-menu-icon-zimbra.jpg Introduction Zdg-6-menu-icon-green-flag.png Getting Started Zdg-6-menu-icon-terminal.png Dev Environment Setup Zdg-6-menu-icon-gear.png Developing Zimlets Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets

Welcome to the Zimlet Developer's Guide which provides instructions on how to create Zimlets for the Zimbra Collaboration Suite server.

Zimlets makes it easy to customize and extend Zimbra to suit your needs, allowing you to add new features to suit your particular requirements. Zimlets are a mechanism for integrating with and extending the functionality of Zimbra Collaboration Suite (ZCS) and Zimbra Desktop (ZD).

Zimlets enable the "mash-up" of Web 2.0 technologies with enterprise messaging (e.g. email, IM, voice) and collaboration systems. With Zimlets, message content and collaboration objects can be made live by dynamically linking to web content and third-party services.

This guide will show you how to set up your development environment, create a basic Zimlet and learn the principles of building, debugging and deploying a Zimlet.


Documentation Conventions

The UNIX convention of "/" as a path separator is used wherever necessary. Also, portions of the command syntax displayed in this document may include sample parameters or variables that represent the actual command syntax you would need to enter. These entries are indicated by parameters in lowercase placed between curly braces {parameter}, as shown in the following table.

Parameter Definition
{zimlet-name} The name of the zimlet.

For example, com_zimbra_helloworld.

{zimlet-package-name} The name of the zimlet package. This is a combination of {zimlet-name} + .zip.

For example, com_zimbra_helloworld.zip.

{zcs-install-dir} The install directory of Zimbra Collaboration Suite (ZCS).

For example, /opt/zimbra.

{zd-install-dir} The install directory of Zimbra Desktop (ZD).

For example, /Users/testuser/zimbra/zdesktop.


Zimlet Terminology

The following sectipon describes some of the basic terminology of zimlets and zimlet development:

Term Description
Zimlet Name This is the name of the zimlet. The zimlet name is used to uniquely identify a zimlet. The name is a very important piece of a zimlet since it is also the name of the Zimlet Package and Zimlet Definition File.

Reverse domain name is a recommended convention for naming your zimlets. This helps create unique zimlet names, particularly if the zimlets are distributed outside of your organization. Reverse domain naming means that you start your zimlet name with the reverse of your organization domain name. For example, for zimbra, our domain is zimbra.com. Therefore, we start all our zimlets with the name com_zimbra_ (reversing the domain and replacing the periods "." with underscores "_".

Note: The Zimlet Name should be all lowercase characters, no special characters (e.g. [{}]/\*&#$@!), dash and underscore are allowed (e.g. - and _), numbers are allowed.

Zimlet Package This is the ZIP file package that contains all zimlet resources and files. This is sometimes referred to as the Zimlet Bundle. The Zimlet Package is named as the {zimlet-name} + zip. For example, a zimlet named "com_zimbra_helloworld" would have a Zimlet Package of com_zimbra_helloworld.zip.
Zimlet Definition File This is the core file of the zimlet. It provides the name, version and description of the zimlet and is used to manage the resources and functionality of the zimlet. This file is also the core of the Zimlet XML API.

See Zimlet APIs for more information on the XML API and as well as all Zimlet APIs.

See Zimlet Definition File for more information on the Zimlet Definition File.

See Zimlet Definition File Reference for more information on the Zimlet Definition File XML elements and syntax.

Zimlet Configuration File

The configuration file specifies configuration properties for the zimlet. Properties can be global or host-specific.

See Zimlet Configuration File for more information on the Zimlet Configuration File.

See Zimlet Configuration File Reference for more information on the Zimlet Configuration File XML elements and syntax.

JavaScript ("JS") JavaScript is the primary language zimlets are written in. You don’t need to be a master of JS but you should understand the fundamentals (like functions and classes).

This is a good website to learn basics of JS:

These sites provide information the basics of Object Oriented JS:

Proxy Servlet The Proxy Servlet is used to make calls to external servers and services from the zimlet via JS. See Proxy Servlet Setup for more information.
Zimlet Handler Object This is the core JavaScript object of a zimlet. When developing your zimlet, your Handler Object will be called when application events happen, which will enable you to interact with the Zimbra client interface and implement your zimlet functionality. See Zimlet Handler Object for more information.

Types of Zimlets

Zimlets can support diferent types of functionality. And can be integrated into the Zimbra client interface in different ways. This section will describe the types of zimlets.

Content Zimlets

Content Zimlets are the simplest type of zimlet (sometimes referred to as “Inline Zimlets”). Content Zimlets allow you to inject functionality directly in context with Zimbra collaboration objects. Using regular expressions, certain content areas of the Zimbra user interface are parsed and links are added to the content that will call the Zimlet. The areas parsed by Content Zimlets are:

  • The “Subject” and “Body” properties of an email (note: in both the Read Message page and Reading pane).
  • The “Notes” property of a contact.

Content Zimlets can responds to different click events (such a single or right-click) and generate menu items.

Extension Zimlets

Extension Zimlets allow you to extend the functionality the Zimbra client interface even further. You can have zimlets that surface in the zimlet panel list or the application tab. Depending on how advanced you want to make your zimlet, you can even integrate directly into menu lists and Zimbra interface dialog buttons.

Panel Zimlets

Panel Zimlets display your zimlet in the Zimlets panel on the lower-left of the Zimbra client interface. These zimlets can respond to different events such as single/double/right-clicks and object drops.

Zdg-6-panel-zimlets.png

Tab Zimlets

Tab Zimlets construct new application tabs in the Zimbra client interface menu bar.

Zdg-6-tab-zimlets.png

Integrated Zimlets

Integrated Zimlets allow you to tie directly into features of the Zimbra client interface. For example, you can hook into the existing menus and toolbars, or even entire areas of the interface (like the mini-calendar area on the Mail main page), to add or change the behavior of functionality.

Zdg-6-integrated-zimlets.png


Useful Links

Some useful "quick links" around this document:

Link Description
Zimlet Definition File Reference Describes the Zimlet Definition File XML syntax
Example Zimlets Example zimlets + code
Jump to: navigation, search