Zimbra

If you have ever written a Zimlet that includes HTML markup directly in JavaScript, you know that escaping and formatting the HTML can be a cumbersome and error prone process.

There is an easier way: Templates. Templates allow you to separate HTML markup from JavaScript code. This enables you to leverage HTML in your Zimlets without the formatting hassles.

The Problem

A common technique for using HTML markup within JavaScript is to use an Array() and append HTML markup data as array entries. Once you have all of the HTML markup in the Array(), you perform an Array.join() to create a single String that represents the HTML markup.

For example, say you wanted you to use the following HTML in your Zimlet:

<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tbody>
<tr>
<td colspan="2">This is a sample table HTML code...</td>
</tr>
</tbody>
</table>


Using the Array() technique, your JavaScript would look like:

var htmlArray = new Array(); var i = 0;
htmlArray[i++] = "<table border=\"0\" cellspacing=\"0\" cellpadding=\"2\" width=\"100%\"><tbody><tr><td colspan=\"2\">";
htmlArray[i++] = "This is a sample table HTML code...";
htmlArray[i++] = "</td></tr></tbody></table>";
htmlMarkup = html.join("");


Even with this simple HTML <table> example, you can see formatting the HTML into an Array() can be tedious. Plus, the extensive use of escaped characters makes it harder to debug the HTML markup. And if you include CSS and style elements with your HTML, the challenge only increases. It’s easy to see that using the JavaScript Array() technique can quickly become out-of-control.

The Solution

With Templates, you separate the HTML markup from your JavaScript code. You create a Template file that contains the HTML markup. That Template file gets compiled into JavaScript and that compiled Template can be referenced from your Zimlet JavaScript.

So instead of the JavaScript Array() technique described above, you can put the HTML markup directly in a Template file (just wrap the HTML in a <template> identification element) and compile.

Here is the same simple HTML <table> example from before in a Template file:

<template id="Simple">
<table border="0" cellspacing="0" cellpadding="2" width="100%">
<tbody>
<tr>
<td colspan="2">This is a sample table HTML code...</td>
</tr>
</tbody>
</table>
</template>


Compiling the Template file converts the HTML markup into JavaScript that can be referenced and used from your Zimlet. No longer do you have to format and escape the HTML markup by hand.

To reference the compiled Template from your Zimlet, first, in your Zimlet Definition File XML, <include> the compiled Template as a resource. Then, in your Zimlet JavaScript, use AjxTemplate.expand() to retrieve the HTML markup from the Template.

var html = AjxTemplate.expand("com_zimbra_template.templates.Simple#Simple");


Now the HTML markup is available for use in your Zimlet as you see fit.

A Word about Compiling Templates

Prior to Zimbra Collaboration Suite 6.0.5, you had to compile your Templates manually and include the compiled Templates with your Zimlet ZIP package. We have tried to make that manual compilation process a little easier by providing a simple Template Compiler utility found here.

But new with is ZCS 6.0.5 is automatic template compilation. Template files included with your Zimlet are compiled at Zimlet deploy time, eliminating the need for manual compilation. This automatic compilation is also supported when using the Development Directory, which makes iterative development even easier.

One More Thing

Your Template can be more than just static HTML markup. You can pass data to the compiled Template when you call AjxTemplate.expand() and reference dynamic data within your Template.

var dataArray = {phone: "123-456-7890"}; canvas.innerHTML = AjxTemplate.expand("com_zimbra_template.templates.Simple#Simple", dataArray);


Useful Links

More information on creating, compiling and using dynamic data with Templates can be found here:

http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Templates

There are also examples available in the Zimlet Developer’s Guide:

• This example shows using a simple Template to display HTML in a tab.

  http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Examples:Tab_Template

• This example shows using a Template to display HTML in a dialog.

  http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Examples:Simple_Dialog_with_Template

Happy coding!

For years, the Zimbra Collaboration Suite (ZCS) has exposed mailbox data via REST. And lately, a few customers have asked about the Zimbra REST API (e.g. How is the API used? What methods are available? How does the Zimbra REST API compare to the Zimbra SOAP API?). So I thought it would be good to revisit the topic.

