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:
data | the object being matched |
text | the 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 |
|
Adds a callback of the given type.
|
|
Displays a second popup list with the members of the given distribution list.
|
<static> |
Handles the on key down event.
|
<static> |
Handles the on key press event.
|
<static> |
ZmAutocompleteListView. onKeyUp(event)
Handles the on key up event.
|
|
Resets the visible state of the autocomplete list.
|
|
Sets the active account.
|
|
Sets the waiting status.
|
|
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
|