Difference between revisions of "ZimletDevSetup"

Line 1: Line 1:
 
== '''Zimlet Development Via Zimbra Desktop''' ==
 
== '''Zimlet Development Via Zimbra Desktop''' ==
 
------------------------------------
 
------------------------------------
'''Zimbra Desktop Configuration'''
+
 
 +
== '''Zimbra Desktop Configuration''' ==
 +
 
 
------------------------------------
 
------------------------------------
 
1. Download Zimbra Desktop
 
1. Download Zimbra Desktop
Line 37: Line 39:
 
5. Restart Zimbra Desktop (Right click on system tray icon and click ShutDown Service, and then start Zimbra Desktop again)
 
5. Restart Zimbra Desktop (Right click on system tray icon and click ShutDown Service, and then start Zimbra Desktop again)
  
 +
 +
 +
 +
 +
== DEVELOPMENT HACKS or TIPS ==
 +
'''Use these to get yourself up-and-running with Zimlet development (via Zimbra Desktop) in no-time'''
 +
 +
 +
-----------------------------
 +
'''Hack #1  Create _dev folder:'''
 +
-----------------------------
 +
* When the Zimlet is deployed, its copied to''' zdesktop\jetty\webapps\service\Zimlet''' and needs the above mentioned deploy-restart-service-undeploy for every small change. But for development we can circumvent this by creating a folder called "_dev" under service\Zimlet\ folder and manually copying and developing Zimlet within that folder until its fully done and production ready.
 +
 +
Say you are developing a Zimlet com_Zimbra_test,
 +
 +
#First navigate and create a _dev directory like below:
 +
  <Zimbra Desktop install directory aka zdesktop>\jetty\webapps\service\Zimlet\
 +
#Then, create the Zimlet folder within _dev
 +
<Zimbra Desktop install directory aka zdesktop>\jetty\webapps\service\Zimlet\_dev\com_Zimbra_test
 +
 +
 +
 +
 +
----------------------------------------------------------
 +
'''Hack #2 Use Zimbra Desktop as a web-application'''
 +
----------------------------------------------------------
 +
Zimbra desktop uses Prism which is essentially Firefox. And it also provides a way to open it via a browser. This means we can use the powerful Firebug
 +
for debugging!
 +
Setup:
 +
# Open Zimbra Desktop
 +
# Click on Account Setup
 +
# Click on Open in Web-Browser Link. (PS: if it opens in IE, copy that link to Firefox since we need Firebug)
 +
# Click on Launch Application (you need the url ''after'' you logged in)
 +
# Bookmark the url; its going to look something like:
 +
<pre>
 +
http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f#1
 +
 +
PS: Remove the last #1(or you might see #2 or #3) at the very end during bookmarking to make it..
 +
http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f
 +
</pre>
 +
 +
 +
 +
 +
----------------------------------------------------------
 +
'''Hack #3 dev=1  the developer mode'''
 +
----------------------------------------------------------
 +
When Zimbra is loaded it zips and and unformats all the javascript code to speedup the login time. Also, it doesnt load all the modules(like calendar, documents etc) and loads them only when needed(aka 'lazy' loading). Finally, Zimbra also has a built-in debugger-window and is also disabled in non-debug mode.
 +
However, For developement and debugging purposes Zimbra provides a developer mode. You can turn-on this mode by simply appending '''dev=1''' to the launch-url. In this mode, all the modules are loaded-upfront, all the javascript code are readable, and you will also see debug-window.
 +
