Zimlet Developers Guide:Developing Zimlets: Difference between revisions

No edit summary
 
(35 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{warning|1=You are looking at legacy Zimlet documentation. For Zimbra Modern UI Zimlet development go to: https://wiki.zimbra.com/wiki/DevelopersGuide#Zimlet_Development_Guide.}}
{{BC|Community Sandbox}}
__FORCETOC__
<div class="col-md-12 ibox-content">
= Zimlet Developers Guide: Dev Environment Setup =
{{KB|{{Unsupported}}|{{ZCS 8.0}}|{{ZCS 7.0}}|}}
{{Archive}}
{| cellspacing="0" cellpadding="5" style="border: 1px solid rgb(153, 153, 170); margin: 0pt 0.5em 0.5em 0pt; float: none; background-color: rgb(249, 249, 255);"
{| cellspacing="0" cellpadding="5" style="border: 1px solid rgb(153, 153, 170); margin: 0pt 0.5em 0.5em 0pt; float: none; background-color: rgb(249, 249, 255);"
|[[Image:zdg-6-menu-icon-zimbra.jpg|20px]]
|[[Image:zdg-6-menu-icon-zimbra.jpg|20px]]
|[[ZCS 6.0:Zimlet Developers Guide:Introduction|Introduction]]
|[[Zimlet Developers Guide:Introduction|Introduction]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-green-flag.png|20px]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-green-flag.png|20px]]
|[[ZCS 6.0:Zimlet Developers Guide:Getting Started|Getting Started]]
|[[Zimlet Developers Guide:Getting Started|Getting Started]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-terminal.png|20px]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-terminal.png|20px]]
|[[ZCS 6.0:Zimlet Developers Guide:Dev Environment Setup|Dev Environment Setup]]
|[[Zimlet Developers Guide:Dev Environment Setup|Dev Environment Setup]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-gear.png|20px]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-gear.png|20px]]
|
|
Line 11: Line 19:
     |'''Developing Zimlets'''
     |'''Developing Zimlets'''
     |-
     |-
     |[[ZCS 6.0:Zimlet Developers Guide:Proxy Servlet Setup|Proxy Servlet Setup]]
     |[[Zimlet_Developers_Guide:Proxy Servlet Setup|Proxy Servlet Setup]]
     |-
     |-
     |[[ZCS 6.0:Zimlet Developers Guide:Firefox and Firebug|Firefox and Firebug]]
     |[[Zimlet_Developers_Guide:Firefox and Firebug|Firefox and Firebug]]
     |-
     |-
     |[[ZCS 6.0:Zimlet Developers Guide:Troubleshooting|Troubleshooting]]
     |[[Zimlet_Developers_Guide:Troubleshooting|Troubleshooting]]
     |}
     |}


|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-advanced.jpg|20px]]
|[[Zimlet Developers Guide:Advanced Concepts|Advanced Concepts]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-library.jpg|20px]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-library.jpg|20px]]
|[[ZCS 6.0:Zimlet Developers Guide:Zimlet API Specifications|API Specifications]]
|[[Zimlet Developers Guide:Zimlet API Specifications|API Specifications]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-checkbox.jpg|20px]]
|style="border-left: 1px solid rgb(153, 153, 170);"|[[Image:zdg-6-menu-icon-checkbox.jpg|20px]]
|[[ZCS 6.0:Zimlet Developers Guide:Example Zimlets|Example Zimlets]]
|[[Zimlet Developers Guide:Example Zimlets|Example Zimlets]]
|}
|}


== Zimlet Files ==
== Zimlet Files ==
Line 29: Line 38:
This section describes the various resources and files that are part of a zimlet. A zimlet can include minimally an XML Zimlet Definition File (e.g. <code>com_zimbra_test.xml</code>). This is where zimlet information such as name and version are described.
This section describes the various resources and files that are part of a zimlet. A zimlet can include minimally an XML Zimlet Definition File (e.g. <code>com_zimbra_test.xml</code>). This is where zimlet information such as name and version are described.


