ZimletDevSetup: Difference between revisions

No edit summary
No edit summary
Line 1: Line 1:
== '''Zimlet Development via Yahoo! Zimbra Desktop''' ==
== '''Zimbra Desktop Basic Configuration''' ==
------------------------------------
 
== '''Zimbra Desktop Configuration''' ==
 
------------------------------------
1. Download Zimbra Desktop
1. Download Zimbra Desktop
http://www.Zimbra.com/products/desktop_download.html
http://www.Zimbra.com/products/desktop_download.html
Line 49: Line 44:


----------------------------------------------------------
----------------------------------------------------------
'''Hack #1 Use Zimbra Desktop as a web-application'''  
=== '''Hack #1 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 Javascript debugging!
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 Javascript debugging!
Line 68: Line 63:


----------------------------------------------------------
----------------------------------------------------------
'''Hack #2 dev=1  the developer mode'''
=== '''Hack #2 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.
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.
Line 84: Line 79:


-----------------------------
-----------------------------
'''Hack #3  Create _dev folder:'''
=== '''Hack #3  Create _dev folder:''' ===
-----------------------------
-----------------------------
* When the Zimlet is deployed, its copied to''' zdesktop\jetty\webapps\service\Zimlet''' and needs  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.
* When the Zimlet is deployed, its copied to''' zdesktop\jetty\webapps\service\Zimlet''' and needs  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.
Line 102: Line 97:


----------------------------------------------------------
----------------------------------------------------------
'''Hack #4 Proxy Hack'''  
===  '''Hack #4 Proxy Hack''' === 
----------------------------------------------------------
----------------------------------------------------------
PS: This is for accessing external sites directly from javascript (you don't need this if jsp was used)
PS: This is for accessing external sites directly from javascript (you don't need this if jsp was used)
Line 132: Line 127:


----------------------------------------------------------
----------------------------------------------------------
'''Hack #5 Firebug & debugging tips'''
=== '''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.
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.
Line 157: Line 152:


----------------------------------------------------------
----------------------------------------------------------
'''Hack #6 Firebug Net(network) tab'''
=== '''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.
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.
Line 169: Line 164:


----------------------------------------------------------
----------------------------------------------------------
'''Hack #7 Firefox Settings'''
=== '''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.
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.
Line 196: Line 191:


-----------------
-----------------
'''On Windows:'''
=== '''On Windows:''' ===
-----------------
-----------------
There are two ways to deploy or undeploy a zimlet in Zimbra Desktop.  
There are two ways to deploy or undeploy a zimlet in Zimbra Desktop.  
Line 202: Line 197:
# Using "Zimlet Installer.hta"
# Using "Zimlet Installer.hta"


'''1. Deploying Zimlets manually'''
==== '''1. Deploying Zimlets manually''' ====
1.  CD to 'zdesktop' folder (the following command is relative to zdesktop)
1.  CD to 'zdesktop' folder (the following command is relative to zdesktop)


Line 219: Line 214:




'''2. Deploying Zimlets via "Zimlet Installer.hta":'''
==== '''2. Deploying Zimlets via "Zimlet Installer.hta":''' ====
# keep Zimbra Desktop should be running
# keep Zimbra Desktop should be running
# Open Zimlet Installer.hta and browse to the Zimlet zip file  
# Open Zimlet Installer.hta and browse to the Zimlet zip file  
Line 232: Line 227:
would over-come this.
would over-come this.


'''1. UnDeploying Zimlets manually'''
====  '''1. UnDeploying Zimlets manually''' ====
1. CD to 'zdesktop' folder (the following command is relative to zdesktop)
1. CD to 'zdesktop' folder (the following command is relative to zdesktop)


Line 250: Line 245:




'''Undeploying Zimlets via "Zimlet Installer.hta":'''
====  '''Undeploying Zimlets via "Zimlet Installer.hta":''' ====
# Keep Zimbra Desktop should be running
# Keep Zimbra Desktop should be running
# 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
Line 266: Line 261:


-----------------
-----------------
'''On MacOSX:'''
===  '''On MacOSX:''' ===
-----------------
-----------------
You will have to run java command to install and uninstall..
You will have to run java command to install and uninstall..


'''Deploy Zimlets'''
====  '''Deploy Zimlets''' ====
1.  CD to zdesktop install folder
1.  CD to zdesktop install folder


Line 291: Line 286:




'''Undeploy Zimlet:'''
====  '''Undeploy Zimlet:''' ====
1.  CD to zdesktop install folder
1.  CD to zdesktop install folder



Revision as of 22:56, 10 March 2009

Zimbra Desktop Basic 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 aka zdesktop>\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 and using Zimbra Desktop as Web Application

PS: Use these tips to get yourself up-and-running with Zimlet development via Zimbra Desktop in no-time



Hack #1 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 Javascript 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 #2 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 #3 Create _dev folder:


  • When the Zimlet is deployed, its copied to zdesktop\jetty\webapps\service\Zimlet and needs 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


Notes:

  1. If your Zimlet is accessing external sites via javascript(not jsp), Please go through Hack #4 Proxy Hack. You will have to deploy a (different) Zimlet that opens-up that domain.



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 don't really deploy the zimlet but simply use a server hack to make it work and so the allowedDomains isn't registered in ldap. However, 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>

Notes: 1. When a 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>

2. See the Deploying and Undeploying Production level Zimlets for more information on how to deploy a Zimlet.



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

3. Shutdown Zimbra Service

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

3. Shutdown Zimbra Service

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

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

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