Some background: REST (REpresentational State Transfer) is an approach for building application services that make application resources available via a URL. There is more than ample information about REST out there on the web so I’ll just point you to the REST Wikipedia article for simplicity.

The Zimbra REST API is a great mechanism for reading user mailbox data and outputting that data in different formats (everything from XML-and-JSON to RSS-and-Atom to iCal-and-VCF). In addition to reading data, we’ve exposed methods to import items — like contacts and appointments — into a mailbox. This capability is very useful when performing a migration (i.e. “how do I import contacts from one system into Zimbra?”)

Here is an example of using the REST API to read mailbox data: if you want an output of messages from the “john doe” inbox folder, you call the Zimbra REST API like this:

http://localhost:7070/home/john.doe/inbox?fmt=xml

You can try this method against a Zimbra server via a browser but more commonly customers use the REST API methods from perl scripts or PHP applications…or even just from the command line using curl.

Here is an example of importing contacts into the “john doe” account: perform a POST of a CSV file to the “contacts” folder. The following command shows importing contacts using curl:

curl -{username}:{password} --upload-file /tmp/mycontacts.csv http://localhost:7070/home/john.doe/contacts?fmt=csv

That’s just a couple examples and as you can see, the REST API is a simple yet powerful mechanism for accessing mailbox data. For more information on the Zimbra REST API (i.e. information on authentication, output formats or just a list & syntax for the REST API methods), here is a link to Zimbra REST API Reference document:

http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimbra_REST_API_Reference

One more thing: A very common question is: “why does the SOAP API support so many more functions than the REST API?” Well, the Zimbra REST API is different (in form and function) than the Zimbra SOAP API. At a high level, it’s really an apples-to-oranges comparison. The REST API is for accessing user mailbox data, and the SOAP API is for executing functionality on the server (which can access user mailbox data and also perform account and administrative functions).

The Zimbra SOAP API is the foundational platform service that the Zimbra Web Client uses to communicate between the browser and the Zimbra server. As you can imagine, to create the rich interface experience the Zimbra Web Client delivers, the SOAP API is very complete with advanced and complex functionality, much more than the REST API. To re-create all of this complex functionality in REST API would be a challenge as well as take significant time. So as the alternative, we expose the SOAP API for direct use by our customers & partners.

But that’s another story…I’ll save the Zimbra SOAP API discussion for a different day…until then, enjoy the REST API and happy coding!

New with Zimbra Collaboration Suite 6.0 is the ability to create Zimlets that show-up as tab applications in the Zimbra Web Client.  This powerful new feature, unique to the Zimbra platform, enables partners & customers to more easily integrate third-party applications with the Zimbra Web Client. And there are already new Zimlets taking advantage of this feature, like the Social Zimlet or the BroadSoft Zimlet.

Let’s take a look at how to implement some of the basic operations of this new feature…But first, some background: the Zimbra Web Client displays multiple default applications across the top of the interface as “tabs”. These applications include (based on your deployment configuration): mail, address book, calendar, tasks, documents and briefcase. With the Zimlet Tab feature, you can add “tabs” to this array of applications.

Creating the Tab

It starts with creating the tab in your Zimlet JavaScript code. A createApp() method has been added to the ZmZimletBase class. Since all zimlets extend ZmZimletBase, to create a tab, all you need to do is call the this.createApp() method from your Zimlet. The three parameters to createApp() are:

• Tab label: the visible text “label” for the tab (for example, “My Tab”).
• Tab icon: the CSS class to use for the icon in the tab.
• Tab tool tip: the tab tool tip shown when hovering over the tab.

So creating a tab is as simple as calling the following from your Zimlet:

this._tabAppName = this.createApp("My Tab", "zimbraIcon", "A new tab app");

This method returns a unique application name for the newly created tab. You will need this unique name to manage and retrieve the different components of the tab, so it’s best to capture this return value.

Listening for Tab Application Events

Your Zimlet will also receive application events as tab applications are launched for the first time and as a user navigates around the Zimbra Web Client between tab applications. The events will be received in the ZmZimletBase.appActive() and ZmZimletBase.appLaunch() methods. By implementing these methods in your Zimlet, you will be able to know when a user launches and switches between tab applications.

Anatomy of a Tab Application

