Zimlet Developers Guide:Dev Environment Setup

Revision as of 20:52, 11 December 2009 by Sposetti (talk | contribs) (New page: {| cellspacing="0" cellpadding="5" style="border: 1px solid rgb(153, 153, 170); margin: 0pt 0.5em 0.5em 0pt; float: none; background-color: rgb(249, 249, 255);" |style="border-left: 1px so...)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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

This section provides an overview of the zimlet development process, discusses setting up your development environment (whether you plan to use Zimbra Collaboration Suite or Zimbra Desktop) and introduces the Zimlet Development Directory (which will help speed your zimlet development).

Zimlet Development Life Cycle Overview

Creation of a zimlet follows an iterative development life cycle through different environments: you design and Code, Package, Deploy, and Test the zimlet.

Code Package Deploy Test Repeat
During the coding phase, you are creating your zimlet. You will start with the Zimlet Definition File (XML) and might expand to include JavaScript and CSS files as well as other associated resources. The primary tools used during this phase are a text editor (or IDE like Eclipse). Since zimlets are very browser/client-side development focused, Mozilla Firefox browser with the Firebug Add-on is the recommended browser for it’s advanced HTML, DOM and JavaScript debugging capabilities. At this stage, you prepare your zimlet for deployment to Zimbra Collaboration Suite (ZCS). The assets and resources created during the Build stage are packaged into a ZIP. Packaging a zimlet can be done using tools such as the zip command library on Unix/Linux or WinZip on Windows. The zimlet package is deployed to ZCS, which can be accomplished via Zimbra Command Line tools or via the Zimbra Administration Console. Test your zimlet in the Zimbra Web Client interface.

Note: If you plan to have end-users on browsers other than Mozilla Firefox, be sure to test your zimlet with other browsers (such as Microsoft Internet Explorer or Safari).

Make code changes, package, deploy, and test...


During development of a zimlet, this process is done continuously by the Zimlet Developers. Developers continually are coding and testing their changes before being ready to make their zimlet available for production deployment. Developers might find while following process above that the time it takes to continually re-package and re-deploy your zimlet slows the iterative development process. Making any change, however small, requires you to re-create your zimlet ZIP package and un-deploy/re-deploy to ZCS.

There are mechanisms to help streamline the iterative development process and reduce (and eliminate) the amount of times you need to package and deploy your zimlet during development:

We discuss those mechanisms in more detail in the sections below.

Note: Even if you use these mechanisms during development, we still recommend you following the above development life cycle process before releasing your zimlet to production.


Using Zimbra Collaboration Suite for Development

You can deploy/undeploy zimlets from the Zimbra Administration Console. Additionally, ZCS includes command line tools to help with deploying, undeploying, flushing the zimlet cache, viewing the deployed zimlet list and modifying the proxy allowed domains.

Deploying Zimlets via Administration Console

  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. Select your Zimlet ZIP package.
  6. The “Flush Zimlet Cache” clears existing zimlet settings during deploy. This box is recommended when upgrading a zimlet.
  7. Click “Deploy”.

Undeploying Zimlets via Administration Console

  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. Select the zimlet to undeploy.
  5. Click “Undeploy”.

Deploying Zimlets via Command Line

  1. Login as zimbra user:
    su – zimbra
    
  2. Run the following command to deploy your zimlet:
    zmzimletctl deploy /tmp/{zimlet-package-name}.zip
    
  3. You can check the status of the zimlet deployment in /opt/zimbra/log/mailbox.log.

Undeploying Zimlets via Command Line

  1. Login as zimbra user:
    su – zimbra
    
  2. Run the following command to deploy your zimlet:
    zmzimletctl undeploy {zimlet-name}
    

List Available Zimlets via Command Line

You can list all available zimlets. Zimlets will be listed in three sections of the Zimbra deployment:

Section Description
Host Zimlets available on Host indicate all Zimlets that are installed but not necessarily deployed (i.e. registered in LDAP). These zimlets are physically present on the Host in {zcs-install-dir}/zimlets-deployed.
LDAP Shows the list of Zimlets that are registered in LDAP.
COS Shows the list of Zimlets that are turned ON.
  1. Login as zimbra user:
    su – zimbra
    
  2. Run the following command to deploy your zimlet:
    zmzimletctl listZimlets
    

Using Zimbra Desktop for Development

You can do zimlet development using Zimbra Desktop (ZD). Since ZD is a "mini-local" instance of Zimbra Collaboration Suite (ZCS), it's very similar to running & developing on ZCS. You will still want to deploy, test and run your zimlets on a ZCS server but ZD development is a quick-and-easy way to get started.

Accessing Zimbra Desktop via Browser

When using ZD for development, you'll need to run in a browser vs. the built-in Mozilla Prism container. To do this, launch ZD as you would normally, browse to Account Setup (found in the upper-right of the ZD interface). On the Account Setup page, there is a link in the bottom-right "open in a web browser". Save that link as a browser bookmark to get to your ZD instance anytime from a browser.

Limitations

There are some limitations when using ZD for development vs. ZCS. Those limitations include:

  • Command line tools (such as zmprov and zmzimletctl) are not available to manage + deploy zimlets.
  • Tab Zimlets will not display.

Deploying Zimlets on Zimbra Desktop (on Windows)

Manually

  1. Browse to the Zimbra Desktop install folder
  2. Run the following java command:
    java -cp {required-jar-files} -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy {directory-location-of-your-zimlet-package}\com_zimbra_helloworld.zip
    

    Note: Be sure to replace {directory-location-of-your-zimlet-package} with the directory where your zimlet package is located.

    Note: Be sure to replace {required-jar-files} with the following:

    jetty\lib\log4j-1.2.8.jar;jetty\common\lib\commons-httpclient-3.0.jar;jetty\common\lib\mail.jar;jetty\common\lib\commons-logging.jar;jetty\common\lib\commons-codec-1.3.jar;jetty\common\lib\json.jar;jetty\common\lib\dom4j-1.5.jar;jetty\common\lib\zimbracommon.jar;jetty\webapps\service\WEB-INF\lib\zimbrastore.jar
    

    The resulting command will look like:

    java -cp jetty\lib\log4j-1.2.8.jar;jetty\common\lib\commons-httpclient-3.0.jar;jetty\common\lib\mail.jar;jetty\common\lib\commons-logging.jar;jetty\common\lib\commons-codec-1.3.jar;jetty\common\lib\json.jar;jetty\common\lib\dom4j-1.5.jar;jetty\common\lib\zimbracommon.jar;jetty\webapps\service\WEB-INF\lib\zimbrastore.jar -Dzimbra.config=conf\localconfig.xml com.zimbra.cs.zimlet.ZimletUtil deploy C:\path\to\zimlet\package\com_zimbra_helloworld.zip
    
  3. Shutdown the Zimbra Desktop Service and restart it.

Via Zimlet Installer

  1. Download File:ZimletInstallerForWindows.zip and unzip to get ZimletInstallerForWindows.hta file
  2. Be sure Zimbra Desktop is running.
  3. Open Zimlet Installer.hta and browse to your Zimlet ZIP package file.
  4. Hit Deploy.

Undeploying Zimlets on Zimbra Desktop (on Windows)

  1. Browse to the Zimbra Desktop install folder
  2. Run the following java command:
    java -cp {required-jar-files} -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy {just-the-zimlet-name}
    

    Note: Be sure to replace {directory-location-of-your-zimlet-package} with the directory where your zimlet package is located.

    Note: Be sure to replace {required-jar-files} with the following:

    jetty\lib\log4j-1.2.8.jar;jetty\common\lib\commons-httpclient-3.0.jar;jetty\common\lib\mail.jar;jetty\common\lib\commons-logging.jar;jetty\common\lib\commons-codec-1.3.jar;jetty\common\lib\json.jar;jetty\common\lib\dom4j-1.5.jar;jetty\common\lib\zimbracommon.jar;jetty\webapps\service\WEB-INF\lib\zimbrastore.jar
    

    The resulting command will look like:

     
    java -cp jetty\lib\log4j-1.2.8.jar;jetty\common\lib\commons-httpclient-3.0.jar;jetty\common\lib\mail.jar;jetty\common\lib\commons-logging.jar;jetty\common\lib\commons-codec-1.3.jar;jetty\common\lib\json.jar;jetty\common\lib\dom4j-1.5.jar;jetty\common\lib\zimbracommon.jar;jetty\webapps\service\WEB-INF\lib\zimbrastore.jar -Dzimbra.config=conf\localconfig.xml com.zimbra.cs.zimlet.ZimletUtil undeploy com_zimbra_helloworld
    
  3. Shutdown the Zimbra Desktop Service and restart it.

Deploying Zimlets on Zimbra Desktop (on MacOS)

  1. Browse to the Zimbra Desktop install folder.
  2. Run the following java command to deploy, for example, a zimlet package named com_zimbra_helloworld.zip.
    java -cp {required-jar-files} -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy {directory-location-of-your-zimlet-package}/com_zimbra_helloworld.zip
    

    Note: Be sure to replace {directory-location-of-your-zimlet-package} with the directory where your zimlet package is located.

    Note: Be sure to replace {required-jar-files} with the following:

    jetty/lib/log4j-1.2.8.jar:jetty/common/lib/commons-httpclient-3.0.jar:jetty/common/lib/mail.jar:jetty/common/lib/commons-logging.jar:jetty/common/lib/commons-codec-1.3.jar:jetty/common/lib/json.jar:jetty/common/lib/dom4j-1.5.jar:jetty/common/lib/Zimbracommon.jar:jetty/webapps/service/WEB-INF/lib/Zimbrastore.jar
    

    The resulting command will look like:

    java -cp jetty/lib/log4j-1.2.8.jar:jetty/common/lib/commons-httpclient-3.0.jar:jetty/common/lib/mail.jar:jetty/common/lib/commons-logging.jar:jetty/common/lib/commons-codec-1.3.jar:jetty/common/lib/json.jar:jetty/common/lib/dom4j-1.5.jar:jetty/common/lib/Zimbracommon.jar:jetty/webapps/service/WEB-INF/lib/Zimbrastore.jar -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy /tmp/com_zimbra_helloworld.zip
    
  3. Shutdown the Zimbra Desktop Service and restart it.

Note: When the zimlet is deployed, the zimlet files are unzipped and copied to {zd-install-dir}/jetty/webapps/service/zimlet

Undeploying Zimlets on Zimbra Desktop (on MacOS)

  1. Browse to the Zimbra Desktop install folder.
  2. Run the following java command to undeploy, for example, a zimlet package named com_zimbra_helloworld.zip.
    java -cp {required-jar-files} -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy {just-the-zimlet-name}
    

    Note: Be sure to replace {required-jar-files} with the following:

    jetty/lib/log4j-1.2.8.jar:jetty/common/lib/commons-httpclient-3.0.jar:jetty/common/lib/mail.jar:jetty/common/lib/commons-logging.jar:jetty/common/lib/commons-codec-1.3.jar:jetty/common/lib/json.jar:jetty/common/lib/dom4j-1.5.jar:jetty/common/lib/Zimbracommon.jar:jetty/webapps/service/WEB-INF/lib/Zimbrastore.jar
    

    Example:

    java -cp jetty/lib/log4j-1.2.8.jar:jetty/common/lib/commons-httpclient-3.0.jar:jetty/common/lib/mail.jar:jetty/common/lib/commons-logging.jar:jetty/common/lib/commons-codec-1.3.jar:jetty/common/lib/json.jar:jetty/common/lib/dom4j-1.5.jar:jetty/common/lib/Zimbracommon.jar:jetty/webapps/service/WEB-INF/lib/Zimbrastore.jar -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy '''com_zimbra_helloworld'''
    
  3. Shutdown the Zimbra Desktop Service and restart it.

Zimlet Development Directory

The Zimlet Development Directory is a convenient way to do iterative zimlet development. The development directory allows you to develop zimlets without having to continually package (i.e. ZIP), deploy and undeploy the zimlet.

You can create zimlet folders and associated file structures under the _dev directory and those zimlets will get picked-up (and recompiled) with each browser refresh. File changes made to the zimlet files in this directory will be automatically reflected when the browser is refreshed. Additionally, files are not obfuscated and merged with other Zimlet files and JSP files can be placed within the zimlet folder and will be compiled every time browser is refreshed.

Development Directory with Zimbra Collaboration Suite

  1. To create the Development Directory, after installing ZCS, browse to your install directory:
    {zcs-install-dir}/zimlets-deployed/
    
  2. Create a _dev directory:
    mkdir {zcs-install-dir}/zimlets-deployed/_dev
    
  3. Use this directory to create zimlet folders and file structures for zimlet development.

Development Directory with Zimbra Desktop

  1. To create the Development Directory, after installing ZD, browse to your install directory:
    {zd-install-dir}/jetty/webapps/service/zimlet
    
  2. Create a _dev directory:
    mkdir {zd-install-dir}/jetty/webapps/service/zimlet/_dev
    
  3. Use this directory to create zimlet folders and file structures for zimlet development.

Allowed Domains Limitation when using the Development Directory

Zimlet Configuration File (config_template.xml) settings for "allowedDomains" are picked up on zimlet deployment. When using the Development Directory, zimlets are not formally deployed so this "allowedDomains" setting is not read. Therefore, when using the Development Directory, open the required domain(s) for your zimlet. One method to open domains while in development is to deploy an "openAllDomains" zimlet.

See the "Proxy Servlet Setup" section for more information about accessing external sites via JavaScript from your zimlets.

Jump to: navigation, search