Zimlet JavaScript API Reference - ZmAutocompleteListView

Class ZmAutocompleteListView


Extends DwtComposite.

This class implements autocomplete functionality. It has two main parts: matching data based on keystroke events, and displaying/managing the list of matches. This class is theoretically neutral concerning the data that gets matched (as long as its class has an autocompleteMatch() method), and the field that it's being called from. The data class's autocompleteMatch() method should returns a list of matches, where each match is an object with the following properties:

datathe object being matched
textthe text to display for this object in the list
[key1]a string that may be used to replace the typed text
[keyN]a string that may be used to replace the typed text
The calling client also specifies the key in the match result for the string that will be used to replace the typed text (also called the "completion string"). For example, the completion string for matching contacts could be a full address, or just the email. The client may provide additional key event handlers in the form of callbacks. If the callback explicitly returns true or false, that's what the event handler will return. A single autocomplete list view may handle several related input fields. With the "quick complete" feature, there may be multiple outstanding autocomplete requests to the server. Each request is managed through a context which has all the information needed to make the request and handle its results. Using Autocomplete Autocomplete kicks in after there is a pause in the typing (that pause has to be at least 300ms by default). Let's say that you are entering addresses into the To: field while composing an email. You type a few characters and then pause: dav ZCS will ask the user for people whose name or email address matches "dav", and display the matches in a list that pops up. The matches will be sorted with the people you email the most at the top. When you select a match, that person's address will replace the search string ("dav") in the To: field. Typically the address will be in a bubble. Davey Jones x Quick Complete Many times you will know which address you're looking for, and you will type enough characters so that they will appear at the top of the matches, and then you type semicolon or a return to select them once the list has come up. If you know that the address you want will appear at the top of the matches based on what you've typed, then there's a way to select it without waiting for the list to come up: just type a semicolon. For example, let's assume that I email Davey Jones a lot, and I know that if I type "dav" he will be the first match. I can just type dav; and continue, whether that's adding more addresses, or moving on to the subject and body (done easily via the Tab key). Autocompletion will happen in the background, and will automatically replace "dav;" with the first match from the list. If no matches are found, nothing changes. One way to think of the Quick Complete feature is as the autocomplete version of Google's "I'm Feeling Lucky", though in this case you have a much better idea of what the results are going to be. You don't have to wait for the list to appear in order to add the bubble. It gets added for you. You can type in multiple Quick Complete strings, and they will all be handled. For example, I could type dav;pb;ann;x; and see bubbles pop up for Davey Jones, Phil Bates, Ann Miller, and Xavier Gold without any more action on my part. I could even type "dav;" into the To: field, hit Tab to go to the Cc: field, type "pb;" there, and then Tab to the Subject: field, and start writing my message. One small limitation of Quick Complete is that the bubbles will pop up within a field in the order that the results come back, which may not match the order of the strings you typed in. You can drag the bubbles to rearrange them if you want. Special Keys There are a number of keys that have special meanings when you are working with an input field that supports autocomplete. Most of them apply while the list of matches is showing, and are used to control selection of the match you want: Return Adds the selected address Tab Adds the selected address ; Adds the selected address , Adds the selected address (if enabled in Preferences/Address Book/Autocomplete) DownArrow Selects the next address (hold to repeat) UpArrow Selects the previous address (hold to repeat) Esc Hides the list A few keys have special meanings while the list is not showing: Return If the input contains an email address, turn it into a bubble Tab Go to the next field Esc If requests are pending (it will say "Autocompleting"), cancel them. If not, cancel compose.

Defined in: ZmAutocompleteListView.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
ZmAutocompleteListView(params, matchValue, dataClass, dataLoader, parent, className, delims, delimCodes, separator, compCallback, selectionCallback, keyDownCallback, keyPressCallback, keyUpCallback, contextId, options, locationCallback)
Creates a new autocomplete list.
Method Summary
Method Attributes Method Name and Description
 
addCallback(type, callback, inputId)
Adds a callback of the given type.
 
expandDL(params)
Displays a second popup list with the members of the given distribution list.
<static>  
ZmAutocompleteListView.onKeyDown(event)
Handles the on key down event.
<static>  
ZmAutocompleteListView.onKeyPress(event)
Handles the on key press event.
<static>  
ZmAutocompleteListView.onKeyUp(event)
Handles the on key up event.
 
reset(element)
Resets the visible state of the autocomplete list.
 
Sets the active account.
 
setWaiting(on, str)
Sets the waiting status.
 
