Zimlet JavaScript API Reference - ZmZimletBase

Class ZmZimletBase


Extends ZmObjectHandler.

This class provides the default implementation for Zimlet functions. A Zimlet developer may wish to override some functions in order to provide custom functionality. All Zimlet Handler Objects should extend this base class.

function com_zimbra_myZimlet_HandlerObject() { };

com_zimbra_myZimlet_HandlerObject.prototype = new ZmZimletBase(); com_zimbra_myZimlet_HandlerObject.prototype.constructor = com_zimbra_myZimlet_HandlerObject;

Defined in: ZmZimletBase.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
Field Summary
Field Attributes Field Name and Description
<static>  
ZmZimletBase.CONTENTOBJECT_MENU
This defines the Content Object Menu.
<static>  
ZmZimletBase.PANEL_MENU
This defines the Panel Menu.
Method Summary
Method Attributes Method Name and Description
 
addCustomMimeHeaders(customMimeHeaders)
This Zimlet hook allows Zimlets to set custom headers to outgoing emails.
 
addSearchDomainItem(icon, label, listener, id)
Adds an item to the search toolbar drop-down.
 
appActive(appName, active)
This method gets called each time the "tab" application is opened or closed.
 
appendExtraSignature(contact, oldMsg)
This method is called by the Zimlet framework when adding a signature to an email message.
 
appLaunch(appName)
This method gets called when the "tab" application is opened for the first time.
 
applyXslt(xsltUrl, doc)
This method will apply and XSL transformation to an XML document.
 
This method is called by the zimlet framework prior to user properties being saved.
 
clicked(spanElement, contentObjText, matchContent, event)
This method is called when a zimlet content object is clicked.
 
createApp(label, image, tooltip, index, style)
Creates a "tab" application and registers this zimlet to receive #appActive and #appLaunch events.
 
This method is called if there are <userProperties> elements specified in the Zimlet Definition File.
 
displayErrorMessage(msg, data, title)
Displays the specified error message in the standard error dialog.
 
Displays the specified status message.
 
doDrag(zmObject)
This method is called when an item is dragged on the Zimlet drop target in the panel.
 
doDrop(zmObject)
This method is called when an item is dropped on the Zimlet in the panel.
 
doubleClicked(canvas)
This method gets called when a double-click is performed.
 
emailErrorCheck(msg, boolAndErrorMsgArray)
This method is called by the Zimlet framework when a message is about to be sent.
 
enableContextMenuItem(contextMenu, menuItemId, enabled)
Enables the specified context menu item.
 
getConfigProperty(propertyName)
Gets the configuration property.
 
Gets the message property.
 
Gets the message properties.
 
getMsgsForConv(callback, conv)
Gets the mail messages for the conversation.
 
getResource(resourceName)
Gets the fully qualified resource Url.
 
Gets the text field value entered in the search bar.
 
Gets the shell for the zimlet.
 
Gets the current user id.
 
Gets the current username.
 
getUserProperty(propertyName)
Gets the user property.
 
getUserPropertyInfo(propertyName)
Gets the user property info for the specified property.
 
Gets the zimlet context.
 
Gets the zimlet manager.
 
init()
This method is called by the Zimlet framework to indicate that the zimlet it being initialized.
 
initializeToolbar(app, toolbar, controller, viewId)
This method is called by the Zimlet framework when application toolbars are initialized.
 
match(content, startIndex)
This method is called when content (e.g.
 
menuItemSelected(contextMenu, menuItemId, spanElement, contentObjText, canvas)
This method is called when a context menu item is selected.
 
onAction(type, action, currentViewId, lastViewId)
This method by the Zimlet framework when an application action occurs.
 
onActionMenuInitialized(controller, actionMenu)
This method gets called by the Zimlet framework when the action menu is initialized on the subject/fragment of an email message.
 
onContactEdit(view, contact, elementId)
This method is called by the Zimlet framework when a contact is edited.
 
onContactView(contact, elementId)
This method is called by the Zimlet framework when a contact is clicked-on in the contact list view.
 
onFindMsgObjects(msg, objMgr)
This method is called by the Zimlet framework when a user clicks-on a message in either the message or conversation view).
 
This method is called by the Zimlet framework when enter is pressed in the search field.
 
onMailConfirm(confirmView, msg)
This method is called by the Zimlet framework when the message confirmation dialog is presented.
 
