Zimlet JavaScript API Reference - ZmId

Class ZmId


This class is responsible for providing unique, predictable IDs for HTML elements. That way, code outside the client can easily locate particular elements.

Not every element that has an associated JS object will have a known ID. Those are allocated only for elements it would be useful to locate: major components of the UI, toolbars, buttons, views, menus, some menu items, some selects, and miscellaneous other components.

Unless noted otherwise, a getElementById() on any of the non-skin IDs will return a DIV. One exception is input fields. The ID is given to the DwtInputField's actual INPUT, rather than to the DIV that contains it. Most other exceptions are table-related: TABLE, TR, and TD.

There is a simple naming scheme for the IDs themselves. Each ID starts with a "z" followed by one to a few letters that indicate the type of object (widget) represented by the element:

  • z a component that is not a special-purpose widget listed below
  • ztb a toolbar (see ZmId.WIDGET)
  • zb a button (see ZmId.WIDGET_TOOLBAR)
  • zi an input field (see ZmId.WIDGET_INPUT)
  • zm a menu (see ZmId.WIDGET_MENU)
  • zmi a menu item (see ZmId.WIDGET_MENU_ITEM)
  • zs a select (see ZmId.WIDGET_SELECT)
  • zov an overview (see ZmId.WIDGET_OVERVIEW)
  • zt a tree (see ZmId.WIDGET_TREE)
  • zti a tree item (see ZmId.WIDGET_TREE_ITEM)
  • ztih a tree item header (see ZmId.WIDGET_TREE_ITEM_HDR)
The skin defines its own container IDs starting with "skin_", which we provide constants for here.

Defined in: ZmId.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
ZmId()
Constructor
Method Summary
Method Attributes Method Name and Description
<static>  
ZmId.create(params, description)
Returns a unique ID that can later be looked up.
<static>  
ZmId.getButtonId(context, op, tbType)
Generates the ID for a button.
<static>  
ZmId.getComposeViewId(component)
Generates an ID for the compose view, or for a component within the compose view.
<static>  
ZmId.getMenuId(context, menuType)
Generates the ID for an action menu.
<static>  
ZmId.getMenuItemId(context, op, menuType)
Generates the ID for a menu item in an action menu.
<static>  
ZmId.getOverviewContainerId(overviewContainerId)
Generates the ID for an overview container.
<static>  
ZmId.getOverviewId(overviewId)
Generates the ID for an overview.
<static>  
ZmId.getParams(id)
Returns the set of params used to create the given ID.
<static>  
ZmId.getPrefPageId(tabKey)
Generates an ID for a pref page tab.
<static>  
ZmId.getTabId(context, tabName)
Generates an ID for a tab (actually the tab button in the tab bar).
<static>  
ZmId.getToolbarId(context, tbType)
Generates the ID for a toolbar.
<static>  
ZmId.getTreeId(overviewId, orgType)
Generates the ID for a tree within an overview.
<static>  
ZmId.getTreeItemId(overviewId, organizerId, type)
Generates a tree item ID based on the underlying organizer and the overview ID (since the same organizer may be represented as tree items in more than one overview).
<static>  
ZmId.getViewId(viewId, component, context)
Generates an ID for a view that fills the content area, or for a component of that view.
<static>  
ZmId.lookup(params)
Returns the DOM ID that matches the given set of params.
<static>  
ZmId.showIds(params)
Displays a list of matching IDs in a popup, with the params used to create them and their descriptions.
Class Detail
ZmId()
Constructor
Author: Conrad Damon.
Method Detail
<static> ZmId.create(params, description)
Returns a unique ID that can later be looked up. As many params as possible should be provided, in order to make lookup easier. If one or more IDs is found to already have been created with the given set of params, a sequence number is added as a parameter.
Parameters:
{hash} params
set of fields describing the ID's element
{string} description
(optional) a brief description of the purpose of the ID

<static> {String} ZmId.getButtonId(context, op, tbType)
Generates the ID for a button. Intended for use with the top toolbar, nav toolbar, and invite toolbar.

Examples: zb|CLV|CHECK_MAIL zb|TV|REPLY zb|COMPOSE|SEND zb|CLV|Nav|PAGE_FORWARD

Parameters:
{String} context
the toolbar context (ID of owning view)
{constant} op
the button operation
{constant} tbType
the type of toolbar (eg invite or nav)
Returns:
{String} the id

<static> {String} ZmId.getComposeViewId(component)
Generates an ID for the compose view, or for a component within the compose view. Since only one compose view is created, there is no need for a context to make the ID unique. The component name is not joined with the "|" character for backward compatibility.

Examples: z|ComposeView z|ComposeView_header z|ComposeView_to_row

Parameters:
{constant} component
component identifier (see ZmId.CMP_ constants)
Returns:
{String} the id

<static> {String} ZmId.getMenuId(context, menuType)
Generates the ID for an action menu.