{| cellpadding="5" cellspacing="0" border="1"
{| cellpadding="5" cellspacing="0" border="1" width="100%"
|style="background-color:#ffffcc;"|'''File'''
|style="background-color:#ffffcc;" width="25%"|'''File'''
|style="background-color:#ffffcc;"|'''Required / Optional'''
|style="background-color:#ffffcc;"|'''Required / Optional'''
|style="background-color:#ffffcc;"|'''Description'''
|style="background-color:#ffffcc;"|'''Description'''
Line 40: Line 49:
|<code>*.js</code>
|<code>*.js</code>
|Optional
|Optional
|Supporting JavaScript (JS) files.
|Supporting JavaScript ("JS") files.
|-
|-
|<code>*.jsp</code>
|<code>*.jsp</code>
|Optional
|Optional
|Supporting JSP files.
|Supporting JavaServer Pages ("JSP") files. See [[ZCS_6.0:Zimlet_Developers_Guide:Java_and_JSP|Java & JSP]] for more information.
|-
|<code>*.jar</code>
|Optional
|Supporting Java Archive ("JAR") files. See [[ZCS_6.0:Zimlet_Developers_Guide:Java_and_JSP|Java & JSP]] for more information.
|-
|-
|<code>*.css</code>
|<code>*.css</code>
Line 52: Line 65:
|<code>{zimlet-name}.properties</code>
|<code>{zimlet-name}.properties</code>
|Optional
|Optional
|The resource properties files for the zimlet. These resources are used for internationalizing and localizing zimlets. See [[#Internationalization|Internationalization]] for more information.
|The resource properties files for the zimlet. These resources are used for internationalizing and localizing zimlets. See [[ZCS 6.0:Zimlet Developers Guide:Internationalization|Internationalization]] for more information.
|-
|-
|<code>config_template.xml</code>
|<code>config_template.xml</code>
Line 76: Line 89:
|-
|-
|style="background-color:#ffffcc;"|'''SOAP API'''
|style="background-color:#ffffcc;"|'''SOAP API'''
|Zimbra exposes a SOAP (Simple Object Access Protocol) API to interact with the zimbra server. Using SOAP and XML, data is sent to/from the server to perform server functions on a given mailbox (for example, creating a message or folder).
|Zimbra exposes a SOAP (Simple Object Access Protocol) API to interact with the zimbra server. Using SOAP, data is sent to/from the server to perform server functions on a given mailbox (for example, creating a message or folder). Examples of calling the Zimbra SOAP API for a zimlet can be found at [[ZCS_6.0:Zimlet_Developers_Guide:Example_Zimlets#SOAP_API_Zimlets|Examples > SOAP API Zimlets]].


A more detailed description of the SOAP API can be found in the server source at <code>ZimbraServer/docs/soap.txt</code>.
A more detailed description of the Zimbra SOAP API commands can be found in the server source at <code>ZimbraServer/docs/soap.txt</code>.
|}
|}


Line 121: Line 134:
Example:
Example:


{|cellpadding="5" cellspacing="0" border="1"
{|cellpadding="5" cellspacing="0" border="1" width="70%"
|style="background-color:#ffffcc;" width="20%" |'''Zimlet Name'''
|style="background-color:#ffffcc;" width="20%" |'''Zimlet Name'''
|com_zimbra_helloworld
|com_zimbra_helloworld
Line 165: Line 178:


See [[ZCS_6.0:Zimlet_Developers_Guide:Zimlet_API_Specifications|Zimlet API Specifications]] for information on the JavaScript API and the Zimlet Definition File syntax.
See [[ZCS_6.0:Zimlet_Developers_Guide:Zimlet_API_Specifications|Zimlet API Specifications]] for information on the JavaScript API and the Zimlet Definition File syntax.
'''Note: Do not use periods "." in your Zimlet Handler Object name. Underscores "_" are acceptable.'''


== Development Mode ==
== Development Mode ==
Line 180: Line 195:
Note: When you are developing zimlets with Development Mode ON, you should be sure to test your Zimlet with in regular mode (i.e. without '''&dev=1''') to confirm the zimlet works properly. In some cases, your zimlet might depend modules being lazy loaded and you will have to write code to load the necessary modules.
Note: When you are developing zimlets with Development Mode ON, you should be sure to test your Zimlet with in regular mode (i.e. without '''&dev=1''') to confirm the zimlet works properly. In some cases, your zimlet might depend modules being lazy loaded and you will have to write code to load the necessary modules.


== Internationalization ==


Internationalization is the process of designing a zimlet so that it can be adapted to various languages and regions without code changes. Sometimes the term internationalization is abbreviated as i18n (because there are 18 letters between the first "i" and the last "n").
To internationalize your zimlets, you can include <code>.properties</code> files with your zimlet. These files will include the internationalized text resources used in your zimlet. You can include multiple properties files with your zimlet to support multiple locales.
'''Note: A ''locale'' is the combination of a ''language'' code and a ''country'' code. For example, the locale for the English language in the country of US is <code>en_US</code>. Or the locale for the English language in the country of United Kingdom is <code>en_GB</code>'''
A list of locale country codes are available at http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm
=== Properties File Naming Convention ===
The properties file must start with your zimlet name, followed by the locale and the <code>.properties</code> extension. These files must be in the base directory of your zimlet. The default locale for a zimlet is <code>en_US</code> ("English-US"). The base zimlet properties file is assumed to be English-US and does not include a locale in the file name.
For example, a zimlet named "com_zimbra_helloworld" would have the following properties files to handle English in multiple countries:
{|cellpadding="5" cellspacing="0" border="1"
|style="background-color:#ffffcc;" |'''File'''
|style="background-color:#ffffcc;" |'''Locale Language'''
|style="background-color:#ffffcc;" |'''Locale Country'''
|style="background-color:#ffffcc;" |'''Description'''
|-
|com_zimbra_helloworld.properties
|English ("en")
|United States ("US")
|The default properties resource bundle for the zimlet in the <code>en_US</code> default locale ("Language: English, Country: US")
|-
|com_zimbra_helloworld_en_GB.properties
|English ("en")
|United Kingdom ("GB")
|The properties resource bundle for the zimlet in the <code>en_CA</code> locale ("Language: English, Country: United Kingdom")
|-
|com_zimbra_helloworld_en_CA.properties
|English ("en")
|Canada ("CA")
|The properties resource bundle for the zimlet in the <code>en_CA</code> locale ("Language: English, Country: Canada")
|}
=== Properties File Syntax ===
The resource keys are stored in the properties file in the format <code>key=value</code>. For example, for a resource key named "helloworld":
<pre>
helloworld = Hello World!
</pre>
Comments can be included in the properties file by prefacing the line with "#". For example:
<pre>
# this is a comment in the props file
helloworld = Hello World!
</pre>
'''Note: key names cannot contain periods (".") or dashes ("-"). Underscore ("_") are allowed.'''
=== Accessing Resource Properties ===
The resource keys in your zimlet properties files can be accessed from the Zimlet Definition File XML using the "${msg}" syntax.
For example, accessing a key named "helloworld" from an XML element:
<pre>
<toolTipText>${msg.helloworld}</toolTipText>
</pre>
For example, accessing a key named "helloworld" from an XML element attribute:
<pre>
<menuItem label= "${msg.helloworld}" id="MY_ITEM_ID" />
</pre>
To access resource keys for your Zimlet Handler Object, use the <code>ZmZimletBase.getMessage()</code> JavaScript method:
<pre>
var str = this.getMessage("helloworld");
</pre>
=== Additional Information ===
<ul>
<li>If building your zimlet using the [[ZCS_6.0:Zimlet_Developers_Guide:Dev_Environment_Setup#Zimlet_Development_Directory|Zimlet Development Directory]], you will need to load the Zimbra client in [[#Development Mode|Development Mode]] (i.e. with the <code>?dev=1</code> parameter) in order for the zimlet resource properties to load.</li>
<li>Naming your Zimlet Handler Object the same as your Zimlet Name will cause sporadic results. Be sure to name the Handler Object something different. For example, the Handler Object for a zimlet named "com_zimbra_helloworld" should be "com_zimbra_helloworldHandlerObject". See [[ZCS_6.0:Zimlet_Developers_Guide:Developing_Zimlets#Zimlet_Handler_Object|Zimlet_Handler_Object]] for more information.</li>
</ul>


== Tab Zimlets Life Cycle ==
{{Article Footer|Zimbra Collaboration Server 7.0|12/22/2009}}


You can create zimlets as application tabs. After creating your application (using <code>ZmZimletBase.createApp()</code>), you zimlet handler object will receive application events such as <code>ZmZimletBase.appActive()</code> and <code>ZmZimletBase.appLaunch()</code>.


[[Image:zcs-6-tab-zimlet-lifecycle.png]]
[[Category:Developers]]
[[Category:Zimlets]]
[[Category:ZCS 7.0]]
[[Category:ZCS 6.0]]

Latest revision as of 06:15, 17 July 2021

Warning: You are looking at legacy Zimlet documentation. For Zimbra Modern UI Zimlet development go to: https://wiki.zimbra.com/wiki/DevelopersGuide#Zimlet_Development_Guide.

Zimlet Developers Guide: Dev Environment Setup

   KB 3209        Last updated on 2021-07-17  




0.00
(0 votes)


Zdg-6-menu-icon-zimbra.jpg Introduction Zdg-6-menu-icon-green-flag.png Getting Started Zdg-6-menu-icon-terminal.png Dev Environment Setup Zdg-6-menu-icon-gear.png
Developing Zimlets
Proxy Servlet Setup
Firefox and Firebug
Troubleshooting
Zdg-6-menu-icon-advanced.jpg Advanced Concepts Zdg-6-menu-icon-library.jpg API Specifications Zdg-6-menu-icon-checkbox.jpg Example Zimlets

Zimlet Files

This section describes the various resources and files that are part of a zimlet. A zimlet can include minimally an XML Zimlet Definition File (e.g. com_zimbra_test.xml). This is where zimlet information such as name and version are described.

File Required / Optional Description
{zimlet-name}.xml Required This is the Zimlet Definition file and specifies the zimlet behavior. This file is required for all zimlets. See Zimlet Definition File Reference for more information on the zimlet XML elements.
*.js Optional Supporting JavaScript ("JS") files.
*.jsp Optional Supporting JavaServer Pages ("JSP") files. See Java & JSP for more information.
*.jar Optional Supporting Java Archive ("JAR") files. See Java & JSP for more information.
*.css Optional Supporting CSS files.
{zimlet-name}.properties Optional The resource properties files for the zimlet. These resources are used for internationalizing and localizing zimlets. See Internationalization for more information.
config_template.xml Optional This is the Zimlet Configuration File and is is used to configure zimlet properties, such as "allowedDomains". See Zimlet Configuration File for more information. See Proxy Servlet Setup for more information on allowed domains.

Zimlet APIs

There are different API components in zimlet development. Based on the functionality you are trying to achieve, your zimlet implementation might leverage a combination of APIs.

XML API The XML API is comprised of two components:

You can accomplish a lot with just the Definition File. For example, you can implement content zimlets, build context menus, make your zimlet appear as a panel items and in general, accomplish basic interactions with external services (via the <actionUrl> tag). But there are limits to how much customization and interaction with the Zimbra Web Client your zimlet can have. Also, there is limited debugging. For any zimlet that wants to present custom dialog boxes or advanced interactions with the Zimbra Web Client (e.g. inject buttons, make a zimlet application tab) That's when you start to leverage the JavaScript API with the XML API. All zimlets will, at minimum, have to include a basic Definition File. See the Zimlet Definition File Reference for more information on the zimlet XML elements and syntax.

JavaScript API Zimlets are primarily written in JavaScript. Using the JavaScript API together with the XML API allows you to write really powerful zimlets. You can use the XML API for certain purposes (like creating a panel item, context-menus, etc) and use the JavaScript API to react to events from those items. See JavaScript APIs for more information.
SOAP API Zimbra exposes a SOAP (Simple Object Access Protocol) API to interact with the zimbra server. Using SOAP, data is sent to/from the server to perform server functions on a given mailbox (for example, creating a message or folder). Examples of calling the Zimbra SOAP API for a zimlet can be found at Examples > SOAP API Zimlets.

A more detailed description of the Zimbra SOAP API commands can be found in the server source at ZimbraServer/docs/soap.txt.

XML APIs

Zimlet Definition File

This file defines the zimlet and is required for all zimlets. You can implement zimlet functionality directly in this file. It exposes very basic functionality and useful for simple content zimlets (e.g. you can define menu items, the zimlet panel interactions and simple URL actions). But beyond the basic, you will want to leverage the JavaScript API and the Zimlet Handler Object.

See Zimlet Definition File Reference for more information on the zimlet XML elements and syntax.

Zimlet Configuration File

The configuration file (config_template.xml) specifies properties for the zimlet configuration. Properties can be global or host specific. The properties may be accessed within the Zimlet Definition File using the "${}" syntax.

Property Syntax Example
To access global properties ${config.global.propertyName} To access a global property named "defaultToGoogle", the syntax is ${config.global.defaultToGoogle}.
To access host-specific properties ${config.host.propertyName} To access a host-specific property named "googleApi", the syntax is ${config.host.googleApi}.

Configuration properties are also available from the Zimlet Handler Object using the getConfigProperty() method.

See Zimlet Configuration File Reference for more information on the zimlet XML elements and syntax.

JavaScript APIs

Zimlet Handler Object

The Zimlet framework provides the Zimlet JavaScript base class: the Zimbra Handler Object. This class is ZmZimletBase. Developers wishing to implement Zimlet functionality in JavaScript should extend the ZmZimletBase class. The ZmZimletBase contains methods for panel zimlets, tab zimlets and content zimlets.

A recommended naming convention is to use your zimlet name in the name of your Zimlet Handler Object implementation.

Example:

Zimlet Name com_zimbra_helloworld
Zimlet Definition File Name com_zimbra_helloworld.xml
Zimlet Package Name com_zimbra_helloworld.zip
Zimlet JavaScript File com_zimbra_helloworld.js
Zimlet Handler Object name com_zimbra_helloworldHandlerObject

As part of your zimlet, in the Zimlet Definition File, include the JavaScript file:

<include>com_zimbra_helloworld.js</include>

Define your Handler Object in the Zimlet Definition File:

<handlerObject>com_zimbra_helloworldHandlerObject</handlerObject>

To implement the Zimlet Handler Object, designate your handler object to be a sub-class of the ZmZimletBase class in the zimlet JavaScript file.

/**
 * Defines the Zimlet handler class.
 */
function com_zimbra_helloworldHandlerObject() {
}

/**
 * Makes the Zimlet class a subclass of ZmZimletBase.
 */
com_zimbra_helloworldHandlerObject.prototype = new ZmZimletBase();
com_zimbra_helloworldHandlerObject.prototype.constructor = com_zimbra_helloworldHandlerObject;

See Zimlet API Specifications for information on the JavaScript API and the Zimlet Definition File syntax.

Note: Do not use periods "." in your Zimlet Handler Object name. Underscores "_" are acceptable.

Development Mode

When the Zimbra web client is loaded, the server consolidates (i.e. ZIPs) and obfuscates (i.e. unformats) all the JavaScript code in the application. This is to speed login and load time. Additionally, not all modules (for example, calendar, documents, etc) are loaded on initial login and modules are only loaded when needed (i.e. "lazy" loading). The combination of the consolidation, obfuscation and lazy loading makes it difficult to debug code in the browser. For example, a zimlet function like sendMail(param1,param2) in the Zimlet JavaScript file might become hy(p1,p2) in the Zimlets-nodev_all.js file.

For development and debugging, you can disable these activities and run the web client in "Development Mode" by appending a dev=1 to the client URL.

In this mode, all of the web client modules are loaded at login, all of the JavaScript is left un-consolidated and readable. Additionally, to further help with debugging, a debug-window pop-up is opened that shows all of the SOAP transactions as they occur between the web client browser and the server.

For example, append dev=1 to the client URL:

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

Note: When you are developing zimlets with Development Mode ON, you should be sure to test your Zimlet with in regular mode (i.e. without &dev=1) to confirm the zimlet works properly. In some cases, your zimlet might depend modules being lazy loaded and you will have to write code to load the necessary modules.


Verified Against: Zimbra Collaboration Server 7.0 Date Created: 12/22/2009
Article ID: https://wiki.zimbra.com/index.php?title=Zimlet_Developers_Guide:Developing_Zimlets Date Modified: 2021-07-17



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