onMailFlagClick(items, on)
This method is called by the Zimlet framework when an email message is flagged.
 
onMsgView(msg, oldMsg, msgView)
This method is called by the Zimlet framework when a user clicks-on a message in the mail application.
 
onParticipantActionMenuInitialized(controller, actionMenu)
This method gets called by the Zimlet framework when the action menu is initialized on the from/sender of an email message.
 
onSearch(queryStr)
This method is called by the Zimlet framework when a search is performed.
 
This method is called by the Zimlet framework when the search button is clicked.
 
This method by the Zimlet framework when an application button is pressed.
 
onShowView(view)
This method is called by the Zimlet framework when showing an application view.
 
onTagAction(items, tag, doTag)
This method is called by the Zimlet framework when an email message is tagged.
 
portletCreated(portlet)
This method is called by the Zimlet framework when the portlet is created.
 
This method is called by the Zimlet framework when the portlet is refreshed.
 
resetToolbarOperations(parent, enable)
Reset the toolbar
 
Saves the user properties.
 
sendRequest(requestStr, serverURL, requestHeaders, callback, useGet, passErrors)
Sends the request content (via Ajax) to the specified server.
 
setTooltipSticky(sticky, popdown)
This method is called when a sticky tooltip is clicked, when clicking outside a sticky tooltip, or when a zimlet wants to stick or unstick a tooltip.
 
setUserProperty(propertyName, value, save, callback)
Sets the value of a given user property
 
singleClicked(canvas)
This method gets called when a single-click is performed.
 
toolTipPoppedDown(spanElement, contentObjText, matchContent, canvas)
This method is called when the tool tip is popping-down.
 
toolTipPoppedUp(spanElement, contentObjText, matchContent, canvas)
This method is called when the tool tip is popping-up.
 
Returns a string representation of the zimlet.
Methods borrowed from class ZmObjectHandler:
getActiveClassName, getClassName, getHoveredClassName, getToolTipText, getTypeName, hasToolTipText, populateToolTip, selected
Class Detail
ZmZimletBase()
See:
#init
Field Detail
<static> ZmZimletBase.CONTENTOBJECT_MENU
This defines the Content Object Menu.
See:
#menuItemSelected}

<static> ZmZimletBase.PANEL_MENU
This defines the Panel Menu.
See:
#menuItemSelected}
Method Detail
addCustomMimeHeaders(customMimeHeaders)
This Zimlet hook allows Zimlets to set custom headers to outgoing emails. To set a custom header, they need to push header name and header value to customMimeHeaders array. Example: customHeaders.push({name:"header1", _content:"headerValue"}); Note: Header name ("header1" in this case) MUST be one of the valid/allowed values of zimbraCustomMimeHeaderNameAllowed global-config property (set by admin)
Parameters:
{array} customMimeHeaders
The array containing all custom headers

{ZmButtonToolBar} addSearchDomainItem(icon, label, listener, id)
Adds an item to the search toolbar drop-down. A listener (if specified) will be called when the item is selected.
Parameters:
{string} icon
the icon (style class) to use or null for no icon
{string} label
the label for the item
{AjxListener} listener
the listener or null for none
{string} id
the unique id of the item to add
Returns:
{ZmButtonToolBar} null if item not created

appActive(appName, active)
This method gets called each time the "tab" application is opened or closed.
Parameters:
{string} appName
the application name
{boolean} active
if true, the application status is open; otherwise, false
See:
#createApp

appendExtraSignature(contact, oldMsg)
This method is called by the Zimlet framework when adding a signature to an email message.

To append extra signature information, the zimlet should push text into the bufferArray.

bufferArray.push("Have fun, write a Zimlet!");

Parameters:
{ZmMailMsg} contact
the clicked message
{ZmMailMsg} oldMsg
the previous clicked message or null if this is the first message clicked

appLaunch(appName)
This method gets called when the "tab" application is opened for the first time.
Parameters:
{string} appName
the application name
See:
#createApp

{AjxXmlDoc} applyXslt(xsltUrl, doc)
This method will apply and XSL transformation to an XML document. For example, content returned from a services call.
Parameters:
{string} xsltUrl
the URL to the XSLT style sheet
{string|AjxXmlDoc} doc
the XML document to apply the style sheet
Returns:
{AjxXmlDoc} the XML document representing the transformed document