show(show, loc)
Displays the current matches in a popup list, selecting the first.
Methods borrowed from class DwtComposite:
addChild, cleanupSeparators, clear, dispose, getChild, getChildren, getNumChildren, getTabGroupMember, removeChild, removeChildren
Methods borrowed from class DwtControl:
addClassName, addControlListener, addDisposeListener, addListener, appendElement, blur, clearContent, clearHandler, condClassName, delClassName, focus, getBounds, getClassName, getContent, getCursor, getData, getDragBox, getDragSource, getDropTarget, getEnabled, getFocusElement, getH, getHtmlElement, getHTMLElId, getInsetBounds, getInsets, getLocation, getMargins, getOpacity, getOuterSize, getPosition, getScrollContainer, getScrollStyle, getSize, getTooltipBase, getToolTipContent, getVisibility, getVisible, getW, getX, getXW, getY, getYH, getZIndex, hasFocus, isAlertShown, isDisposed, isInitialized, isListenerRegistered, notifyListeners, preventContextMenu, preventSelection, removeAllListeners, removeControlListener, removeDisposeListener, removeListener, reparent, reparentHtmlElement, replaceElement, setBounds, setClassName, setContent, setCursor, setData, setDisplay, setDisplayState, setDragBox, setDragSource, setDropTarget, setEnabled, setEventPropagation, setFocusElement, setHandler, setHtmlElementId, setLocation, setOpacity, setPosition, setScrollStyle, setSize, setToolTipContent, setVisibility, setVisible, setZIndex, showAlert, zShow
Class Detail
ZmAutocompleteListView(params, matchValue, dataClass, dataLoader, parent, className, delims, delimCodes, separator, compCallback, selectionCallback, keyDownCallback, keyPressCallback, keyUpCallback, contextId, options, locationCallback)
Creates a new autocomplete list. The list isn't populated or displayed until some autocompletion happens. Takes a data class and loader, so that when data is needed (it's loaded lazily), the loader can be called on the data class.
Author: Conrad Damon.
Parameters:
{Hash} params
a hash of parameters:
{String} matchValue
the name of field in match result to use for completion
{function} dataClass
the class that has the data loader
{function} dataLoader
a method of dataClass that returns data to match against
{DwtComposite} parent
the control that created this list (defaults to shell)
{String} className
the CSS class
{Array} delims
the list of delimiters (which separate tokens such as addresses)
{Array} delimCodes
the list of delimiter key codes
{String} separator
the separator (gets added to the end of a match)
{AjxCallback} compCallback
the callback into client to notify it that completion happened
{AjxCallback} selectionCallback
the callback into client to notify it that selection from extended DL happened (passed from email.js, and accessed from ZmDLAutocompleteListView.prototype._doUpdate)
{AjxCallback} keyDownCallback
the additional client ONKEYDOWN handler
{AjxCallback} keyPressCallback
the additional client ONKEYPRESS handler
{AjxCallback} keyUpCallback
the additional client ONKEYUP handler
{string} contextId
ID from parent
{Hash} options
the additional options for the data class
{function} locationCallback
used to customize list location (optional)
Method Detail
addCallback(type, callback, inputId)
Adds a callback of the given type. In an input ID is provided, then the callback will only be run if the event happened in that input.
Parameters:
{constant} type
autocomplete callback type (ZmAutocompleteListView.CB_*)
{AjxCallback|function} callback
callback to add
{string} inputId
DOM ID of an input element (optional)

expandDL(params)
Displays a second popup list with the members of the given distribution list.
Parameters:
{hash} params
hash of params:
{string} params.email
address of a distribution list
{string} params.textId
ID of link text
{string} params.rowId
ID or list view row
{DwtMouseEvent} params.ev
mouse event
{DwtPoint} params.loc
location to popup at; default is right of parent ACLV
{Element} params.element
input element

<static> ZmAutocompleteListView.onKeyDown(event)
Handles the on key down event.
Parameters:
{Event} event
the event

<static> ZmAutocompleteListView.onKeyPress(event)
Handles the on key press event.
Parameters:
{Event} event
the event

<static> ZmAutocompleteListView.onKeyUp(event)
Handles the on key up event.
Parameters:
{Event} event
the event

reset(element)
Resets the visible state of the autocomplete list. The state-related properties are not per-element because there can only be one visible autocomplete list.
Parameters:
element

setActiveAccount(account)
Sets the active account.
Parameters:
{ZmAccount} account
the account

setWaiting(on, str)
Sets the waiting status.
Parameters:
{Boolean} on
if true, turn waiting "on"
{string} str
string that pending request is for

show(show, loc)
Displays the current matches in a popup list, selecting the first.
Parameters:
{Boolean} show
if true, display the list
{String} loc
where to display the list

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