Zimlet JavaScript Class: Difference between revisions

(Zimlets Whitepaper conversion 4-JavaScriptClass in progress)
 
No edit summary
 
(11 intermediate revisions by 2 users not shown)
Line 1: Line 1:
=Zimlet JavaScript Class=
{{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}}
<p class=MsoNormal style='text-autospace:none'><span style='color:black'>The
__FORCETOC__
Zimlet framework provides the Zimlet JavaScript base class. Developers wishing
<div class="col-md-12 ibox-content">
to implement Zimlet functionality directly in JavaScript should extend this
=Zimlet Javascript Class=
class. The name of the derived class, as well as the file in which the class is
{{KB|{{Unsupported}}|{{ZCS 5.0}}||}}
defined should be the same as the Zimlet</span><span style='font-family:"Arial1252","sans-serif";
{{Archive}}{{WIP}}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.
color:black'>’</span><span style='color:black'>s name.</span></p>
 
<p class=MsoNormal style='text-autospace:none'><span style='color:black'>The
methods comprising the Zimlet base class (ZmZimletBase.js) may be divided into
the following categories:</span></p>


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 the Zimlet panel items.
*Methods related to content objects
*Methods related to content objects
*Helper methods
*Helper methods


<p class=MsoNormal style='text-autospace:none'><span style='color:black'>There
There are certain formal parameters that are common to a number of methods defined by the Zimlet class:
are certain formal parameters that are common to a number of methods defined by
the Zimlet class:</span></p>
 
*Parameters common to Zimlet panel item methods:
*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
**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:
*Parameters common to content object methods:
**spanElement - This parameter is common to certain content object methods. It represents the HTML &lt;span&gt; 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.
**spanElement - This parameter is common to certain content object methods. It represents the HTML &lt;span&gt; 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
**contentObjText - The content object text of the content object being acted upon
 
*Parameters common across methods:
*Parameters common across methods:</span></p>
**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:
**canvas - The value of this parameter is driven by the
corresponding &lt;canvas&gt; element in the Zimlet Definition file.. The list
below enumerates the value of th canvas parameter for each value of the
&lt;canvas&gt; element</span><span style='font-family:"Arial1252","sans-serif";
color:black'>’</span><span style='color:black'>s type attribute:</span></p>
 
***'''none''' - canvas will be null
***'''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 <div> object that may be arbitrarily manipulated. For example, any HTML content may be placed within this <div> by setting its innerHTML attribute.
***'''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 </span><span style='font-family: Courier;color:black'>getHtmlElement() </span><span style='color:black'>method of a composite object a handle may be obtained to composite</span><span style='font-family:"Arial1252","sans-serif";color:black'>’</span><span style='color:black'>s DOM element. This element is a &lt;div&gt; object that may be arbitrarily manipulated. For example, any HTML content may be placed within this &lt;div&gt; by setting its </span><span style='font-family:Courier; color:black'>innerHTML </span><span style='color:black'>attribute.</span></p>
 
***'''tooltip''' - canvas will be a DwtToolTip
***'''tooltip''' - canvas will be a DwtToolTip
***'''window''' - canvas is a handle to the new browser window.
***'''window''' - canvas is a handle to the new browser window.


Line 419: Line 397:
===getUserPropertyInfo===
===getUserPropertyInfo===