{boolean} checkProperties(props)
This method is called by the zimlet framework prior to user properties being saved.
Parameters:
{array} props
an array of objects with the following properties:
  • props[...].label {string} the property label
  • props[...].name {string} the property name
  • props[...].type {string} the property type
  • props[...].value {string} the property value
Returns:
{boolean} true if properties are valid; otherwise, false or {String} if an error message will be displayed in the standard error dialog.

clicked(spanElement, contentObjText, matchContent, event)
This method is called when a zimlet content object is clicked.
Parameters:
{Object} spanElement
the enclosing span element
{string} contentObjText
the content object text
{array} matchContent
the match content
{DwtMouseEvent} event
the mouse click event

{string} createApp(label, image, tooltip, index, style)
Creates a "tab" application and registers this zimlet to receive #appActive and #appLaunch events.
Parameters:
{string} label
the label to use on the application tab
{string} image
the image (style class) to use on the application tab
{string} tooltip
the tool tip to display when hover-over the application tab
{number} index Optional
the index to insert the tab (must be > 0). 0 is first location. Default is last location.
{constant} style
the button positioning style (see DwtControl)
Returns:
{string} the name of the newly created application

createPropertyEditor(callback)
This method is called if there are <userProperties> elements specified in the Zimlet Definition File. When the zimlet panel item is double-clicked, the property editor will be presented to the user.

This method creates the property editor for the set of <property> elements defined in the <userProperties> element. The default implementation of this method will auto-create a property editor based on the attributes of the user properties.

Override this method if a custom property editor is required.

Parameters:
{AjxCallback} callback
the callback method for saving user properties

displayErrorMessage(msg, data, title)
Displays the specified error message in the standard error dialog.
Parameters:
{string} msg
the error message to display
{string} data
the error message details
{string} title
the error message dialog title

displayStatusMessage(msg)
Displays the specified status message.
Parameters:
{string} msg
the status message to display

{boolean} doDrag(zmObject)
This method is called when an item is dragged on the Zimlet drop target in the panel. This method is only called for the valid types that the Zimlet accepts as defined by the <dragSource> Zimlet Definition File XML.
Parameters:
{ZmAppt|ZmConv|ZmContact|ZmFolder|ZmMailMsg|ZmTask} zmObject
the dragged object
Returns:
{boolean} true if the drag should be allowed; otherwise, false

doDrop(zmObject)
This method is called when an item is dropped on the Zimlet in the panel.
Parameters:
{ZmAppt|ZmConv|ZmContact|ZmFolder|ZmMailMsg|ZmTask} zmObject
the dropped object

doubleClicked(canvas)
This method gets called when a double-click is performed. By default, this method will create the default property editor for editing user properties.
Parameters:
{Object} canvas
the canvas
See:
#singleClicked
#createPropertyEditor

emailErrorCheck(msg, boolAndErrorMsgArray)
This method is called by the Zimlet framework when a message is about to be sent.

To fail the error check, the zimlet must return a boolAndErrorMsgArray array with the following syntax:

{hasError:<true or false>, errorMsg:<error msg>, zimletName:<zimlet name>}

Parameters:
{ZmMailMsg} msg
the message
{array} boolAndErrorMsgArray
an array of error messages, if any

enableContextMenuItem(contextMenu, menuItemId, enabled)
Enables the specified context menu item.
Parameters:
{ZmZimletBase.PANEL_MENU|ZmZimletBase.CONTENTOBJECT_MENU} contextMenu
the context menu
{string} menuItemId
the menu item Id
{boolean} enabled
true to enable the menu item; false to disable the menu item

{string} getConfigProperty(propertyName)
Gets the configuration property.
Parameters:
{string} propertyName
the name of the property to retrieve
Returns:
{string} the value of the property or null if no such property exists

{string} getMessage(msg)
Gets the message property.
Parameters:
{string} msg
the message
Returns:
{string} the message property or "???" + msg + "???" if not found

{string[]} getMessages()
Gets the message properties.
Returns:
{string[]} an array of message properties

getMsgsForConv(callback, conv)
Gets the mail messages for the conversation.
Parameters:
{AjxCallback} callback
the callback method
{ZmConv} conv
the conversation

{string} getResource(resourceName)
Gets the fully qualified resource Url.
Parameters:
{string} resourceName
the resource name
Returns:
{string} the fully qualified resource Url

{string} getSearchQuery()
Gets the text field value entered in the search bar.
Returns:
{string} the search field value or null for none

