Zimlet Developers Guide:Getting Started

1. Zimbra Tech Center
2. Community Sandbox
3. Zimlet Developers Guide:Getting Started

Zimlet Developers Guide: Getting Started

 - This is archive documentation, which means it is not supported or valid for recent versions of Zimbra Collaboration.

Introduction

Getting Started

Dev Environment Setup

Developing Zimlets

Advanced Concepts

API Specifications

Example Zimlets

This section provides instructions for creating and deploying a simple “Hello World!” zimlet. We will show you how to create and package your zimlet, two methods to deploy the zimlet (via Command Line and via Administration Console) and give solutions to common problems you might encounter.

Checklist

To write your first Zimlet, you will need:

• Zimbra Collaboration Suite (ZCS) 5.0 or later installed. ZCS is available for download at http://www.zimbra.com/downloads
• An IDE (like Eclipse or IntelliJ) or text editor. Most of the ZCS client code was written using IntelliJ IDEA

Creating your first Zimlet

Your first zimlet will be a Content Zimlet that simply displays the greeting “Hello World!” in context on the words “user” or “person”. The zimlet name will be "com_zimbra_helloworld".

1. Create a folder called /tmp/com_zimbra_helloworld.
2. In the newly created folder, create the Zimlet Definition file com_zimbra_helloworld.xml
3. Edit the file and add the following:

   <zimlet name="com_zimbra_helloworld" version="1.0" description="Hello World Zimlet">
        <contentObject>
            <matchOn>
                <regex attrs="ig"> user|person</regex> <!-- matches on the words user or person -->
            </matchOn>
            <toolTip>Hello World!</toolTip>
        </contentObject>
    </zimlet>
   

4. Save the file.
5. ZIP the zimlet folder contents into com_zimbra_helloworld.zip. This is the zimlet package. Be sure the zimlet file (not the folder) is the top-level content of the ZIP.

Deploying the Zimlet (via Command Line)

This section describes deploying the zimlet using the Zimbra Command Line tools. The alternative method is to deploy the zimlet via Administration Console.

1. Copy the zimlet ZIP file to your Zimbra server.
2. Login as zimbra user:

   su – zimbra
   

3. Run the following command to deploy your zimlet:

   zmzimletctl deploy /tmp/com_zimbra_helloworld.zip
   

4. You can check the status of the zimlet deployment in /opt/zimbra/log/mailbox.log.

Deploying the Zimlet (via Administration Console)

This section describes deploying the zimlet using the Zimbra Administration Console. The alternative method is to deploy the zimlet via Command Line tools.

1. Browse to the Zimbra Administration Console.
2. Login as the Zimbra administrator.
3. Navigate to the Zimlets section of the Console to manage zimlets.
4. Click “Deploy”.
5. Browse to the zimlet ZIP package file and click “Deploy”.
   
6. The zimlet will be in the zimlet list “Enabled”.
   

Seeing the Zimlet in Action

To see the zimlet in action, login to the Zimbra Web Client. Send yourself a message with the words “user” or “person” in the subject or message body and you’ll see the resulting “Hello World!” tooltip shown when you hover over the text.

Common Problems and Solutions

Problem	Zimlet fails to deploy and FileNotFoundException in {zcs-install-dir}/log/mailbox.log.
Summary	The Zimlet failed to deploy and the zimlet definition file {zimlet-name}.xml could not be found in the zimlet package.
Solution #1	Check that your zimlet ZIP package has the zimlet content at the top-level (i.e. directly in the ZIP).
Solution #2	Check that your zimlet name matches in the following locations: The name of the Zimlet Definition File {zimlet-name}.xml The Zimlet Definition File <zimlet> name parameter <zimlet name={zimlet-name}” ... > The Zimlet Package zip file is named {zimlet-name}.zip
Solution #3	If you create your zimlet ZIP archive on a Mac and use the "Compress" feature from the Mac UI, additional Mac-specific files (e.g. directory __MACOSX/*) are added to the ZIP. Either remove these files manually or use the "zip" command line utility instead of Compress.
Solution #4	Check that your zimlet name is all lower case. For example "com_zimbra_helloworld" is valid. "COM_zimbra_HelloWorld" is not.