The layout of a tab application includes the following: the Tab and the Content Areas (i.e. Toolbar, Main and Overview).

The Tab

The row of tab applications across the top of the Zimbra Web Client interface is managed by an application chooser, which is represented by the Zimbra JavaScript class ZmAppChooser. The ZmAppChooser class extends ZmToolBar, making the row of tab applications basically a toolbar with buttons that look like “tabs”.

That means, after tab creation, you can manage the actual “tab” for the application as a ZmAppButton. For example, you can obtain a handle to the tab “button” through the app chooser and set, among other things, the text label & the tool tip.

var controller = appCtxt.getAppController();
var appChooser = controller.getAppChooser();

// change the tab label and tool tip
var appButton = appChooser.getButton(this._tabAppName);
appButton.setText("NEW TAB LABEL");
appButton.setToolTipContent("NEW TAB TOOL TIP");

The Content Areas

You can set the various content areas of the tab to suit your Zimlet needs. The Toolbar area is the area directly under the row of tab applications. This is typically the place where you put toolbar buttons for application control. The Overview area is located on the left-side of the page. This area typically houses a navigation tree but you can set any content you see fit. The Main area is the primary content location for the tab and can be set with whatever application content as needed.

The Toolbar Area can be obtained from the ZmZimletApp and is represented as a ZmToolBar object:

var app = appCtxt.getApp(this._tabAppName);
var toolbar = app.getToolbar();
toolbar.setContent("<b>TAB APPLICATION - TOOLBAR AREA</b>");

The Main Area can be accessed directly from the ZmZimletApp:

var app = appCtxt.getApp(this._tabAppName);
app.setContent("<b>TAB APPLICATION - MAIN AREA</b>");

The Overview Area can be obtained from the ZmZimletApp and is represented as a ZmOverview object:

var app = appCtxt.getApp(this._tabAppName);
var overview = app.getOverview();
overview.setContent("<b>TAB APPLICATION - OVERVIEW AREA</b>");

So that’s the basics of tab applications and Zimlets. As you can see, by leveraging this new Zimlet Tab feature, you will be able to create new & powerful integrations with Zimbra Collaboration Suite.

More information on implementing your own Zimlet tab application can be found in the Zimlet Developer’s Guide at:

http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Introduction

http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Zimlet_Tab

Zimlet Tab Examples are available at:

http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Example_Zimlets#Tab_Zimlets

And checkout the Zimlet JavaScript API Reference for information on the ZmZimletBase class and tab application methods such as createApp(), appAction() and appLaunch():

http://files.zimbra.com/docs/zimlet/zcs/6.0/jsdocs/index.html

When developing a Zimlet, you are constantly making code changes and then packaging and deploying the Zimlet to be able to test those changes. This is the Zimlet development process and is done over & over again until your Zimlet is “ready” for production. An iterative development process like this that involves packaging and deploying with each code change can be quite time consuming and really impact your developer productivity.

That’s where the Zimlet Development Directory comes in.

By using the Zimlet Development Directory, you can develop your Zimlets without having to package and deploy the Zimlet with each code change. You can make your code changes directly in the Zimlet files and just refresh your browser to see the changes take affect. This will greatly reduce your development time and overall, make it much easier to build Zimlets.

To use the Zimlet Development Directory, create a _dev folder in the {zcs-install-dir}/zimlets-deployed directory. In the _dev folder, create your Zimlet folder and file structure that you can modify on the fly. It’s just that easy.

For example, say you want to create a Zimlet named “com_zimbra_myzimlet”:

1. Create the development directory:
   {zcs-install-dir}/zimlets-deployed/_dev
2. Create the Zimlet folder:
   {zcs-install-dir}/zimlets-deployed/_dev/com_zimbra_myzimlet
3. Now put your Zimlet Definition File (com_zimbra_myzimlet.xml) and whatever other resources your Zimlet needs in that directory (like JavaScript files, JSP files, Properties files, etc).
4. Make code changes to the Zimlet files as necessary and voila, just refresh your browser to see the changes take affect.