Examples: zm|CLV zm|Contacts zm|TV|Par

Parameters:
{String} context
the menu context (eg ID of owning view, or app)
{constant} menuType
the type of menu (eg participant)
Returns:
{String} the id

<static> {String} ZmId.getMenuItemId(context, op, menuType)
Generates the ID for a menu item in an action menu.

Examples: zmi|CLV|REPLY_ALL zmi|TV|Par|SEARCH

Parameters:
{String} context
the menu context
{constant} op
the menu operation
{constant} menuType
the type of menu (eg participant)
Returns:
{String} the id

<static> {String} ZmId.getOverviewContainerId(overviewContainerId)
Generates the ID for an overview container.
Parameters:
{String} overviewContainerId
the overview container ID
Returns:
{String} the id

<static> {String} ZmId.getOverviewId(overviewId)
Generates the ID for an overview.

Examples: zov|Mail zov|ZmChooseFolderDialog-ZmListController zov|ZmPickTagDialog

Parameters:
{String} overviewId
the overview ID
Returns:
{String} the id

<static> ZmId.getParams(id)
Returns the set of params used to create the given ID.
Parameters:
id

<static> {String} ZmId.getPrefPageId(tabKey)
Generates an ID for a pref page tab.
Parameters:
{String} tabKey
the tab key
Returns:
{String} the id

<static> {String} ZmId.getTabId(context, tabName)
Generates an ID for a tab (actually the tab button in the tab bar).

Tab contexts and names:

  • VIEW_PREF General, Mail, Composing, Signatures, Address Book, Accounts, Mail Filters, Calendar, Shortcuts
  • VIEW_CONTACT personal, work, home, other, notes
  • VIEW_APPOINTMENT details, schedule, attendees, locations, equipment
  • VIEW_SHORTCUTS list, ZmId.ORG_FOLDER, ZmId.ORG_SEARCH, ZmId.ORG_TAG

Parameters:
{constant} context
the owning view identifier (see ZmId.VIEW_ constants)
{String} tabName
[string] name of tab
Returns:
{String} the id

<static> {String} ZmId.getToolbarId(context, tbType)
Generates the ID for a toolbar.

Examples: ztb|CLV ztb|TV|Nav ztb|CV|Inv

Parameters:
{String} context
the toolbar context (ID of owning view)
{constant} tbType
the type of toolbar (for example, invite or nav)
Returns:
{String} the id

<static> {String} ZmId.getTreeId(overviewId, orgType)
Generates the ID for a tree within an overview.

Examples: zt|Mail|FOLDER zt|ZmPickTagDialog|TAG

Parameters:
{String} overviewId
the overview ID
{String} orgType
the organizer type (see ZmId.ORG_ constants)
Returns:
{String} the id

<static> {String} ZmId.getTreeItemId(overviewId, organizerId, type)
Generates a tree item ID based on the underlying organizer and the overview ID (since the same organizer may be represented as tree items in more than one overview). Some sample IDs:
  • zti|Mail|2 Inbox
  • zti|Mail|172 user-created item in mail overview
  • zti|Contacts|7 system Contacts folder
  • zti|Calendar|304 user-created item in calendar overview
  • ztih|Mail|FOLDER Folders header in mail overview
Constants for some system folder tree items have been provided as a convenience.
Parameters:
{String} overviewId
the unique ID for overview
{ZmOrganizer} organizerId
the ID of the data object backing tree item
{constant} type
the organizer type (for headers only)
Returns:
{String} the id

<static> {String} ZmId.getViewId(viewId, component, context)
Generates an ID for a view that fills the content area, or for a component of that view. A context should be provided if the view is not a singleton (for example, message view may appear within several double-pane views). The component name is not joined with the "|" character in order to preserve backward compatibility.

Examples: zv|COMPOSE zv|TV zv|TV|MSG zv|TV|MSG_hdrTable

Parameters:
{constant} viewId
the view identifier (see ZmId.VIEW_ constants)
{constant} component
the component identifier (see ZmId.MV_ constants)
{constant} context
the ID of owning view
Returns:
{String} the id

<static> ZmId.lookup(params)
Returns the DOM ID that matches the given set of params. If more than one ID matches, a list is returned. A partial set of params may be provided. The more params provided, the better the chance of finding just one ID. The best approach is to provide the minimal set of params that will uniquely differentiate the element. If no params are provided, returns all IDs. Optionally, a list of values can be given. An attempt will be made to reverse-engineer the params by figuring out the appropriate key for each value. This method will never be as reliable as providing a hash in the first place.
Parameters:
{hash|array} params
set of fields describing the ID(s) being sought

<static> ZmId.showIds(params)
Displays a list of matching IDs in a popup, with the params used to create them and their descriptions. Intended as a development tool.
Parameters:
params
set of fields describing the ID(s) being sought

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