<p class=MsoNormal>This method returns a user property<span style='font-family:
'''getUserPropertyInfo''' provides a specified [[Zimlet_Definition_File#.3Cproperty.3E|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.
"Arial1252","sans-serif"'>’</span>s property information. The property
information is a hash the content of which depends on the type of the property.
All properties support the following keys:</p>
 
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span><i>name </i>- The property<span style='font-family:"Arial1252","sans-serif"'>’</span>s
name</p>
 
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span><i>label </i>- The label to be displayed for the element</p>
 
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span><i>Visible </i>- True if the property should be displayed in the
property editor.</p>
 
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span><i>Type </i>- This will be one of:</p>
 
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>Zimlet.STRING_PROP</p>
 
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>Zimlet.PASSWORD_PROP</p>
 
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>Zimlet.NUMBER_PROP</p>
 
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>Zimlet.DATE_PROP</p>
 
<p class=MsoNormal style='margin-left:.75in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>Zimlet.SELECT_PROP</p>
 
<p class=MsoNormal style='text-autospace:none'>The following is the list of
properties supported for the specific property types:</p>
 
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>string</p>
 
**minLen - Minimum length for the string (optional)</p>
 
**maxLen - Maximum length for the string (optional)</p>
 
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>password</p>
**minLen - Minimum length for the string (optional)</p>
**maxLen - Maximum length for the string (optional)</p>


* number
The getUserPropertyInfo method defines the following formal parameters:</p>
**minVal - Minimjum value for the number (optional)
* ''propName'': The user property name as a "string".
**maxVal - Maximum value for the number (optional)


*date
For example, to return the ''value'' of the user property ''websiteUrl '' would be
**N/A
<pre>
 
// this.getUserProperty(“PropertyName”)
<p class=MsoNormal style='text-autospace:none'><span style='font-family:"Antique Olive","sans-serif"'>&#61623;</span><span style='font-family:"Symbol-1-1","sans-serif"'> </span>select</p>
this.getUserPropertyInfo("websiteUrl")["value"];
 
</pre>
**items - an array of the items in the select. There will always be atleast one item</p>
<p class=MsoNormal style='text-autospace:none'>in this array. Each item has two keys</p>
 
***label - The label to be displayed for the item (Required)
 
***value - The value for the item (Required)
 
<p class=MsoNormal style='text-autospace:none'>The getUserPropertyInfo method
defines the following formal parameters:</p>
 
<p class=MsoNormal style='text-autospace:none'><span style='font-family:"Antique Olive","sans-serif"'>&#61623;</span><span
style='font-family:"Symbol-1-1","sans-serif"'> </span><i>propName </i>- The
user property name</p>
 
<p class=MsoNormal style='text-autospace:none'><span style='font-family:"Antique Olive","sans-serif"'>&#61623;</span><span
style='font-family:"Symbol-1-1","sans-serif"'> </span>Returns a has containing
the property info, or null if no such property exists</p>


===getUsername===
===getUsername===
Line 510: Line 412:
<p class=MsoNormal style='text-autospace:none'>This method returns the current
<p class=MsoNormal style='text-autospace:none'>This method returns the current
user<span style='font-family:"Arial1252","sans-serif"'>’</span>s username</p>
user<span style='font-family:"Arial1252","sans-serif"'>’</span>s username</p>
===getUserProperty===
<p class=MsoNormal style='text-autospace:none'>This method returns the value of
the requested user property. It defines the following formal parameters:</p>
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span><i>propertyName </i>- This is the name of the property whose
value is to be returned. For</p>
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>example: <span style='font-family:"Arial1252","sans-serif"'>“</span>someUserProperty<span
style='font-family:"Arial1252","sans-serif"'>”</span></p>
<p class=MsoNormal style='margin-left:.5in;text-indent:-.25in;text-autospace:
none'><span style='font-size:12.0pt'>*<span style='font:7.0pt "Times New Roman"'>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
</span></span>Return the value of the property, or null if no such property
exists</p>


===saveUserProperties===
===saveUserProperties===
 
This method will save the value of any modified properties to ZCS. It takes no formal parameters.
<p class=MsoNormal style='text-autospace:none'>This method will save the value
of any modified properties to ZCS. It takes no formal parameters</p>


===sendRequest Method===
===sendRequest Method===

Latest revision as of 06:12, 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 Javascript Class

   KB 2956        Last updated on 2021-07-17  




0.00
(0 votes)

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 this
        by 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

menuItemSelected Method

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 methods 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-createa property editor based on the attributes of the Zimlets 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 Zimlets properties. In addition, this method will register a callback for the dialogs okbutton. 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.somePropertyor 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 users 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 frameworks 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. Its constructor defines the following formal parameters:

*      obj - Generally obj is a reference to thisobject.

*      func- The function to call. If obj is not null, then the value of thiswhen 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 getmethod 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.

Verified Against: Date Created: 7/15/2009
Article ID: https://wiki.zimbra.com/index.php?title=Zimlet_JavaScript_Class 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