Zimlet Developers Guide:Dev Environment Setup

From Zimbra :: Wiki

Jump to: navigation, search
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-advanced.jpg Advanced Concepts Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets


Developer Article

Article Information

This article applies to the following ZCS versions.
  ZCS 8.0 Article  ZCS 8.0
  ZCS 7.0 Article  ZCS 7.0
  ZCS 6.0 Article  ZCS 6.0


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).

Contents

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.

Note: Limitations for using ZD (vs. using ZCS) for zimlet development include:

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

Zimbra Desktop 1.0

The following section describes using Zimbra Desktop 1.0 for development.

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.

Zimlet Logging

Logs for Zimbra Desktop are found at {zd-install-dir}/logs/zdesktop.log. The following section describes how to turn on zimlet logging.

Turn on Zimlet Logging (on Windows)
  1. Browse to the {zd-install-dir}/config directory.
  2. Open the log4j.properties file for editing (for example, with notepad.exe).
  3. Add the following line to the bottom of the file:
    log4j.logger.zimbra.zimlet=DEBUG
    
  4. Save the file.
  5. Shutdown and restart the Zimbra Desktop Service. Browse to "Settings > Control Panel > Administrative Tools > Services" to stop and then start the "Zimbra Desktop Service".
Turn on Zimlet Logging (on MacOS)
  1. Browse to the {zd-install-dir}/config directory.
  2. Open the log4j.properties file for editing (for example, with TextMate).
  3. Add the following line to the bottom of the file:
    log4j.logger.zimbra.zimlet=DEBUG
    
  4. Save the file.
  5. Shutdown and restart the Zimbra Desktop Service by running the following commands from the {zd-install-dir}:
    ./zdesktop stop
    launchctl start com.zimbra.zdesktop
    