There are some limitations, however. If using Internationalization resource properties, you will need to load the Zimbra Web Client in Development Mode (i.e. with “?dev=1″ on the URL). Also, the “allowed domains” setting in the Zimlet Configuration File (config_template.xml) for the Proxy Servlet is not recognized. There is a workaround for this situation described in the Proxy Servlet Setup section of the Zimlet Developer’s Guide.

We still recommend that you package and deploy your Zimlet when you plan to go into production. But as you can see, the Zimlet Development Directory cuts-out the deploy & package development steps and is a convenient way to do iterative Zimlet development.

More information on the Zimlet Development Directory can be found in the Zimlet Developer’s Guide at:

http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Dev_Environment_Setup#Zimlet_Development_Directory

This is one people have asked about a lot. Starting with Zimbra Collaboration Suite 6.0, we will be providing a formal Zimlet Developer’s Guide and API Reference. The goal of this documentation is to make it easier for partners and customers to build Zimlets and to integrate with the Zimbra platform. As we’ve built this documentation, here are some of our guiding principles:

• Easy to find. Make the documentation online and “wiki-based” for easy access.
• Reduce “wondering” between versions. Maintain documentation with each ZCS release so when new major versions of ZCS are delivered (and changes are made to the APIs), people on older ZCS releases can still access their “version specific” documentation.
• Lower overhead to get started. Make developing Zimlets possible without having to download the entire product source. Of course, product source will still be available for those who want it but we want to make even advanced Zimlet tasks (for example, compiling templates) possible without needed the entire source tree.

Here are links to the new developer documentation:

Zimlet Developer’s Guide for ZCS 6.0
http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Introduction

Zimlet Definition File Reference for ZCS 6.0
http://wiki.zimbra.com/index.php?title=ZCS_6.0:Zimlet_Developers_Guide:Zimlet_Definition_File_Reference

Zimlet JavaScript API Reference for ZCS 6.0
http://files.zimbra.com/docs/zimlet/zcs/6.0/jsdocs/index.html

These are living documents and we will be adding content & more information over the coming weeks. With this first-launch, we are looking for your thoughts on the best ways you enjoy learning and making use of the new material, as well as ideas and suggestions about Zimlet topics that you think we should cover. Please provide feedback and comments in the forums at:

http://www.zimbra.com/forums/zimlets/35951-new-zimlet-developer-documentation-zcs-6-0-available.html

Pay attention to the extra bar at the top to navigate around the wiki pages:

Whether you just want dozens of examples, a list of all the elements in the Zimlet Definition File…or want to dive into advanced topics like Templates and Portals, we plan to leave no stone unturned.

Happy coding!

Tomorrow in Paris, France there is an all day meet-up for Zimbra community members, partners and customers.  The agenda includes Zimbra roadmap beyond ZCS 6 and will have some basics on Zimlet development with drinks to follow.  It looks like a great opportunity to learn a lot and network with others in the community.  There will be both English and French speakers there, be sure to check it out!

From our French friends:

We held the first hands-on Zimlet training over at our London offices back in October, where Raja Rao put together such a great presentation and collection of modules that we decided to roll it into a permanent series.

If your organization is interested in enhancing Zimbra via communication with external services, adding extra functionality via widgets and application portals, or just wants to increase usability of existing inline content: We cordially invite you to our beautiful (and relatively warm) Sunnyvale, California campus February 23-24th. Whether your somewhat new to basic object oriented JavaScript programming or already familiar with advanced Zimbra specific SOAP, JSON requests, and hooks; our front-end engineers and best mashup gurus will be available to help get your coding started.

Details on this two day course’s agenda and the registration form can be found here: Zimbra-Training-Registration-Zimlet-Course.pdf

-For more information contact us or email training@
-Local Hotel options: Zimbra-Training-Location-Sunnyvale.pdf
-There are partner discounts, though any member of the community is welcome to attend even if you aren’t a network edition customer.
-Can’t make it in December? We’re holding another in May tentatively the 4th through 5th. Be sure to let us know early if your interested – space is limited and will fill up fast.

Zimbra’s massive user base means our new product releases reach farther than ever before. How far? Consider our 50 million paid mailbox count. With that comes the responsibility to make our solutions exactly what people need when it comes to shaping the future of communication.

So what are some of the top requested features included in the first release of Zimbra Collaboration Suite 6.0?

