Zimlet Developers Guide:Dev Environment Setup: Difference between revisions
Line 389: | Line 389: | ||
</li> | </li> | ||
<li>Save the file.</li> | <li>Save the file.</li> | ||
<li>Shutdown and restart the Zimbra Desktop. Right-click on the Zimbra Desktop tray icon and select "Shutdown Service". Browse to "Start > Programs > Zimbra Desktop > Zimbra Desktop" to restart.</li> | <li>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.</li> | ||
</ol> | </ol> | ||
Revision as of 03:53, 10 February 2010
![]() |
Introduction | ![]() |
Getting Started | ![]() |
Dev Environment Setup | ![]() |
Developing Zimlets | ![]() |
Advanced Concepts | ![]() |
API Specifications | ![]() |
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:
- Using Zimbra Desktop (ZD) as the development platform
- Using the Zimlet Development Directory (whether using ZCS or ZD as the development platform)
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
- Browse to the Zimbra Administration Console.
- Login as the Zimbra administrator.
- Navigate to the Zimlets section of the Console to manage zimlets.
- Click “Deploy”.
- Select your Zimlet ZIP package.
- The “Flush Zimlet Cache” clears existing zimlet settings during deploy. This box is recommended when upgrading a zimlet.
- Click “Deploy”.
Undeploying Zimlets via Administration Console
- Browse to the Zimbra Administration Console.
- Login as the Zimbra administrator.
- Navigate to the Zimlets section of the Console to manage zimlets.
- Select the zimlet to undeploy.
- Click “Undeploy”.
Deploying Zimlets via Command Line
- Login as zimbra user:
su – zimbra
- Run the following command to deploy your zimlet:
zmzimletctl deploy /tmp/{zimlet-package-name}.zip
- You can check the status of the zimlet deployment in
/opt/zimbra/log/mailbox.log
.
Undeploying Zimlets via Command Line
- Login as zimbra user:
su – zimbra
- 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. |
- Login as zimbra user:
su – zimbra
- 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.
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)
- Browse to the
{zd-install-dir}/config
directory. - Open the
log4j.properties
file for editing (for example, withnotepad.exe
). - Add the following line to the bottom of the file:
log4j.logger.zimbra.zimlet=DEBUG
- Save the file.
- 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)
- Browse to the
{zd-install-dir}/config
directory. - Open the
log4j.properties
file for editing (for example, withTextMate
). - Add the following line to the bottom of the file:
log4j.logger.zimbra.zimlet=DEBUG
- Save the file.
- 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 Zimbra Desktop (on Windows)
- Browse to the Zimbra Desktop install folder
- 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
- 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 Zimbra Desktop (on Windows)
- Browse to the Zimbra Desktop install folder
- 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
- 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 Zimbra Desktop (on MacOS)
- Browse to the Zimbra Desktop install folder.
- 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
- 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 Zimbra Desktop (on MacOS)
- Browse to the Zimbra Desktop install folder.
- 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
- Shutdown and restart the Zimbra Desktop Service. Run the following commands from the
{zd-install-dir}
:./zdesktop stop launchctl start com.zimbra.zdesktop
Limitations
Limitations when using ZD for development (vs. using ZCS) include:
- Command line tools (such as
zmprov
andzmzimletctl
) are not available to manage + deploy zimlets. - Tab Zimlets will not display.
Zimbra Desktop 2.0
The following section describes using Zimbra Desktop 2.0 for development.
- On Windows, you can select the install directory when running the installer. By default, the install directory is
c:\Program Files\zimbra\Zimbra Desktop
- On MacOS, the install directory for Zimbra Desktop 2.0 is
~/Library/Zimbra Desktop
.
Note: ZD2 is currently in Beta. This information is subject to change prior to release.
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)
- Edit the
{zd-install-dir}/data/jetty/etc/jetty.xml
file. - Find the port setting by searching for "jetty.port" string:
<Set name="port"><SystemProperty name="jetty.port" default="0"/></Set>
- Change the default value from "0" to the fixed port (for example "49163").
- Save the file.
- 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.
<Set name="port">49163</Set>
Setting a Fixed Port (on MacOS)
- Edit the
{zd-install-dir}/jetty/etc/jetty.xml
file. - Find the port setting by searching for "jetty.port" string:
<Set name="port"><SystemProperty name="jetty.port" default="0"/></Set>
- Change the default value from "0" to the fixed port (for example "49163").
- Save the file.
- Shutdown and restart the Zimbra Desktop Service by running the following commands from
{zd-install-dir}/bin
:./stop-zdesktop ./start-zdesktop
<Set name="port">49163</Set>
Zimlet Logging
Logs for Zimbra Desktop are found at {zd-install-dir}/log/zdesktop.log
. The following section describes how to turn on zimlet logging.
Turn on Zimlet Logging (on Windows)
- Browse to the
{zd-install-dir}/data/conf
directory. - Open the
log4j.properties
file for editing (for example, withnotepad.exe
). - Add the following line to the bottom of the file:
log4j.logger.zimbra.zimlet=DEBUG
- Save the file.
- 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)
- Browse to the
{zd-install-dir}/conf
directory. - Open the
log4j.properties
file for editing (for example, withTextMate
). - Add the following line to the bottom of the file:
log4j.logger.zimbra.zimlet=DEBUG
- Save the file.
- Shutdown and restart the Zimbra Desktop Service by running the following commands from
{zd-install-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
- To create the Development Directory, after installing ZCS, browse to your install directory:
{zcs-install-dir}/zimlets-deployed/
- Create a _dev directory:
mkdir {zcs-install-dir}/zimlets-deployed/_dev
- Use this directory to create zimlet folders and file structures for zimlet development.
Development Directory with Zimbra Desktop
- To create the Development Directory, after installing ZD, browse to your install directory:
{zd-install-dir}/jetty/webapps/service/zimlet
- Create a _dev directory:
mkdir {zd-install-dir}/jetty/webapps/service/zimlet/_dev
- 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. 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.