Deploying Zimlets (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 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 and restart the Zimbra Desktop Service. Browse to "Settings > Control Panel > Administrative Tools > Services" to stop and then start the "Yahoo! Zimbra Desktop Service".

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

Undeploying Zimlets (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 and restart the Zimbra Desktop Service. Browse to "Settings > Control Panel > Administrative Tools > Services" to stop and then start the "Yahoo! Zimbra Desktop Service".

Deploying Zimlets (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 and restart the Zimbra Desktop Service. Run the following commands from the {zd-install-dir}:
    ./zdesktop stop
    launchctl start com.zimbra.zdesktop
    

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

Undeploying Zimlets (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 and restart the Zimbra Desktop Service. Run the following commands from the {zd-install-dir}:
    ./zdesktop stop
    launchctl start com.zimbra.zdesktop
    

Zimbra Desktop 2.0

The following section describes using Zimbra Desktop 2.0 Beta 3 for development.

Note: ZD2 is currently in Beta. This information is subject to change prior to release.

Install Directory

On Windows:

  • Install directory {zd-install-dir} can be chosen during install time and defaults to c:\Program Files\Zimbra\Zimbra Desktop
  • User data directory {zd-user-dir} is at c:\Documents and Settings\{user}\Local Settings\Application Data\Zimbra\Zimbra Desktop

On MacOS:

  • Install directory {zd-install-dir} can be chosen during install time and defaults to /Applications/Zimbra Desktop
  • User data directory {zd-user-dir} is at ~/Library/Zimbra Desktop

Accessing Zimbra Desktop via Browser

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

By default, ZD2 will select & run on a random, unused port on your machine. When doing development, it's easiest to save this link as a browser bookmark to get to your ZD instance anytime from a browser. But because of the random port number, the link is subject to change (which can happen at service and machine restarts). Each time you want to run ZD2 in a browser, to determine the correct port, you can launch ZD2, browse to Account Setup & "open in a web browser" page to obtain the latest link (with the latest port).

Setting a Fixed Port (on Windows)
  1. Edit the {zd-user-dir}/jetty/etc/jetty.xml file.
  2. Find the port setting by searching for "jetty.port" string:
    <Set name="port"><SystemProperty name="jetty.port" default="0"/></Set>
    
  3. Change the default value from "0" to the fixed port (for example "49163").
  4. <Set name="port">49163</Set>
    
  5. Save the file.
  6. Shutdown and restart the Zimbra Desktop service. Right-click on the Zimbra Desktop tray icon and select "Shutdown Service". Browse to "Start > Programs > Zimbra Desktop > Zimbra Desktop" to restart.
Setting a Fixed Port (on MacOS)
  1. Edit the {zd-user-dir}/jetty/etc/jetty.xml file.
  2. Find the port setting by searching for "jetty.port" string:
    <Set name="port"><SystemProperty name="jetty.port" default="0"/></Set>
    
  3. Change the default value from "0" to the fixed port (for example "49163").
  4. <Set name="port">49163</Set>
    
  5. Save the file.
  6. Shutdown and restart the Zimbra Desktop Service by running the following commands from {zd-user-dir}/bin:
    ./stop-zdesktop
    ./start-zdesktop
    
Setting a Fixed Port (on Linux)
  1. Edit the {zd-user-dir}/jetty/etc/jetty.xml file.
  2. Find the port setting by searching for "jetty.port" string:
    <Set name="port"><SystemProperty name="jetty.port" default="0"/></Set>
    
  3. Change the default value from "0" to the fixed port (for example "49163").
  4. <Set name="port">49163</Set>
    
  5. Save the file.
  6. Shutdown and restart the Zimbra Desktop Service by running the following commands from {zd-user-dir}/bin:
    ./zdesktop stop
    ./zdesktop start
    

Deploying Zimlets (on Windows)

  1. Copy your Zimlet package ZIP file to the zimlets directory at {zd-user-dir}/zimlets.
  2. Shutdown and restart the Zimbra Desktop service. Right-click on the Zimbra Desktop tray icon and select "Shutdown Service". Browse to "Start > Programs > Zimbra Desktop > Zimbra Desktop" to restart.

Deploying Zimlets (on MacOS)

  1. Copy your Zimlet package ZIP file to the zimlets directory at {zd-user-dir}/zimlets.
  2. Shutdown and restart the Zimbra Desktop Service by running the following commands from {zd-user-dir}/bin:
    ./stop-zdesktop
    ./start-zdesktop
    

Zimlet Logging

Logs for Zimbra Desktop are found at {zd-user-dir}/log/zdesktop.log. The following section describes how to turn on zimlet logging.

Turn on Zimlet Logging (on Windows)
  1. Browse to the {zd-user-dir}/conf directory.
  2. Open the log4j.properties file for editing (for example, with notepad.exe).
  3. Add the following line to the bottom of the file:
    log4j.logger.zimbra.zimlet=DEBUG
    
  4. Save the file.
  5. Shutdown and restart the Zimbra Desktop service. Right-click on the Zimbra Desktop tray icon and select "Shutdown Service". Browse to "Start > Programs > Zimbra Desktop > Zimbra Desktop" to restart.
Turn on Zimlet Logging (on MacOS)
  1. Browse to the {zd-user-dir}/conf directory.
  2. Open the log4j.properties file for editing (for example, with TextMate).
  3. Add the following line to the bottom of the file:
    log4j.logger.zimbra.zimlet=DEBUG
    
  4. Save the file.
  5. Shutdown and restart the Zimbra Desktop Service by running the following commands from {zd-user-dir}/bin:
    ./stop-zdesktop
    ./start-zdesktop
    

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.0

  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.

Development Directory with Zimbra Desktop 2.0

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

Note: ZD2 is currently in Beta. This information is subject to change prior to release.

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. The Open All Domains zimlet is provided as an example.

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


Verified Against: Zimbra Collaboration Server 7.0 Date Created: 12/22/2009
Article ID: http://wiki.zimbra.com/index.php?title=Zimlet_Developers_Guide:Dev_Environment_Setup Date Modified: 04/11/2014
Personal tools