Sync your phone like never before.

We’ve added user trigger-able device wipe, server policies, and tasks to the existing MobileSync support for email, contacts, and appointments.

Arrange and personalize the interface.

Read and compose multiple messages in tabs without the need for pop-out windows using the advanced AJAX client. Widescreen? Move the reading pane to the side.

Presentation Framework.

Create new presentations (as well as documents and spreadsheets) from the briefcase – no need for external software to run them.

 

 

Calendar views. Direct CalDav connections. Streamlined contacts.

Our feature rich UI has new layouts including fisyeye and a sortable list view. Access an external ICS/CalDAV url – with adjustable automatic update polling frequencies. For the address book: Rather than pages of blanks to fill out, add only the contact fields you want.

Lite-client overhauls galore.

The standard HTML client now includes all our primary apps, plus the ability to drag items like it’s AJAX cousin. Using a web-browser on your mobile device? There’s multiple variants based on device type and connection speed. We’ve added appointment management functionality to the portable web-client, a simplified login page, as well as file access.

Role based administration.

Delegate. Empower distribution list managers without worrying about them accidentially changing major server settings. Even let someone add or remove members, but not create or delete existing lists – the views and ACL rights are that customizable. Hosting providers can now give one account permission to manage multiple domains or adjust class-of-service features.

 

 

Connect with your social world.

Zimlets now have the ability to define application or preferences tabs. So use the new Social Zimlet to manage Twitter, Facebook, or just browse Digg. Try the Discover Zimlet to visit all that Del.icio.us has to offer.

Share Management.

Join a new group? Get up to speed fast – receive and an instant email about all the available shares. Didn’t accept that invite long ago but turns out you need something? Rather than digging it up, just use the new share tool to see what you have permissions on; or have given to others.

Server Architecture Improvements.

A few of the powerful under-the-hood changes include a new OpenLDAP engine with the ability to make on the fly config tweaks, SQLite & RRD for logger, customizable hierarchical storage queries. Plus we’ve exposed a UI for the stats service – giving you quick insight on just about everything you can think of.

With thousands of votes from the Zimbra community submitted to our product management database, and tens of thousands of hours logged by our engineering team, we are excited to officially announce Zimbra Collaboration Suite 6.0.

ZCS 6.0 is chock full of everything you asked for – because we made sure to check off the hit list of top requests. Some of the highlights include improved delegation and share management, increased productivity with three-pane email view, read receipts, remote wipe for mobile devices, and more. Our goal was also to make ZCS 6.0 the most flexible product yet, so we’ve also made it easier than ever to integrate 3^rd party software. You can learn more about the new features in 6.0 later today in a deep-dive blog post.

But that’s not the only recent milestone: Did you ever wonder what Zimbra and South Africa have in common? No it’s not our love for South African Hip Hop or Kwaito … it is that Zimbra just bested their population of 49.3 million because today, we have surpassed the 50,000,000th paid mailbox mark. Meaning if all Zimbra users made up their own country they would be the 25^th most populous in the world, edging up on Italy (Pasta anyone?). It’s amazing that we were able to gain ten million paid mailboxes just six months after reaching 40 million. Those 50 million accounts are spread across over 100,000 organizations that are now using Zimbra throughout the globe. That leap can only be attributed to our wonderful collection of partners and developers who continually remind us what people need so we can deliver the best collaboration product on the market.

We’ve been lucky to have the opportunity to work with a wide range of customers – from enterprises such as Mediacom and WebMD, to new government organizations including The Drug Enforcement Administration (DEA), Greece’s Ministry of Foreign Affairs, and Oman’s Ministry of Health; to educational institutions like Swarthmore College, Ecole Polytechnique de Montreal, and Savannah College of Art and Design.

Below are images a new mash-up built around ZCS 6 platform enhancements enabling Zimlets to be core application tabs.  “Zimbra Social” keeps you on top of all your Facebook, Twitter and Digg goodness.

Get the latest version of the Social Zimlet from the Gallery

Thanks again for all your support and feedback; hope you enjoy ZCS 6.0!
Network Edition server download | Open Source Edition server download

You can also find a bit more about what’s new in ZCS 6 on the Zimbra website.