Now open the bookmark you made earlier(in hack #2) and append dev=1
 +
<pre>
 +
http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f&dev=1
 +
</pre>
 +
 +
Obviously, you can have two bookmarks, one with debug on and the other with off.
 +
 +
''One more important note:'' When you develop Zimlets in debug-mode ON, as  mentioned earlier, you will have to test your Zimlet with ''non-debug mode (without &dev=1'' to make sure it still works with lazy loading. In some cases, it wont since your Zimlet might depend on some module being loaded and you will have to write code to load some missing modules and such issues
 +
 +
 +
 +
----------------------------------------------------------
 +
'''Hack #4 Proxy Hack'''
 +
----------------------------------------------------------
 +
PS: This is for accessing external sites directly from javascript (you don't need this if jsp was used)
 +
 +
Whenever you access external site(say *.yahoo.com) you need to tell(register in ldap) the backend-server that yahoo.com is OK to access. i.e. we need to set allowedDomains parameter in config_template.xml for that domain and actually *deploy* the zimlet. Now, in _dev, we dont really deploy the zimlet but simply use a server hack to make it work and so the allowedDomains isn't registered in ldap.
 +
But, if we deploy the zimlet, then we can't keep it in _dev since it would duplicate zimlets, i.e you will see 2 instances of the zimlets. So, what I normally do is to create a dummy-zimlet (com_zimbra_test) and in that I allow ALL domains( "*" instead of "*.yahoo.com")and deploy that. Since allowedDomains property is a global property, its then applicable for all the zimlets I develop.
 +
 +
So deploy the  com_zimbra_openalldomains.zip zimlet only on your test-box so that you can use any zimlets _dev that might need to access external websites via Javascript.
 +
 +
This zimlet has a config_template.xml file that has the following:
 +
 +
<zimletConfig name="com_zimbra_openalldomains" version="1.0">
 +
    <global>
 +
        <property name="allowedDomains">*</property>
 +
    </global>
 +
</zimletConfig>
 +
 +
PS: When the zimlet goes to production, it needs to have its *own* config_template.xml file that opens-up only required domain, something like
 +
 +
<zimletConfig name="com_zimbra_myzimlet" version="1.0">
 +
    <global>
 +
        <property name="allowedDomains">rss.news.yahoo.com</property>
 +
    </global>
 +
</zimletConfig>
 +
 +
 +
 +
 +
----------------------------------------------------------
 +
'''Hack #5 Firebug & debugging tips'''
 +
----------------------------------------------------------
 +
Firebug is perhaps world's best javascript debugging tool out there. Download it and enable every setting it, you will use everything during the course of the Zimlet development.
 +
http://getfirebug.com/
 +
 +
 +
1. '''debugger;''' statement.
 +
This is perhaps the most convenient thing within Firebug. Simply write that statement anywhere and javascript execution halts there.
 +
 +
com_Zimbra_test.prototype.function =
 +
function() {
 +
  var i =0;
 +
  debugger;  //javascript halts right on this line
 +
  doSomethingWith(i);
 +
}
 +
 +
2. The other thing that helps is...
 +
'''console.log(someVariable);''' //this some variable is printed in Firebug's log
 +
 +
3. more information can be found here:
 +
http://getfirebug.com/logging.html
 +
 +
 +
 +
----------------------------------------------------------
 +
'''Hack #6 Firebug Net(network) tab'''
 +
----------------------------------------------------------
 +
When accessing services the two common errors we get are are 403 and 500. In firebug, you can easily debug these and many other http errors using Net or network tab.
 +
# '''Error 403''' == permission denied; or access it not allowed and
 +
# '''Error 500''' == your request is incorrect; i.e.the url or some parameter isnt properly formatted or constructed
 +
 +
'''Notes:'''
 +
Of course, apart from debugging errors, you can also see soap-requests and soap-responses and all the network traffic.
 +
 +
 +
 +
----------------------------------------------------------
 +
'''Hack #7 Firefox Settings'''
 +
----------------------------------------------------------
 +
Everytime we load Zimlets in browser it caches in the browser. To make sure we dont cache but still keep cookies and authtokens, perform the following configuration settings.
 +
 +
 +
# Open Firefox's > Tools > Options > Privacy
 +
# Click on Settings
 +
# Check Cache
 +
# Uncheck Authenticated Sessions
 +
# Uncheck cookies
 +
# Press OK
 +
# Also Check "Always clear my private data when i close firefox". This will help in clearing cache whenever we press Refresh.
 +
# Finally, Uncheck Ask me before Clearing private data, you  most likely dont want it to keep asking your permission.
  
  
Line 42: Line 184:
  
 
------------------------------------
 
------------------------------------
'''Deploying and undeploying Production-level Zimlets'''  
+
 
 +
== '''Deploying and undeploying 'Production-level' Zimlets''' ==
 +
 
------------------------------------
 
------------------------------------
  
PS: ''only production level Zimlets that are ready-to-go. For Zimlet development, see "DEVELOPMENT HACKS or TIPS" section below''
+
PS: ''only for production level Zimlets that are ready-to-go for actual deployment. For Zimlet that are under construction, see "DEVELOPMENT HACKS or TIPS" section''
  
  
Line 58: Line 202:
 
# CD to 'zdesktop' folder (the following command is relative to zdesktop)
 
# CD to 'zdesktop' folder (the following command is relative to zdesktop)
 
# Run the following java command...
 
# Run the following java command...
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy '''<PATH to Zimlet.zip file>\com_Zimbra_hello.zip'''
 
 
<pre>
 
<pre>
 +
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy <PATH to Zimlet.zip file>\com_Zimbra_hello.zip
 +
</pre>
 +
<pre>
 +
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 deploy C:\path\to\zimletZipfile\com_Zimbra_hello.zip
 
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\zimletZipfile\com_Zimbra_hello.zip
 
</pre>
 
</pre>
Line 73: Line 220:
  
 
Notes:  
 
Notes:  
# When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet folder.  
+
* When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet folder.  
# This will deploy the Zimlet and restarts Zimbra Desktop Service
+
* This will deploy the Zimlet and restarts Zimbra Desktop Service
# You should see Zimlet after the restart.
+
* You should see Zimlet after the restart.
# All Production Zimlets needs to be *deployed* and needs a restart. While developing a Zimlet however we will use _dev folder which
+
* All Production Zimlets needs to be *deployed* and needs a restart. While developing a Zimlet however we will use _dev folder which
 
would over-come this.
 
would over-come this.
  
Line 82: Line 229:
 
# CD to 'zdesktop' folder (the following command is relative to zdesktop)
 
# CD to 'zdesktop' folder (the following command is relative to zdesktop)
 
# Run the following command.  
 
# Run the following command.  
 +
<pre>
 
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
 
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
<pre>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 C:\path\to\zimletZipfile\com_Zimbra_hello.zip
+
</pre>
 +
<pre>
 +
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 C:\path\to\zimletZipfile\com_Zimbra_hello.zip
 
</pre>
 
</pre>
 
# Shutdown Zimbra Service
 
# Shutdown Zimbra Service
Line 93: Line 244:
 
# Open Zimlet Installer.hta and enter Zimlet's handler name like: ''com_Zimbra_test'' (without .zip) in the undeploy field
 
# Open Zimlet Installer.hta and enter Zimlet's handler name like: ''com_Zimbra_test'' (without .zip) in the undeploy field
 
# Hit UnDeploy
 
# Hit UnDeploy
## this will UnDeploy the Zimlet and restarts Zimbra Desktop Service
+
* This will UnDeploy the Zimlet and restarts Zimbra Desktop Service
## You should see Zimlet go away after the restart.
+
* You should see Zimlet go away after the restart.
  
  
Line 100: Line 251:
  
 
Notes:  
 
Notes:  
# There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.
+
* There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.
  
  
Line 112: Line 263:
 
# CD to zdesktop install folder
 
# CD to zdesktop install folder
 
# Run the following java command...
 
# Run the following java command...
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy '''<PATH to Zimlet.zip file>/com_Zimbra_hello.zip'''
+
<pre>
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 deploy ~/Y/Zimlets/com_Zimbra_hello.zip
+
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy <PATH to Zimlet.zip file>/com_Zimbra_hello.zip
 
+
</pre>
 +
<pre>
 +
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 deploy ~/Y/Zimlets/com_Zimbra_hello.zip
 +
</pre>
 
# Shutdown Zimbra Desktop Service and Start it
 
# Shutdown Zimbra Desktop Service and Start it
  
  
 
Notes:  
 
Notes:  
# When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet.
+
* When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet.
  
  
  
 
'''Undeploy Zimlet:'''
 
'''Undeploy Zimlet:'''
1. CD to zdesktop install folder
+
# CD to zdesktop install folder
 
+
# Run the following command..
2. java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
+
<pre>
 +
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
 +
</pre>
 +
<pre>
 +
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_hello
 
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_hello
 
Note: For undeploying just use the Zimlet-handler-name (not the path and also dont include .zip)
 
Note: For undeploying just use the Zimlet-handler-name (not the path and also dont include .zip)
 +
</pre>
 +
# Shutdown Zimbra Desktop Service and start it
  
3. Shutdown Zimbra Desktop Service and start it
+
Notes:
PS: There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.
+
* There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.
  
  

Revision as of 21:25, 10 March 2009

Zimlet Development Via Zimbra Desktop


Zimbra Desktop Configuration


1. Download Zimbra Desktop http://www.Zimbra.com/products/desktop_download.html

2. Install Zimbra desktop to C:\zdesktop or some easy to reach location.

3. Configure your Zimbra Desktop with a dummy/test gmail or yahoo account.

(PS: Steps 4 & 5 can be skipped once Zimbra Desktop goes RC2(build 1513) or later, currently it is RC1(build 1482)

4. Configure Zimbra Desktop to permit Zimlets

Open localconfig.xml in <installDirectory>\conf\localconfig.xml

And replace..

 <key name="zdesktop_installation_key">
   <value>[CURRENT_VALUE]</value>
 </key>


 with..
 <key name="zdesktop_installation_key">
   <value>[CURRENT_VALUE]</value>
 </key>
 <key name="Zimbra_ldap_password">
   <value>[CURRENT_VALUE]</value>
 </key>

.. [CURRENT_VALUE] is whatever key Zimbra Desktop generated and should be same for both "zdesktop_installation_key" and "Zimbra_ldap_password"


5. Restart Zimbra Desktop (Right click on system tray icon and click ShutDown Service, and then start Zimbra Desktop again)



DEVELOPMENT HACKS or TIPS

Use these to get yourself up-and-running with Zimlet development (via Zimbra Desktop) in no-time



Hack #1 Create _dev folder:


  • When the Zimlet is deployed, its copied to zdesktop\jetty\webapps\service\Zimlet and needs the above mentioned deploy-restart-service-undeploy for every small change. But for development we can circumvent this by creating a folder called "_dev" under service\Zimlet\ folder and manually copying and developing Zimlet within that folder until its fully done and production ready.

Say you are developing a Zimlet com_Zimbra_test,

  1. First navigate and create a _dev directory like below:
 <Zimbra Desktop install directory aka zdesktop>\jetty\webapps\service\Zimlet\
  1. Then, create the Zimlet folder within _dev

<Zimbra Desktop install directory aka zdesktop>\jetty\webapps\service\Zimlet\_dev\com_Zimbra_test




Hack #2 Use Zimbra Desktop as a web-application


Zimbra desktop uses Prism which is essentially Firefox. And it also provides a way to open it via a browser. This means we can use the powerful Firebug for debugging! Setup:

  1. Open Zimbra Desktop
  2. Click on Account Setup
  3. Click on Open in Web-Browser Link. (PS: if it opens in IE, copy that link to Firefox since we need Firebug)
  4. Click on Launch Application (you need the url after you logged in)
  5. Bookmark the url; its going to look something like:
http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f#1

PS: Remove the last #1(or you might see #2 or #3) at the very end during bookmarking to make it..
http://localhost:7633/Zimbra/desktop/login.jsp?at=4343c072e-8f566-4af9-8acb-1656046bd230f




Hack #3 dev=1 the developer mode


When Zimbra is loaded it zips and and unformats all the javascript code to speedup the login time. Also, it doesnt load all the modules(like calendar, documents etc) and loads them only when needed(aka 'lazy' loading). Finally, Zimbra also has a built-in debugger-window and is also disabled in non-debug mode. However, For developement and debugging purposes Zimbra provides a developer mode. You can turn-on this mode by simply appending dev=1 to the launch-url. In this mode, all the modules are loaded-upfront, all the javascript code are readable, and you will also see debug-window. Now open the bookmark you made earlier(in hack #2) and append dev=1

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

Obviously, you can have two bookmarks, one with debug on and the other with off.

One more important note: When you develop Zimlets in debug-mode ON, as mentioned earlier, you will have to test your Zimlet with non-debug mode (without &dev=1 to make sure it still works with lazy loading. In some cases, it wont since your Zimlet might depend on some module being loaded and you will have to write code to load some missing modules and such issues



Hack #4 Proxy Hack


PS: This is for accessing external sites directly from javascript (you don't need this if jsp was used)

Whenever you access external site(say *.yahoo.com) you need to tell(register in ldap) the backend-server that yahoo.com is OK to access. i.e. we need to set allowedDomains parameter in config_template.xml for that domain and actually *deploy* the zimlet. Now, in _dev, we dont really deploy the zimlet but simply use a server hack to make it work and so the allowedDomains isn't registered in ldap. But, if we deploy the zimlet, then we can't keep it in _dev since it would duplicate zimlets, i.e you will see 2 instances of the zimlets. So, what I normally do is to create a dummy-zimlet (com_zimbra_test) and in that I allow ALL domains( "*" instead of "*.yahoo.com")and deploy that. Since allowedDomains property is a global property, its then applicable for all the zimlets I develop.

So deploy the com_zimbra_openalldomains.zip zimlet only on your test-box so that you can use any zimlets _dev that might need to access external websites via Javascript.

This zimlet has a config_template.xml file that has the following:

<zimletConfig name="com_zimbra_openalldomains" version="1.0">

   <global>
       <property name="allowedDomains">*</property>
   </global>

</zimletConfig>

PS: When the zimlet goes to production, it needs to have its *own* config_template.xml file that opens-up only required domain, something like

<zimletConfig name="com_zimbra_myzimlet" version="1.0">

   <global>
       <property name="allowedDomains">rss.news.yahoo.com</property>
   </global>

</zimletConfig>




Hack #5 Firebug & debugging tips


Firebug is perhaps world's best javascript debugging tool out there. Download it and enable every setting it, you will use everything during the course of the Zimlet development. http://getfirebug.com/


1. debugger; statement. This is perhaps the most convenient thing within Firebug. Simply write that statement anywhere and javascript execution halts there.

com_Zimbra_test.prototype.function = function() {

 var i =0;
 debugger;  //javascript halts right on this line
 doSomethingWith(i);

}

2. The other thing that helps is... console.log(someVariable); //this some variable is printed in Firebug's log

3. more information can be found here: http://getfirebug.com/logging.html



Hack #6 Firebug Net(network) tab


When accessing services the two common errors we get are are 403 and 500. In firebug, you can easily debug these and many other http errors using Net or network tab.

  1. Error 403 == permission denied; or access it not allowed and
  2. Error 500 == your request is incorrect; i.e.the url or some parameter isnt properly formatted or constructed

Notes: Of course, apart from debugging errors, you can also see soap-requests and soap-responses and all the network traffic.



Hack #7 Firefox Settings


Everytime we load Zimlets in browser it caches in the browser. To make sure we dont cache but still keep cookies and authtokens, perform the following configuration settings.


  1. Open Firefox's > Tools > Options > Privacy
  2. Click on Settings
  3. Check Cache
  4. Uncheck Authenticated Sessions
  5. Uncheck cookies
  6. Press OK
  7. Also Check "Always clear my private data when i close firefox". This will help in clearing cache whenever we press Refresh.
  8. Finally, Uncheck Ask me before Clearing private data, you most likely dont want it to keep asking your permission.




Deploying and undeploying 'Production-level' Zimlets


PS: only for production level Zimlets that are ready-to-go for actual deployment. For Zimlet that are under construction, see "DEVELOPMENT HACKS or TIPS" section



On Windows:


There are two ways to deploy or undeploy a zimlet in Zimbra Desktop.

  1. Manual installation
  2. Using "Zimlet Installer.hta"

1. Deploying Zimlets manually

  1. CD to 'zdesktop' folder (the following command is relative to zdesktop)
  2. Run the following java command...
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy <PATH to Zimlet.zip file>\com_Zimbra_hello.zip
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 deploy C:\path\to\zimletZipfile\com_Zimbra_hello.zip
  1. Shutdown Zimbra Service
  2. Start Zimbra Desktop again


2. Deploying Zimlets via "Zimlet Installer.hta":

  1. keep Zimbra Desktop should be running
  2. Open Zimlet Installer.hta and browse to the Zimlet zip file
  3. Hit Deploy


Notes:

  • When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet folder.
  • This will deploy the Zimlet and restarts Zimbra Desktop Service
  • You should see Zimlet after the restart.
  • All Production Zimlets needs to be *deployed* and needs a restart. While developing a Zimlet however we will use _dev folder which

would over-come this.

1. UnDeploying Zimlets manually

  1. CD to 'zdesktop' folder (the following command is relative to zdesktop)
  2. Run the following command.
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
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 C:\path\to\zimletZipfile\com_Zimbra_hello.zip
  1. Shutdown Zimbra Service
  2. Start Zimbra Desktop again


Undeploying Zimlets via "Zimlet Installer.hta":

  1. keep Zimbra Desktop should be running
  2. Open Zimlet Installer.hta and enter Zimlet's handler name like: com_Zimbra_test (without .zip) in the undeploy field
  3. Hit UnDeploy
  • This will UnDeploy the Zimlet and restarts Zimbra Desktop Service
  • You should see Zimlet go away after the restart.



Notes:

  • There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.



On MacOSX:


You will have to run java command to install and uninstall..

Deploy Zimlets

  1. CD to zdesktop install folder
  2. Run the following java command...
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil deploy <PATH to Zimlet.zip file>/com_Zimbra_hello.zip
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 deploy ~/Y/Zimlets/com_Zimbra_hello.zip
  1. Shutdown Zimbra Desktop Service and Start it


Notes:

  • When Zimlet is deployed, it gets registered in ldap and also the Zimlet files are unzipped and copied to <zdesktop>\jetty\webapps\service\Zimlet.


Undeploy Zimlet:

  1. CD to zdesktop install folder
  2. Run the following command..
java -cp <required jar files> -DZimbra.config=conf/localconfig.xml com.Zimbra.cs.Zimlet.ZimletUtil undeploy <JUST-THE-Zimlet-HANDLER-NAME-WITHOUT-DOTZIP>
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_hello
Note: For undeploying just use the Zimlet-handler-name (not the path and also dont include .zip)
  1. Shutdown Zimbra Desktop Service and start it

Notes:

  • There is a server bug that causes undeployer not to delete Zimlet files in <zdesktop>\jetty\webapps\service\Zimlet folder. It wont hurt, but you can manually delete it if need be.


Zimlet Development by manually building ZCS Environment

  • You'll need ZCS 3.0 or later, either Network or Open Source Edition.
  • JDK 5
  • Eclipse or other editors you are familiar with.
  • Apache Ant for building example Zimlets bundled with ZCS source code. You can use the existing build.xml and just add your own zimlet for easy building and deployment.
  • zip / unzip utility. Most Linux distributions come with /usr/bin/zip and /usr/bin/unzip. Windows XP has a built-in support for zip, but you can also use open source zip utilities like 7-Zip.


Verified Against: ZCS 5.0 Date Created: 3/10/2009
Article ID: https://wiki.zimbra.com/index.php?title=ZimletDevSetup Date Modified: 2009-03-10



Try Zimbra

Try Zimbra Collaboration with a 60-day free trial.
Get it now »

Want to get involved?

You can contribute in the Community, Wiki, Code, or development of Zimlets.
Find out more. »

Looking for a Video?

Visit our YouTube channel to get the latest webinars, technology news, product overviews, and so much more.
Go to the YouTube channel »

Jump to: navigation, search