Zimlet Developers Guide:Developing Zimlets

Introduction

Getting Started

Dev Environment Setup

Developing Zimlets Proxy Servlet Setup Firefox and Firebug

API Specifications

Example Zimlets

Zimlet Files

This section describes the various resources and files that are part of a zimlet. A zimlet can include minimally an XML Zimlet Definition File (e.g. com_zimbra_test.xml). This is where zimlet information such as name and version are described.

File	Required / Optional	Description
{zimlet-name}.xml	Required	This is the Zimlet Definition file and specifies the zimlet behavior. This file is required for all zimlets. See Zimlet Definition File Reference for more information on the zimlet XML elements.
*.js	Optional	Supporting JavaScript (JS) files.
*.jsp	Optional	Supporting JSP files.
*.css	Optional	Supporting CSS files.
{zimlet-name}.properties	Optional	The resource properties for the zimlet. These resources are used for internationalizing and localizing zimlets.
config_template.xml	Optional	This is the Zimlet Configuration File and is is used to configure zimlet properties, such as "allowedDomains". See Zimlet Configuration File for more information. See Proxy Servlet Setup for more information on allowed domains.

Zimlet APIs

There are different API components in zimlet development. Based on the functionality you are trying to achieve, your zimlet implementation might leverage a combination of APIs.

XML API	The XML API is comprised of two separate pieces: Zimlet Definition File Zimlet Configuration File You can accomplish a lot with just the Definition File. For example, you can implement content zimlets, build context menus, make your zimlet appear as a panel items and in general, accomplish basic interactions with external services (via the <actionUrl> tag). But there are limits to how much customization and interaction with the Zimbra Web Client your zimlet can have. Also, there is limited debugging. For any zimlet that wants to present custom dialog boxes or advanced interactions with the Zimbra Web Client (e.g. inject buttons, make a zimlet application tab) That's when you start to leverage the JavaScript API with the XML API. All zimlets will, at minimum, have to include a basic Definition File. See the Zimlet Definition File Reference for more information on the zimlet XML elements and syntax.
JavaScript API	!!!Use the JavaScript API and XML API You can write some really complex Zimlets with relative ease (after all Zimbra is written in pure Javascript) Firebug provides you with world-class debugging power. You can still use the xml api for certain purposes like creating a panel item, context-menus etc. (ie a mix of the XML and JS apis)
SOAP API	!!!

XML APIs

Zimlet Definition File

This file defines the zimlet and is required for all zimlets. You can implement zimlet functionality directly in this file. It exposes very basic functionality and useful for simple content zimlets (e.g. you can define menu items, the zimlet panel interactions and simple URL actions). But beyond the basic, you will want to leverage the JavaScript API and the Zimlet Handler Object.

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

Zimlet Configuration File

The configuration file (config_template.xml) specifies properties for the zimlet configuration. Properties can be global or host specific. The properties may be accessed within the Zimlet Definition File using the "${}" syntax.

Property	Syntax	Example
To access global properties	${config.global.propertyName}	To access a global property named "defaultToGoogle", the syntax is ${config.global.defaultToGoogle}.
To access host-specific properties	${config.host.propertyName}	To access a host-specific property named "googleApi", the syntax is ${config.host.googleApi}.

Configuration properties are also available from the Zimlet Handler Object using the getConfigProperty() method.

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

JavaScript APIs

!!!

Zimlet Handler Object

!!!

SOAP APIs

!!!

Development Mode

When the Zimbra web client is loaded, the server consolidates (i.e. ZIPs) and obfuscates (i.e. unformats) all the JavaScript code in the application. This is to speed login and load time. Additionally, not all modules (for example, calendar, documents, etc) are loaded on initial login and modules are only loaded when needed (i.e. "lazy" loading). The combination of the consolidation, obfuscation and lazy loading makes it difficult to debug code in the browser.

For development and debugging, you can disable these activities and run the web client in "Development Mode" by appending a dev=1 to the client URL.

In this mode, all of the web client modules are loaded at login, all of the JavaScript is left un-consolidated and readable. Additionally, to further help with debugging, a debug-window pop-up is opened that shows all of the SOAP transactions as they occur between the web client browser and the server.

For example, append dev=1 to the client URL:

http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f&dev=1

Note: When you are developing zimlets with Development Mode ON, you should be sure to test your Zimlet with in regular mode (i.e. without &dev=1) to confirm the zimlet works properly. In some cases, your zimlet might depend modules being lazy loaded and you will have to write code to load the necessary modules.