Zimlet JavaScript Class
|
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 Javascript Class
The Zimlet framework provides the Zimlet JavaScript base class. Developers wishing to implement Zimlet functionality directly in JavaScript should extend this class. The name of the derived class, as well as the file in which the class is defined should be the same as the Zimlet name.
The methods comprising the Zimlet base class (ZmZimletBase.js) may be divided into the following categories:
- Methods related to the Zimlet panel items.
- Methods related to content objects
- Helper methods
There are certain formal parameters that are common to a number of methods defined by the Zimlet class:
- Parameters common to Zimlet panel item methods:
- zmObject - This parameter is common to certain Zimbra Panel Item methods. It represents the ZCS object that has been dropped onto the panel item. The types of ZCS objects and their respective properties are described in section 3.5.5
- Parameters common to content object methods:
- spanElement - This parameter is common to certain content object methods. It represents the HTML <span> element that surrounds the content object text the content that is rendered in the user's browser. The content object methods may manipulate the CSS style of this element to reflect such things as state change based on a user's actions. For example, if a user selects to approve a purchase order from a context menu, the Zimlet developer may wish to turn the content object representing the purchase order green.
- contentObjText - The content object text of the content object being acted upon
- Parameters common across methods:
- canvas - The value of this parameter is driven by the corresponding <canvas> element in the Zimlet Definition File. The list
below enumerates the value of th canvas parameter for each value of the <canvas> element's type attribute:
- none - canvas will be null
- dialog - will be an instance of the DwtDialog class. DwtDialog is a component of the DHTML Widget Toolkit (DWT) library that is itself a package in the Zimbra AJAX Toolkit. Instances of DwtDialog may have DWT widgets such as buttons and trees added to them at runtime. However, the decision to use the DWT widget set is optional. By calling the getHtmlElement() method of a composite object a handle may be obtained to <composite>'s DOM element. This element is a object that may be arbitrarily manipulated. For example, any HTML content may be placed within thisby setting its innerHTML attribute.
- tooltip - canvas will be a DwtToolTip
- window - canvas is a handle to the new browser window.
The only exception to the above is for the toolTipPoppedUp method. In this case, the canvas parameter will always be a DwtComposite object.
the remainder of this section will describe the methods defined by the Zimbra class.
Zimlet Panel Item Methods
Zimlet panel item methods are invoked via the elements of the <zimletPanelItemt> element within
the Zimlet definition file
doDrag Method
This method is called when an item is dragged on the Zimlet drop target as realized in the UI. It is invoked from within the <dragSource> element. This method is only called for the valid types that the Zimlet accepts. This method can perform additional validation based on semantic information beyond the type of the object being dragged onto the Zimlet. This method defines the following formal parameters:
* zmObject
* Return true if the drag should be allowed, false otherwise.
doDrop Method
This method is called when an item is dropped on the Zimlet item as realized in the UI. At this point the Zimlet should perform the actions it needs to for the drop. This method defines the following formal parameters:
* zmObject
* canvas
* Return void
singleClicked Method
This method is called when a panel item is clicked once. Beware that it may be called once or twice during a doubleClick.
* canvas
* Return void
doubleClicked Method
This method is called when the Zimlet panel item is double clicked. This method defines the following formal parameters:
* canvas
* Return void
Content Object Methods
Content object methods are invoked via the elements of the <contentObject> element within the Zimlet definition file
match Method
This method is called when content (e.g. a mail message) is being parsed. The match method may be called multiple times for a given piece of content and should apply whatever pattern matching is required to identify objects in the content. This method defines the following formal parameters
* content - The content against which to perform a match
* startIndex - Index in the content at which to begin the search
* Return the first content object match in the content starting from startIndex
clicked Method
The clicked method is called when a Zimlet content object is clicked on by the user. This method defines the following formal parameters
* spanElement
* contentObjText
* matchContext
* canvas
* Returns void
toolTipPoppedUp Method
This method is called when the tool tip is being popped up. This method defines the following formal parameters:
* spanElement
* contentObjText
* matchContext
* canvas
* Returns void
toolTipPoppedDownMethod
This method is called when the user is popping down a sticky tool tip. It defines the following formal parameters:
* spanElement
* contentObjText
* matchContext
* canvas
* Returns null if the tool tip may be popped down, else return a string indicating why the tool tip should not be popped down
Common Methods
The menuItemSelected method is called when a context menu item is selected by the user. It defines the following formal parameters:
* contextMenu - Identifies the context menu from which the item was selected. This may be
* Zimlet.PANEL_MENU
* Zimlet.CONTENTOBJECT_MENU.
* menuItemId - This is the ID that is provide in the <menuItem> elements id attribute
* spanElement
* contentObjText
* canvas
* Return void
createPropertyEditor Method
This method is called by the Zimlet framework if there is a <userProperties> element specified in the Zimlet definition file. Specifically, the framework will add a properties menu item to the Zimlet panel item and content object action menus (if one or both are defined). When this menu item is selected, the property editor will be presented to the user. This method’s responsibility is to create a property editor for the set of properties defined in the <userProperties> element. The default implementation of this method will “auto-create” a property editor based on the attributes of the Zimlet’s user properties. Zimlet implementers should override this method if a custom property editor is required. createProperty defines the following formal parameters:
* dialog - An instance of a DwtDialog widget. This widget should be populated with the right sets of fields/data to represent the Zimlet’s properties. In addition, this method will register a callback for the dialog’s “ok” button. This callback will generally save changed properties by calling the saveUserProperties method
* Return void
submitForm Method
This method is called by the Zimlet framework when the user clicks on the submit button of a form that is generated by the <formEditor> element (see 3.2.2). This method defines the following formal parameters:
* formName – The name of the form that is being submitted
* formFields – a Hash of the form fields. The key is the field name, and the value is the value the user entered for the field.
Helper Methods
Helper methods are provided by the Zimlet class to provide common utility functions for derived classes. These methods are typically not overridden.
applyXslt
This method will apply and XSL transformation to an XML document (e.g. one returned from a webservices call). This method defines the following formal parameters:
* xsltUrl – This is the URL to the XSLT style sheet.
* document – XML document (or AjxXmlDoc) to which the style sheet is to be applied
* Return an AjxXmlDoc representing the transformed document.
checkProperties
Called just before the properties are saved. Allows the Zimlet writer to validate properties one last time before they are saved.
* props – The properties that are about to be saved
* Return true is the properties are valid. If a string is returned then a error dialog is displayed.
enableContextMenuItem Method
This method provides the ability to enable and disable menu items in the context menu. This methods takes the following formal parameters:
* contextMenu - Identifies the context menu from which the item was selected. This may be
* Zimlet.PANEL_MENU
* Zimlet.CONTENTOBJECT_MENU.
* menuItemId - The menu item on which to act
* enabled - a Boolean that if set to true will enable the menu item, and if set to false will disable the item
getConfigProperty Method
This method returns the value of the requested global or host property. It defines the following formal parameters:
* propertyName - This is the name of the property whose value is to be returned. For example: “global.someProperty” or “host.someProperty”
* Return the value of the property, or null if no such property exists
getResource
This method returns the fully qualified URL of a resource specified by the <resource> element. var imageURL = this.getResource(“image.gif”);
getUserPropertyInfo
getUserPropertyInfo provides a specified property from the Zimlet Definition File. It returns a hash of the key/value pairs in a <property> tag or null if no such property exists.
The getUserPropertyInfo method defines the following formal parameters:- propName: The user property name as a "string".
For example, to return the value of the user property websiteUrl would be
// this.getUserProperty(“PropertyName”)
this.getUserPropertyInfo("websiteUrl")["value"];
getUsername
This method returns the current user’s username
saveUserProperties
This method will save the value of any modified properties to ZCS. It takes no formal parameters.
sendRequest Method
The sendRequest method enables asynchronous communications with a remote server. This method defines the following formal parameters
* requestStr - the request string that is to be sent to the remote server
* serverUrl - the URL of the remote server. Note that due to security constraints this must be the ZCS server (i.e. the server from which the JavaScript originated); however it is actually possible to communicate with a remote server by using the Zimlet framework’s proxy servlet (see section 6)
* requestHeaders - a JavaScript array of HTTP request headers
* callback. This is an instance of the AjxCallback class. The AjxCallback class provides a mechanism for encapsulating callbacks. It’s constructor defines the following formal parameters:
* obj - Generally obj is a reference to “this” object.
* func- The function to call. If obj is not null, then the value of “this” when func is
* called will be obj
* args - Arguments to be passed to the func. This may be a single value or a JavaScript array of values.
An example of how to construct an AjxCallback object is as follows:
new AjxCallback(this, MyZimlet.prototype.asyncCallback, [this._val1, this._val2]);
* useGet - if True, then the HTTP “get” method is used. In this case the requestStr should generally be null since the serverUrl will contain the query parameters.
setUserProperty
This method sets the value of a user property. It defines the following formal parameters:
* propertyName - This is the name of the property whose value is to be returned. For example: “someUserProperty”
* value - The value to which to set the property
* save - If true, then the property will be saved (along with any other modified properties)
* Return void
* Throws ZimletException if no such property exists or if the value is not valid for the property type. A ZimletException is a JavaScript class derived from base AJAX Exception class that is a component of the Zimbra AJAX Toolkit.