{DwtShell} getShell()
Gets the shell for the zimlet.
Returns:
{DwtShell} the shell

{string} getUserID()
Gets the current user id.
Returns:
{string} the current user id

{string} getUsername()
Gets the current username.
Returns:
{string} the current username

{string} getUserProperty(propertyName)
Gets the user property.
Parameters:
{string} propertyName
the name of the property to retrieve
Returns:
{string} the value of the property or null if no such property exists

{string} getUserPropertyInfo(propertyName)
Gets the user property info for the specified property.
Parameters:
{string} propertyName
the property
Returns:
{string} the value of the user property

{ZimletContext} getZimletContext()
Gets the zimlet context.
Returns:
{ZimletContext} the context

{ZmZimletMgr} getZimletManager()
Gets the zimlet manager.
Returns:
{ZmZimletMgr} the zimlet manager

init()
This method is called by the Zimlet framework to indicate that the zimlet it being initialized. This method can be overridden to initialize the zimlet.

initializeToolbar(app, toolbar, controller, viewId)
This method is called by the Zimlet framework when application toolbars are initialized.
Parameters:
{ZmApp} app
the application
{ZmButtonToolBar} toolbar
the toolbar
{ZmController} controller
the application controller
{string} viewId
the view Id

{array} match(content, startIndex)
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 the pattern matching as defined for a given zimlet <regex>. Zimlets should also use the "g" option when constructing their <regex>.

The return should be an array in the form:

result[0...n] // should be matched string(s)
result.index // should be location within line where match occurred
result.input // should be the input parameter content

Parameters:
{string} content
the content line to perform a match against
{number} startIndex
the start index (i.e. where to begin the search)
Returns:
{array} the matching content object from the startIndex if the content matched the specified zimlet handler regular expression; otherwise null

menuItemSelected(contextMenu, menuItemId, spanElement, contentObjText, canvas)
This method is called when a context menu item is selected.
Parameters:
{ZmZimletBase.PANEL_MENU|ZmZimletBase.CONTENTOBJECT_MENU} contextMenu
the context menu
{string} menuItemId
the selected menu item Id
{Object} spanElement
the enclosing span element
{string} contentObjText
the content object text
{Object} canvas
the canvas

onAction(type, action, currentViewId, lastViewId)
This method by the Zimlet framework when an application action occurs.
Parameters:
{string} type
the type of action (for example: "app", "menuitem", "treeitem")
{string} action
the action
{string} currentViewId
the current view Id
{string} lastViewId
the last view Id

onActionMenuInitialized(controller, actionMenu)
This method gets called by the Zimlet framework when the action menu is initialized on the subject/fragment of an email message.

This method is called twice:

  • The first-time a right-click is performed on a message in Conversation View.
  • The first-time a right-click is performed on a message in Message View.

Parameters:
{ZmController} controller
the controller
{ZmActionMenu} actionMenu
the action menu

onContactEdit(view, contact, elementId)
This method is called by the Zimlet framework when a contact is edited.
Parameters:
{ZmEditContactView} view
the edit contact view
{ZmContact} contact
the contact being edited
{string} elementId
the element Id

onContactView(contact, elementId)
This method is called by the Zimlet framework when a contact is clicked-on in the contact list view.
Parameters:
{ZmContact} contact
the contact being viewed
{string} elementId
the element Id

onFindMsgObjects(msg, objMgr)
This method is called by the Zimlet framework when a user clicks-on a message in either the message or conversation view).
Parameters:
{ZmMailMsg} msg
the clicked message
{ZmObjectManager} objMgr
the object manager

onKeyPressSearchField(queryStr)
This method is called by the Zimlet framework when enter is pressed in the search field.
Parameters:
{string} queryStr
the search query string
See:
#onSearchButtonClick

onMailConfirm(confirmView, msg)
This method is called by the Zimlet framework when the message confirmation dialog is presented.
Parameters:
{ZmMailConfirmView} confirmView
the confirm view
{ZmMailMsg} msg
the message

onMailFlagClick(items, on)
This method is called by the Zimlet framework when an email message is flagged.
Parameters:
{ZmMailMsg[]|ZmConv[]} items
an array of items
{boolean} on
true if the flag is being set; false if the flag is being unset

