View source for Zimlet Definition File

==Outline== 

The <zimlet> element is the enclosing element in the definition file. The <zimlet> element has the following attributes:</nowiki>   
* '''name''' - The name attribute is the Zimlet’s name and is a required attribute. This must be the same name as is used to prefix all the well defined files in the Zimlet bundle. The Zimlet name is required to be unique within a deployment. The naming convention for Zimlets follows that of Java. That is, the name is prefixed with the domain of the author’s company; however, the “.”s in the domain are replaced by “_” characters. From example: name=”com_acme_Maps” 
* '''version''' - This required attribute specifies the Zimlet’s version. For example, version=”1.0” 
* '''description''' – This attribute provides a short (approximately one line) description used in mouse-overs and dialogs  <nowiki>The <zimlet> element may also contain a number of optional child elements that define the Zimlet. The following sub sections describe each of these child elements</nowiki>  

=== <summary> Element ===

The summary element contains text describing the Zimlet in more detail. It can also contain limitations and a list of current functionality: 
  
 <nowiki><summary>  This Zimlet will provide map information for street addresses  
  Note: Currently maps are not scrollable or clickable. </nowiki>   
 
The summary element is an optional element.   

=== <include> Element ===

In certain cases a Zimlet implementation may require additional JavaScript code to be loaded by the client. For such cases, the <include> element is provided. The content of this element provides a reference to the additional script files that are to be loaded. These files may be internal, that is specified by a relative URL (e.g. foo.js) or external, that is specified by an absolute URL <nowiki>(e.g. http://api.google.com/maps.js). </nowiki> If multiple <include> elements are provided, 

loading order is maintained (top to bottom).

Below are examples of the <include> element:

 <nowiki><include>http://api.google.com/maps.js</include></nowiki>  
 <nowiki><include>gmaps.js</include></nowiki>  

=== <includeCSS> Element ===

<nowiki>A Zimlet implementation may require CSS styles to be loaded by the client. The <includeCSS> element is provided for such cases. The content of this element provides a reference to the additional CSS file that is to be loaded. This file may be internal, that is specified by a relative URL (e.g. foo.css) or external, that is specified by an absolute URL (e.g. http://my.server.com/styles.css). Any CSS file included with a <includeCSS> element is automatically loaded. </nowiki>It is required that any CSS class in these files be prefixed with or include the zimlet name to avoid collisions with other CSS classes or Zimlets.   

<nowiki>Below are examples of the <includeCSS> element:</nowiki>   

 <nowiki><includeCSS></nowiki>http://my.server.com/styles.css<nowiki></includeCSS></nowiki>  
 <nowiki><includeCSS>styles.css</includeCSS></nowiki>   

=== <resource> Element ===

<nowiki>A Zimlet implementation may require additional resources: images, binaries, etc. For such cases, the <resource> element is provided. The content of this element provides a reference to the additional files that are to be loaded. These files may be internal (specified by a relative URL, e.g. image.gif) or external (specified by an absolute URL, e.g. http://api.google.com/maps.jgif). </nowiki>Resources are not automatically loaded. They can be accessed with the fully qualified URL via the Zimlet JavaScript class’ getResource() method (see section 4.4.8)   

=== <handlerObject> Element ===

The <nowiki><handlerObject></nowiki><nowiki> element designates the constructor to call in the <zimlet>.js at init time. The </nowiki><nowiki><handlerObject> element </nowiki>may be omitted if the zimlet does not implement custom JavaScript code.   

=== <contentObject> Element ===

A content object is an object that is recognized by a Zimlet in a body of content, such as an email message body, the notes of an appointment, or fields in a contact. Examples of content objects are: Phone numbers, URLs, purchase order numbers, package tracking numbers, etc. <nowiki>The <contentObject> element defines the content object that a Zimlet recognizes and how the user interacts with the object. If a Zimlet does not expose a content object then this element may be omitted. The <contentObject> element is fully described in section </nowiki>   

=== <serverExtension> Element ===

<nowiki>The <serverExtension> element describes how a content object is indexed on the server. Content, such as email message bodies, calendar appointment notes, and contact fields, that contains one or more Zimlet content objects may be searched for via the query language’s “has” clause. For example, if a Zimlet were to define phone numbers as a content object, then </nowiki><nowiki>to search for content containing phone numbers, a <serverExtension> element would be specified that defines phone numbers, and would enable searching for content containing phone numbers via </nowiki>the “has:phone” clause. <nowiki>The <serverExtension> element is fully described in section </nowiki>   

=== <zimletPanelItem> Element ===

<nowiki>The Zimlet panel appears within the ZCS AJAX client’s overview panel. The overview panel is to the right of the application buttons and also contains panels for a user’s folders, tags, and saved searches. By defining a <zimletPanelItem> element, a Zimlet may add an item to the Zimlet panel within the overview panel. The user may interact with a Zimlet panel item by clicking, double clicking, right-clicking for a context menu, as well as by dragging and dropping various objects, such as contacts, conversations, and mail messages onto the panel item. As part of the panel item definition, the Zimlet author specifies the type of objects that the Zimlet supports as well the actions to be performed on those objects. If a Zimlet author does not wish to expose a panel item for their Zimlet, then this element may be omitted. The <zimletPanelItem> element is fully described in section </nowiki>  

=== Example ===

Below is an example outline of a Zimlet definition file: 
  
<pre> 
 <zimlet name="com_zimbra_sforce" version="1.0"
   description="Salesforce INTEGRATION">
 <include>sforce.js</include>
 <includeCSS>sforce.css</includeCSS>

 <handlerObject>Com_Zimbra_SForce</handlerObject>

 <zimletPanelItem label="Salesforce" icon="SFORCE-panelIcon">

    <toolTipText>
     Use drag'n'drop to interact with your SalesForce account
 </toolTipText>

  <dragSource type="ZmContact" />
  <dragSource type="ZmMailMsg" />
  <dragSource type="ZmConv" />

  <contextMenu>
    <menuItem label="Login" id="LOGIN" />
    <menuItem label="Preferences..." id="PREFERENCES" />
    <menuItem />
    <menuItem label="Visit Salesforce" id="WWW.SFORCE.COM "
      icon="SFORCE-panelIcon">
      <canvas type="dialog" title="Salesforce Website"
        width="800" height="600" />
      <actionUrl target="http://www.sforce.com ">
      <param name="referrer"> www.zimbra.com</param >
    </actionUrl>
         </menuItem>
  </contextMenu>

 </zimletPanelItem>

 <userProperties>
  <property type="string" name="user" minLength="4" maxLength="32"
    label="User ID" />
  <property type="password" name="passwd" minLength="4"
    maxLength="32" label="Password" />
 </userProperties>
 
 </zimlet> 
</pre>

== Common Elements ==
 
<nowiki>There are several elements that may appear in various contexts in both the <contentObject> and <zimletPanelItem> elements. This section describes these 

elements.</nowiki>  
 
=== <actionUrl> Element ===
 
<nowiki>The <actionUrl> element describes a URL that is called based on a given action. Examples of actions are clicking on a content object or dropping a contact 

onto a Zimlet panel item. The <actionUrl> element has several attributes:</nowiki>   
* method - The value of this attribute may be either “get” or “post”. If omitted, it defaults to the HTTP “get” method. 
* target - This attribute specifies the target URL. This may be either an absolute URL or a relative URL. 
* xslt – XSLT style sheet filename. This file must be part of the Zimlet bundle. If present the XSLT style sheet is applied to the result of the target. The output 

of applying the style sheet must be an HTML element such as a div. 
* paramStart – This attribute specifies the character to use when appending parameters to a GET URL. If omitted, the default is “?”. 
* paramJoin – This attribute specifies the character to use when appending additional parameters. If omitted, the default is “&”.  <nowiki>

In addition to the above attributes, the <actionUrl> element can have zero or more <param> element children. </nowiki>   <nowiki>The <param> element specifies 

parameters that are to be passed to the target URL. </nowiki><nowiki>The <param> element has a single required “name” attribute that specifies the parameter name. 

The content of the element is the value of the parameter. The possible content of the <param> element varies depending on the context in which the <actionUrl> 

element is being defined as follows:</nowiki>  
 
* <nowiki><contentObject></nowiki>  
** The value of the content object represented by the following: ${src.objectContent} 
** Arbitrary string content with or without ${src.foo} type variables. 
* <nowiki><zimletPanelItem></nowiki> 
** A ZCS object property. The valid set of object properties for the action depend on the object being dropped onto the panel Item. Object properties are prefixed 

with ‘${obj.‘and suffixed with ‘}’ for example, ${obj.cid}. ZCS objects and their properties are described in section ). 
** Arbitrary string content with or without ${src.foo} type variables  <nowiki>

Additionally if the <actionUrl> element appears alongside a <formEditor> element, then the values of the form fields (see </nowiki><nowiki>) are available to the 

<actionUrl>. Form fields are prefixed with ‘${form.‘and suffixed with ‘}’ for example, ${form.quantity}</nowiki>   <nowiki>

The Zimlet framework will package and send the parameters according to the value specified by the enclosing <actionUrl> element’s “method” attribute.</nowiki>   

<nowiki>The following is an example of a <actionUrl> element that may be defined for an action on a content object:</nowiki>   

<preset>
 <actionUrl method=”get” target=http://www.mapquest.com> 
 <param name=”address”>${src.objectContent}</param></nowiki>  <nowiki></actionUrl></nowiki>   
</preset>

Assuming the value for ${src.objectContent} is “111 Main St Anytown 94044”, then the Zimlet framework would send the following data to the server:  

 <nowiki> http://www.mapquest.com?address=111%20Main%20St%20Anytown%2094044 </nowiki>

Here is another example with static param value:   

 <nowiki><actionUrl method=”get” target=”http://www.amazon.com”></nowiki>  <nowiki><param name=”referrer”>www.zimbra.com</param></nowiki>   

<nowiki></actionUrl></nowiki>   <nowiki>

When inside a <contentObject> element, <param>-eters also support ${src.$1}, ${src.$2}, etc.  These will get replaced by contents of the N-th parentheses group in a 

matched string.  Let's take the “Bugz” Zimlet as an example.  It matches text such as "bug 1234", therefore ${src.objectContent} will be "bug 1234".  However, when 

the user clicks on the content object, it should open the bug URL from Bugzilla, so it needs _only_ the bug ID.  Therefore, the matching RegExp can be stated as:
</nowiki>     
 <nowiki><regex attr="ig">bug\s+([9-0]+)</regex></nowiki><nowiki>and the <actionUrl> can be stated as:</nowiki>  <nowiki><actionUrl  

target="http://bugzilla.zimbra.com/show_bug.cgi"></nowiki>   <nowiki><param name="id">${src.$1}</param></nowiki><nowiki>  </actionUrl></nowiki>   

=== <formEditor> Element ===

<nowiki>A form editor permits the definition of a form into which the user enters information that may be submitted to a remote server. The <formEditor> element 

specifies the following required attribute:</nowiki>   
* name – This is the name of the form. This name must be unique within the Zimlet definition file.  

<nowiki>The <formEditor> element may contain one or more <field> elements. There are several types of field elements, and they all share the following set of common 

attributes:</nowiki>   

* type - The type of the field such as “string”. The set of valid fields is described below. 
* name - The field name. 
* label - The label to be displayed for the field in the form editor. 
* value - The default value for the field (optional).  

<nowiki>If the <formEditor> element appears alongside an <actionUrl> element, then the fields of the form may be accessed in the actionUrl as described in section 

</nowiki><nowiki>. If there is no <actionUrl> element specified, then the Zimlet JavaScript class </nowiki>submitForm() method is called (see section )   

Following is a list of the available form field types.  

===='''number'''====

When a field’s type attribute is “number”, then the following optional attributes are available:  

* minVal - The minimum value permitted for the field 
* maxVal - The maximum value permitted for the field

===='''string'''====

When a field’s type attribute is “string”, then the following optional attributes are available:  
* minLength - The minimum length of the string 
* maxLength - The maximum length of the string 
* visualType – May be either “inputField” or “textArea”, corresponding to an input field or a multi-line text area respectively. If omitted it defaults to “inputField”. 
* numLines – Applicable only if the visualType is “textArea”. Specifies the number of lines that should be displayed in the text area. 
 
===='''password'''====  

A password is typically obfuscated as the user types it in. When a field’s type attribute is “password”, then the following optional attributes are available:  

* minLength - The minimum length of the string 
* maxLength - The maximum length of the string   

===='''date'''====
 
Dates are represented internally as milliseconds since the beginning of the Unix epoch.  

===='''boolean'''====
 
The Boolean type represents a “true” or “false” value. This is presented to the user as a check button. 
  
===='''enum'''====
  
The enum type represents a set of choices. This may be presented to the user as a dropdown box with a list of the valid choices or a set of radio buttons. A 

field of this type has one or more <nowiki><item></nowiki> child elements. 

The <item> element defines three attributes:
  
* label - The user interface label for the element. This is a required attribute. 
* value - The value for the item. This is a required attribute. 
* visualType – This may be either “select” or “radio” corresponding to a drop down select element or a set of radio buttons respectively. If omitted, then this 

value defaults to “select”.

===='''<nowiki><formEditor></nowiki> Example'''====
<pre> 
 <nowiki><formEditor name=”smsForm”></nowiki>  
       <nowiki><field type=”string” name=”phoneNo” label=”${msg.phoneNo}” </nowiki>  
             maxLength=”14”/>  
       <nowiki><field type=”string” name=”message” label=”${msg.message}” </nowiki>  
             visualType=”textArea” maxLength=”120” numLine=”10”/>  
 <nowiki></formEditor></nowiki> 
</pre>  
=== <canvas> Element ===

<nowiki>Certain actions may result in content being presented to the user. In certain cases this content is static, e.g. driving directions; in other cases it may 

be interactive, e.g. an html form. The <canvas> element describes the visual element into which such content is to be rendered. </nowiki>  
* type - This required attribute defines the type for the canvas. This may be one of: 

** none - There is no visual element for this action. 
** dialog - The visual will be a dialog. 
** tooltip – The visual will be a tool tip. 
** window - A new browser window will be created.   
* width - The width in pixels of the visual. This is an optional parameter and is ignored if the visual type is “none”. If this attribute is omitted, then the 

Zimlet framework will automatically size the content. 
* height - The height in pixels of the visual. This is an optional parameter and is ignored if the visual type is “none”. If this attribute is omitted, then the 

Zimlet framework will automatically size the content   <nowiki>

If this element is omitted from an action, it is the equivalent of specifying a <canvas> element with a type attribute value of “none”</nowiki>   

=== <contextMenu> Element ===

<nowiki>A context menu is usually popped up when the user right clicks the mouse over a content object or a panel item (should either be defined). The <contextMenu> 

element specifies the context menu items and their corresponding actions. The <contextMenu> element is optional and omitting it will disable the context menu for 

the Zimlet’s content object. </nowiki><nowiki>If present, the <contextMenu> element must contain one or more <menuItem> elements. </nowiki> 

===='''<nowiki><menuItem> Element</nowiki>'''====

<nowiki>A <menuItem> element describes an entry in the context menu. A <menuItem> element defines the following attributes:</nowiki>  

* id - A unique identifier for the menu item. This is a required attribute 
* label - This is the text that will be displayed for the menu item in the context menu 
* icon - The url of the icon to be displayed for the menu item (optional) 
* disabledIcon - The url of the icon to be displayed when this menu item is disabled (optional)  

It may contain the following child elements:
   
* <nowiki><canvas> - determines the visual for the menu item. The <canvas> element is described in section </nowiki> 
* <nowiki><actionUrl> - Specifies the URL to load. The <actionUrl> element is described in section </nowiki>. If this element is not present, then the Zimlet 

framework will call the Zimlet class’ menuItemSelected method (described in section ). Note that the only way to enable or disable a menu item is via the JavaScript 

methods.  

===='''<nowiki><contextMenu> Example</nowiki>'''====   

<pre>
<contextMenu>
   <menuItem label=”${msg.mapquest}” icon=”mapquest.gif” id=”MAPQUEST”>
     <canvas type=”window”/>
     <actionUrl target=”http://www.mapquest.com ”>
       <param name=””>${src.objectContent}</param>
     </actionUrl>
   </menuItem>

   <menuItem label=”${msg.yahooMaps}” icon=”yahoo.gif” id=”YAHOOMAPS”>
     <canvas type=”dialog” width=”200” height=”200”/>
   </menuItem>
 </contextMenu> 
</pre>
=='''<nowiki><contentObject></nowiki> Element'''==

A content object is an object that is recognized by a Zimlet in a body of content, such as email message body, the notes of an appointment, or fields in a contact. 

Examples of content objects are: Phone numbers, URLs, purchase order numbers, package tracking numbers, etc. <nowiki>The <contentObject> element defines the content 

object that a Zimlet recognizes and how the user interacts with the object. If a Zimlet does expose a content object, then this element may be omitted.</nowiki>   

<nowiki>The <contentObject> element may contain a number of child elements which will be described in the following sections.</nowiki>  
 
=== <matchOn> Element ===

<nowiki>Much as the <serverExtension> element specifies the rules that must be applied to match a content object for server side indexing, the <matchOn> element 

specifies the rules for the matching content objects on the client. There are two mechanisms that may be used to define these rules: 

</nowiki>   
# <nowiki>The first is with the <regex> element. The content of this element specifies a regular expression that defines the Zimlet’s content object. The format of 

this regular expression must follow the </nowiki>'''JavaScript''' regular expression grammar. The attrs attribute can be used to set any RegEx attributes. 

# If the content object matching rules cannot be expressed by a regular expression, then the Zimlet class’ match method (described section ) may be overridden to 

provide the matching rules  

'''<nowiki><matchOn> Example</nowiki>'''  

 <nowiki><matchOn></nowiki>  <nowiki><regex attrs=”ig”>1[zZ]\\s?\\w{3}\\s?\\w{3}\\s?\\</regex></nowiki>   <nowiki></matchOn></nowiki>  
 
=== <onClick> Element ===

<nowiki>The <onClick> element defines the behaviour for the click action. This usually means the user clicking on a content object with the left mouse button. 

<onClick> may have the following elements:</nowiki>   
* <nowiki><canvas> - determines the visual for the action. The <canvas> element is described in section </nowiki> 
* <nowiki><actionUrl> - Specifies the URL to be loaded. The <actionUrl> element is described in section </nowiki>. If this element is omitted, then the Zimlet 

framework’s will call the Zimlet class’ clicked method (described in section )  

'''<nowiki><onClick> Example</nowiki>'''  

<nowiki>In the example below, when the user clicks on the Zimlet content object, a new browser window of 300x300 pixel dimension is opened. The browser is loaded 

with the content of the URL specified in the <actionUrl> element</nowiki>   

 <nowiki><onClick></nowiki>  <nowiki><canvas type=”window” width=”300” height=”300”/></nowiki>  <nowiki><actionUrl method=”get”  target=”http://maps.google.com”

></nowiki>  <nowiki><param name=””>${src.objectContent}</param></nowiki>  <nowiki></actionUrl></nowiki>  <nowiki></onClick></nowiki>

=== <toolTip> Element ===
  
<nowiki>When a user hovers their mouse over an object, a tool tip may be popped up. The <toolTip> element controls the behaviour of this tool tip. The <toolTip> 

element has the following attributes:</nowiki>   

* sticky - This Boolean attribute may be set to “true” or “false”. If omitted, it will default to “false”. If set to “true”, then the tool tip becomes a sticky tool 

tip. Such a tool tip behaves as a standard tool tip (i.e. will be dismissed on the appropriate amount of mouse motion) unless the user clicks within its content, at 

which time it will remain “popped up” requiring the user to explicitly dismiss it. Sticky tool tips are a hybrid between dialogs and standard tool tips. They are 

useful when the user is able to interact with the content of the tool tip - for example to zoom into the map of an address. If the sticky attribute is set to false, 

then the tool tip behaves as a traditional tool tip and will be dismissed when the user moves their mouse. 
* width - The width in pixels of the tool tip content. If this attribute is omitted, then the Zimlet framework will automatically size the tool tip. 
* height - The height in pixels of the tool tip content. If this attribute is omitted, then the Zimlet framework will automatically size the content  

<nowiki>The <toolTip> element may also contain the following child element:</nowiki> 
 
* <nowiki><actionUrl> - Specifies the URL to be loaded. The <actionUrl> element is described in section </nowiki>. If this element is omitted, then the Zimlet 

framework will call the Zimlet class’ toolTipPoppedUp method (described in section ). If the tool tip is a sticky tool tip, then when it is dismissed the Zimlet 

class’ toolTipPoppedDown method (described in section ) will be called.   

===='''<nowiki><toolTip> Example</nowiki>'''====

<pre>
   <nowiki><toolTip sticky=”true” width=”100” height=”200”></nowiki>  
         <nowiki><actionUrl method=”get” target=”http://maps.google.com”></nowiki>  <nowiki>
               <param name=””>${src.objectContent}</param></nowiki>           <nowiki></actionUrl></nowiki>  
   <nowiki></toolTip></nowiki>   
</pre>

== <serverExtension> Element ==

<nowiki>To have the ZCS server provide an index for a contentObject defined by a Zimlet, a <serverExtension> element must be provided. This element has a number of 

important attributes which determine how indexing takes place on the server:</nowiki>
   
* hasKeyword - This attribute specifies the keyword that will be used with the query language’s “has” clause e.g. “has:address”, or “has:id”. 
* regex - This attribute specifies a regular expression that defines the Zimlet’s content object. The format of this regular expression must follow the '''Java 

Development Kit (JDK)''' regular expression grammar. This attribute is mutually exclusive with the extensionClass attribute below 
* extensionClass - If the content object matching rules cannot be expressed by a regular expression, then the extensionClass attribute may be specified. The content 

of this attribute specifies a Java class that extends the com.zimbra.cs.zimlet.ZimletHandler interface. This class file must be part of the Zimlet bundle.
  ===='''<nowiki><serverExtension> Example</nowiki>'''====   

<pre>
 <nowiki><serverExtension hasKeyword=”address” </nowiki>  
       extensionClass=”com.acme.Matcher”/>   
</pre>

=== ZimletHandler Interface  ===

When a regular expression is insufficient for identifying a Zimlet’s content object, the Zimlet developer may provide a Java class that implements the 

com.zimbra.cs.zimlet.ZimletHandler interface with the match() method as shown below:    

 <nowiki>public String[] match(String text)</nowiki>   

Parameter: 
 
* ''text'' - The text to be parsed for content objects   

Return Value:  

* array of String containing content objects.   

== <zimletPanelItem> Element ==

<nowiki>The Zimlet panel appears within the ZCS AJAX client’s overview panel. The overview panel is to the right of the application buttons and also contains panels 

for a user’s folders, tags, and saved searches. By defining a <zimletPanelItem> a Zimlet may add an item to the Zimlet panel within the overview panel. The user may 

interact with a Zimlet panel item by doubling clicking it, as well as by dragging and dropping various objects, such as contacts, conversations, and mail messages 

onto it. As part of the panel item definition, the Zimlet author specifies the types of objects that the Zimlet supports as well the actions to be performed on 

those objects. If a Zimlet author does not wish to expose a panel item for their Zimlet, then this element may be omitted.</nowiki>   

<nowiki>The <zimletPanelItem> defines the following attributes:</nowiki>  
 
* label - The label will be displayed as the text label for the Zimlet panel item 
* icon - The url of the icon to be displayed as the Zimlet panel item’s icon (optional)  

<nowiki>The <zimletPanelItem> element may contain a number of child elements which will be described in the following sections.</nowiki>   

=== <toolTipText> Element ===

This optional element defines the tool tip text to be displayed when a user hovers their mouse over the Zimlet panel item   

'''<nowiki><toolTipText> example</nowiki>'''   

 <nowiki><toolTipText>${msg.panelTooltipText}</toolTipText> </nowiki>   
 <nowiki><toolTipText>Drag and drop a contact</toolTipText> </nowiki> 

=== <doubleClicked> Element ===

<nowiki>The <doubleClicked> element defines the behavior for the double click action. This usually means the user double clicking the left mouse button on the 

Zimlet panel item. The <doubleClicked> element may contain the following elements:</nowiki>   

* <nowiki><canvas> - Determines the visual for the action. The <canvas> element is described in section </nowiki> 
* <nowiki><actionUrl> - Specifies the URL to loaded. The <actionUrl> element is described in section </nowiki>. If this element is omitted, then the Zimlet 

framework will call the Zimlet class’ doubleClicked method (described in section )  

'''<nowiki><doubleClicked> Example</nowiki>''' 
<pre>  <nowiki><doubleClicked></nowiki>  
     <nowiki><canvas type=”window” width=”300” height=”300”/></nowiki>  
     <nowiki><actionUrl method=”get” target=http://maps.google.com/></nowiki>  
<nowiki></doubleClicked></nowiki> 
</pre>

=== <singleClicked> Element ===

<nowiki>The <singleClicked> element defines the behaviour for the single click action. This usually means the user single clicks the left mouse button on the Zimlet 

panel item. <singleClicked> may have the following elements:</nowiki>   
* <nowiki><canvas> - Determines the visual for the action. The <canvas> element is described in section </nowiki> 
* <nowiki><actionUrl> - Specifies the URL to be loaded. The <actionUrl> element is described in section </nowiki>. If this element is omitted, then the Zimlet 

framework will call the Zimlet class’s singleClicked method (described in section )  

'''<nowiki><singleClicked> Example</nowiki>'''  
 <pre>
<nowiki><singleClicked></nowiki>  
    <nowiki><canvas type=”window” width=”300” height=”300”/></nowiki>  
    <nowiki><actionUrl method=”get” target=http://maps.google.com/></nowiki> 
<nowiki></singleClicked></nowiki>   
</pre>

=== <dragSource> Element ===

<nowiki>The <dragSource> element specifies a drag source for the Zimlet panel item. A drag source consists of a ZCS object type e.g. a conversation, a contact, or a 

mail message (for a complete discussion of valid objects and object properties see section </nowiki><nowiki>) and the action to be performed when a object of that 

type is dropped on the panel item. There may be zero or more <dragSource> items specified for a Zimlet panel item. The <dragSource> element requires a single 

attribute named “type”. This attribute specifies the drag source type and may be one of the objects specified in section </nowiki><nowiki>. The <dragSource> item 

may also contain the following child elements:</nowiki>   

* <nowiki><canvas> - determines the visual for the drop action. The <canvas> element is described in section </nowiki> 
* <nowiki><actionUrl> - Specifies the URL to be loaded when an item of the type specified in the <dragSource> element’s type attribute is dropped onto the Zimlet 

panel item. The <actionUrl> element is described in section </nowiki>. If this element is omitted, then the Zimlet framework will call the Zimlet class’ doDrag 

method (described in section <nowiki>) when an object of the type specified by the <dragSource> element’s type attribute is dragged onto the panel item. If the item 

is dropped on the panel item, the Zimlet class’s </nowiki>doDrop method (described in section ) is called.  

'''<nowiki><dragSource> Example</nowiki>''' 
<pre>  <nowiki><dragSource type=”Contact”></nowiki>  
     <nowiki><canvas type=”inline” width=”200” height=”150”/></nowiki>  
     <nowiki><actionUrl target=”http://maps.google.com”></nowiki> 
          <nowiki><param name=””>${obj.homeAddress}</param></nowiki>  
<nowiki></actionUrl></nowiki>  <nowiki></dragSource></nowiki> 
</pre>  

=== ZCS Objects and Object Properties ===

This section describes the set of ZCS objects that may be specified as drag source types. In addition, the set of attributes available as URL parameters is 

enumerated for each object type.    

<nowiki>These public attributes may be accessed by specifying it as the value of a <actionUrl> element’s <param> child. In this case the attribute may be accessed 

by enclosing it with “${}” and scoped with “obj”. For example to access the Conversation object’s subject attribute, one would specify ${obj.subject}</nowiki>   

The following JavaScript types are converted to URL encoded formats using the following rules: 
  
* '''Int''' - Passed as simple integer value, e.g. http://acme.com/service?msgId='''8273828''' 
* '''String''' - Passed as simple string value, e.g. http://acme.com/service?subject='''Hello%20World''' 
* '''Array''' – Passed as a comma separated list of values. If there is a comma in the value, it will be escaped with a backslash: \, 
* '''Boolean''' – Passed as 1 for TRUE, and 0 for FALSE 
* '''Date''' – Passed as an integer representing the number of milliseconds since the beginning of the Unix epoch  '''ZmConv'''  ZmConv class represents a 

conversation. A Conversation is a set of email messages related by the same subject and received within a defined period of time. 

The following attributes are exported for use as URL parameters:  
 
* '''id'''<nowiki> [Int]- Conversation ID</nowiki> 
* '''subject'''<nowiki> [String] - Conversation subject i.e. subject of the first message in the conversation</nowiki> 
* '''date'''<nowiki> [Date] - Receipt date of the first matched message based on sort order</nowiki> 
* '''fragment'''<nowiki> [String] - Fragment from the first matched message based on sort order</nowiki> 
* '''participants'''<nowiki> [Array(string)] - </nowiki>Up to five participants email addresses including the originator of the conversation. 
* '''numMsgs'''<nowiki> [Int] - Number of messages in the conversation</nowiki> 
* '''tags'''<nowiki> [Array(Int)] - Union of the set of tags on the messages in this conversation. May be null. Comma separated list when passed to a URL</nowiki> * 

'''flagged'''<nowiki> [Boolean] - True if one or more messages in the conversation has been flagged</nowiki> 
* '''unread'''<nowiki> [Boolean] - True if one or more </nowiki>messages in the conversation is unread 
* '''attachment'''<nowiki> [Boolean] - True if one or messages in the conversation has an attachment </nowiki> * '''forwarded '''<nowiki>[Boolean] - True if one or 

</nowiki>more messages in the conversation has been forwarded  * '''sent'''<nowiki> [Boolean] - True if the user has participated in the conversation</nowiki> * 

'''replied'''<nowiki> [Boolean] - True if one or more messages have been replied to by the user</nowiki> * '''draft'''<nowiki> [Boolean] - True if the conversation 

contains a draft message. Note that a conversation containing a draft message will only contain that message.</nowiki>  

'''ZmMailMsg'''  

The ZmMailMsg object represents a mail message. The following attributes are exported for use as URL parameters: 
  
* '''id'''<nowiki> [Int]- Message ID for the message</nowiki> 
* '''convId'''<nowiki> [Int]- Conversation ID for the message</nowiki> 
* '''from'''<nowiki> [String] - Email address from the “From:” header</nowiki> 
* '''to'''<nowiki> [Array(String)] - List of email addresses from the “To:” header</nowiki> 
* '''cc'''<nowiki> [Array(String)] - List of email addresses from the “Cc:” header</nowiki> * '''subject'''<nowiki> [String] - Message subject</nowiki> 
* '''date'''<nowiki> [Date] - Receipt or sent date of the message</nowiki> 
* '''size'''<nowiki> [Int] - Size in bytes of the message</nowiki> 
* '''fragment'''<nowiki> [String] - Fragment from the message</nowiki> 
* '''tags'''<nowiki> [Array(Int)] - Set of tags on the message</nowiki> 
* '''flagged'''<nowiki> [Boolean] - True if the message has been flagged</nowiki> 
* '''unread'''<nowiki> [Boolean] - True if the message is unread</nowiki> 
* '''attachment'''<nowiki> [Boolean] - True if the message has an attachment </nowiki> 
* '''forwarded '''<nowiki>[Boolean] - True if the message has been forwarded </nowiki> 
* '''sent'''<nowiki> [Boolean] - True if this message was sent by the user</nowiki> 
* '''replied'''<nowiki> [Boolean] - True if the user has replied to this message</nowiki> 
* '''draft'''<nowiki> [Boolean] - True if this is a draft message.</nowiki>  

'''ZmContact'''  

The ZmContact object represents a contact. The following attributes are exported for use as URL parameters:
   
* '''assistantPhone'''<nowiki> [String]</nowiki> 
* '''callbackPhone'''<nowiki> [String]</nowiki> 
* '''carPhone'''<nowiki> [String]</nowiki> 
* '''company'''<nowiki> [String]</nowiki> 
* '''companyPhone'''<nowiki> [String]</nowiki> 
* '''email'''<nowiki> [String]</nowiki> 
* '''email2'''<nowiki> [String]</nowiki> 
* '''email3'''<nowiki> [String]</nowiki> 
* '''fileAs'''<nowiki> [String]</nowiki> 
* '''firstName'''<nowiki> [String]</nowiki> 
* '''homeCity'''<nowiki> [String]</nowiki> 
* '''homeCountry'''<nowiki> [String]</nowiki> 
* '''homeFax'''<nowiki> [String]</nowiki> 
* '''homePhone'''<nowiki> [String]</nowiki> 
* '''homePhone2'''<nowiki> [String]</nowiki> 
* '''homePostalCode'''<nowiki> [String]</nowiki> 
* '''homeState'''<nowiki> [String]</nowiki> * '''homeStreet'''<nowiki> [String]</nowiki> 
* '''homeURL'''<nowiki> [String]</nowiki> 
* '''jobTitle'''<nowiki> [String]</nowiki> 
* '''lastName'''<nowiki> [String]</nowiki> 
* '''middleName'''<nowiki> [String]</nowiki> 
* '''mobilePhone'''<nowiki> [String]</nowiki> 
* '''namePrefix'''<nowiki> [String]</nowiki> * '''nameSuffix'''<nowiki> [String]</nowiki> 
* '''notes'''<nowiki> [String]</nowiki> 
* '''otherCity'''<nowiki> [String]</nowiki> 
* '''otherCountry'''<nowiki> [String]</nowiki> 
* '''otherFax'''<nowiki> [String]</nowiki> 
* '''otherPhone'''<nowiki> [String]</nowiki> 
* '''otherPostalCode'''<nowiki> [String]</nowiki> 
* '''otherState'''<nowiki> [String]</nowiki> 
* '''otherStreet'''<nowiki> [String]</nowiki> 
* '''otherURL'''<nowiki> [String]</nowiki> 
* '''pager'''<nowiki> [String]</nowiki> 
* '''workCity'''<nowiki> [String]</nowiki> 
* '''workCountry'''<nowiki> [String]</nowiki> 
* '''workFax'''<nowiki> [String]</nowiki> 
* '''workPhone'''<nowiki> [String]</nowiki> 
* '''workPhone2'''<nowiki> [String]</nowiki> 
* '''workPostalCode'''<nowiki> [String]</nowiki>  
* '''workState'''<nowiki> [String]</nowiki>
* '''workStreet'''<nowiki> [String]</nowiki> 
* '''workURL'''<nowiki> [String]</nowiki>  

'''ZmAppointment'''  
 
* '''id'''<nowiki> [Int] - Mail item id</nowiki>  
* '''uid'''<nowiki> [String] - iCal UID of the appointment</nowiki> 
* '''type'''<nowiki> [String] - Appointment type: Event or Todo</nowiki> * '''subject'''<nowiki> [String] - Appointment subject</nowiki> 
* '''startDate'''<nowiki> [Date] - Appointment start date</nowiki> 
* '''endDate'''<nowiki> [Date] - Appointment end date</nowiki> 
* '''allDayEvent'''<nowiki> [Boolean] - True if an all day event, false otherwise</nowiki> 
* '''exception'''<nowiki> [Boolean] - True if this is an exception to a repeating appointment</nowiki> 
* '''recurring'''<nowiki> [Boolean] - True if this is a recurring appointment</nowiki> 
* '''alarm'''<nowiki> [Boolean] - True if the appointment has an alarm</nowiki> 
* '''otherAttendees'''<nowiki> [Boolean] - True if there are other attendees </nowiki> 
* '''attendees'''<nowiki> [Array(String)] - List of other attendees</nowiki> 
* '''location'''<nowiki> [String] - Location of the appointment</nowiki> 
* '''notes'''<nowiki> [String] - Notes</nowiki> 
* '''isRecurring'''<nowiki> [Boolean] - True if the appointment is a recurring appointment</nowiki> 
* '''timeZone'''<nowiki> [String] - Appointment’s timezone</nowiki>  

== <userProperties> Element ==

User properties enable Zimlets to store per user state. If a Zimlet defines user properties, then a properties menu item is added to the Zimlet’s panel item and content object context menu.  When the user selects the properties menu item, she is presented with a property editor with which to edit the Zimlet’s user properties. The property editor is constructed by the Zimlet class’ [[Zimlet_JavaScript_Class_WP#createPropertyEditor_Method|createPropertyEditor]] method. The default implementation of this method will “auto-create” a property editor. Zimlet implementers are free to override this method in order to provide a custom editor.   

=== <property> ===
The <userProperties> element may contain one or more '''<property>''' elements as its children. There are several types of property elements. They all share the following set of common attributes:

* type - The type of the property such as “string”. The set of valid properties is described below 
* ''name'': The variable name of the user property.
* ''label'': The "pretty name" of the user property to be displayed in the Property Editor.  If it does not exist, it will default to value of the ''name'' property.
* ''Visible'': True if the property should be displayed in the Property editor.  This attribute is only required if the <userProperties> element’s editor attribute is set to “standard”
* ''value'': The pre-populated value of the property.  It will be displayed in the Property Editor property field.  This is optional.
* ''Type'': This will be one of
** Zimlet.STRING_PROP
** Zimlet.PASSWORD_PROP
** Zimlet.NUMBER_PROP
** Zimlet.DATE_PROP
** Zimlet.SELECT_PROP

The properties are supported for the specific property types:
* string
**minLen - Minimum length for the string (optional)
**maxLen - Maximum length for the string (optional)
** visualType – May be either “inputField” or “textArea” corresponding to an input field or a multi-line text area respectively. If omitted it defaults to “inputField”
** numLines – Applicable only if the visualType is “textArea”. Specifies the number of lines that should be displayed in the text area.  
* password
**minLen - Minimum length for the string (optional)
**maxLen - Maximum length for the string (optional)
* number
**minVal - Minimum value for the number (optional)
**maxVal - Maximum value for the number (optional)
*date:  Dates are represented internally as milliseconds since the epoc.
**N/A
* select
**items - an array of the items in the select. There will always be atleast one item in this array. Each item has two keys.
***label - The label to be displayed for the item (Required)
***value - The value for the item (Required)
* boolean:  The Boolean type represents a “true” or “false” value. This is presented to the user as a check button.
* enum:  The enum type represents a set of choices.  This may be presented to the user as a dropdown box with a list of the valid choices or a set of radio buttons. A property of this type has one or more <item> child elements. The <item> element defines three attributes:
** label - The user interface label for the element. This is a required attribute. 
** value - The value for the item. This is a required attribute. 
** visualType – This may be either “select” or “radio”. If omitted, then this value defaults to “select”  

The [[Zimlet JavaScript Class]] may access a <property> '' value'' with [[Zimlet_JavaScript_Class#getUserPropertyInfo|getUserPropertyInfo]].

The Zimlet definition file may accesa a <property> ''value'' by enclosing the property name with “${}”, and scoping it with “prop”.  For example to access a property name “username”, one would specify ${prop.userName}

=== <userProperties> Example ===
<pre>
<userProperties editor=”standard”>
  <property type=”string” name=”uname” label=”${msg.uname}” visible=”true” minLength=”4” maxLength=”8”/>
   <property type=”password” name=”pword” label=”${msg.pword}” visible=”true” minLength=”4” maxLength=”8”/>
   <property type=”select” name=”pageSize” label=”${msg.pageSize}”
     visible=”true”>
     <item label=”10” value=”10”/>
     <item label=”20” value=”20”/>
     <item label=”50” value=”50”/>
   </property>
 </userProperties> 
</pre>

== See also ==
* [[Zimlet_Examplel_xml_Maps]]

{{Article Footer||7/16/2009}}
[[Category:Zimlets]]