onMsgView(msg, oldMsg, msgView)
This method is called by the Zimlet framework when a user clicks-on a message in the mail application.
Parameters:
{ZmMailMsg} msg
the clicked message
{ZmMailMsg} oldMsg
the previous clicked message or null if this is the first message clicked
{ZmMailMsgView} msgView
the view that displays the message

onParticipantActionMenuInitialized(controller, actionMenu)
This method gets called by the Zimlet framework when the action menu is initialized on the from/sender of an email message.
Parameters:
{ZmController} controller
the controller
{ZmActionMenu} actionMenu
the action menu

onSearch(queryStr)
This method is called by the Zimlet framework when a search is performed.
Parameters:
{string} queryStr
the search query string

onSearchButtonClick(queryStr)
This method is called by the Zimlet framework when the search button is clicked.
Parameters:
{string} queryStr
the search query string
See:
#onKeyPressSearchField

onSelectApp(id)
This method by the Zimlet framework when an application button is pressed.
Parameters:
{string} id
the id of the application button

onShowView(view)
This method is called by the Zimlet framework when showing an application view.
Parameters:
{string} view
the name of the view

onTagAction(items, tag, doTag)
This method is called by the Zimlet framework when an email message is tagged.
Parameters:
{ZmMailMsg[]|ZmConv[]} items
an array of items
{ZmTag} tag
the tag
{boolean} doTag
true if the tag is being set; false if the tag is being removed

portletCreated(portlet)
This method is called by the Zimlet framework when the portlet is created.
Parameters:
{ZmPortlet} portlet
the portlet

portletRefreshed(portlet)
This method is called by the Zimlet framework when the portlet is refreshed.
Parameters:
{ZmPortlet} portlet
the portlet

resetToolbarOperations(parent, enable)
Reset the toolbar
Parameters:
{ZmButtonToolBar|ZmActionMenu} parent
the toolbar or action menu
{int} enable
number of items selected

{string} saveUserProperties(callback)
Saves the user properties.
Parameters:
{AjxCallback} callback
the callback to invoke after the save
Returns:
{string} an empty string or an error message

{Object} sendRequest(requestStr, serverURL, requestHeaders, callback, useGet, passErrors)
Sends the request content (via Ajax) to the specified server.
Parameters:
{string} requestStr
the request content to send
{string} serverURL
the server url
{string[]} requestHeaders
the request headers (may be null)
{AjxCallback} callback
the callback for asynchronous requests or null for none
{boolean} useGet
true to use HTTP GET; null or false otherwise
{boolean} passErrors
true to pass errors; null or false otherwise
Returns:
{Object} the return value

setTooltipSticky(sticky, popdown)
This method is called when a sticky tooltip is clicked, when clicking outside a sticky tooltip, or when a zimlet wants to stick or unstick a tooltip. To explicitly dismiss a sticky tooltip, this method should be called with parameters (false, true)
Parameters:
{boolean} sticky
Whether stickiness should be applied or removed
{boolean} popdown
(Optional) Pop down the tooltip after removing stickiness

setUserProperty(propertyName, value, save, callback)
Sets the value of a given user property
Parameters:
{string} propertyName
the name of the property
{string} value
the property value
{boolean} save
if true, the property will be saved (along with any other modified properties)
{AjxCallback} callback
the callback to invoke after the user properties save
Throws:
ZimletException if no such property exists or if the value is not valid for the property type
See:
#saveUserProperties

singleClicked(canvas)
This method gets called when a single-click is performed.
Parameters:
{Object} canvas
the canvas
See:
#doubleClicked

{string} toolTipPoppedDown(spanElement, contentObjText, matchContent, canvas)
This method is called when the tool tip is popping-down.
Parameters:
{Object} spanElement
the enclosing span element
{string} contentObjText
the content object text
{array} matchContent
the matched content
{Object} canvas
the canvas
Returns:
{string} null if the tool tip may be popped-down; otherwise, a string indicating why the tool tip should not be popped-down

toolTipPoppedUp(spanElement, contentObjText, matchContent, canvas)
This method is called when the tool tip is popping-up.
Parameters:
{Object} spanElement
the enclosing span element
{string} contentObjText
the content object text
{array} matchContent
the matched content
{Object} canvas
the canvas

{string} toString()
Returns a string representation of the zimlet.
Returns:
{string} a string representation of the zimlet

Documentation generated by JsDoc Toolkit 2.3.0 on Tue Jun 28 2016 21:01:39 GMT-0400 (EDT)