Zimlet JavaScript API Reference - ZmList

Class ZmList


Extends ZmModel.

This class represents a list of items (ZmItem objects). Any SOAP method that can be applied to a list of item IDs is represented here, so that we can perform an action on multiple items with just one CSFE call. For the sake of convenience, a hash matching item IDs to items is maintained. Items are assumed to have an 'id' property.

The calls are made asynchronously. We are assuming that any action taken will result in a notification, so the action methods generally do not have an async callback chain and thus are leaf nodes. An exception is moving conversations. We don't know enough from the ensuing notifications (which only indicate that messages have moved), we need to update the UI based on the response.

Defined in: ZmList.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
ZmList(type, search)
Creates an empty list of items of the given type.
Method Summary
Method Attributes Method Name and Description
 
add(item, index)
Adds an item to the list.
 
addFromDom(node, args)
Adds an item to the list from the given XML node.
 
cache(offset, newList)
Caches the list.
 
Clears the list, including the id hash.
 
copyItems(params)
Copies a list of items to the given folder.
 
create(args)
Creates an item from the given arguments.
 
Creates the item (local).
 
deleteItems(params)
Deletes one or more items from the list.
 
deleteLocal(items)
Deletes the items (local).
 
flagItems(params)
Sets and unsets a flag for each of a list of items.
 
get(index)
Gets the item.
<static>  
ZmList.getActionSummary(params)
Returns a string describing an action, intended for display as toast to tell the user what they just did.
 
Returns the list as an array.
 
getById(id)
Gets the item with the given id.
 
getSubList(offset, limit)
Gets a vector containing a subset of items of this list.
 
Returns the list as a vector.
 
Gets if there are more items for this search.
 
indexOf(item)
Returns the index of the given item in the list.
 
modifyItem(item, mods, callback)
Applies the given list of modifications to the item.
 
modifyLocal(items, mods)
Modifies the items (local).
 
moveItems(params)
Moves a list of items to the given folder.
 
moveLocal(items, folderId)
Moves the items (local).
 
Create notification.
 
remove(item)
Removes an item from the list.
 
removeAllTags(params)
Removes all tags from a list of items.
 
set(respNode)
Populates the list with elements created from the response to a SOAP command.
 
setHasMore(bHasMore)
Sets the "more" flag for this list.
 
size()
Returns the number of items in the list.
 
tagItems(params)
Tags or untags a list of items.
Methods borrowed from class ZmModel:
addChangeListener, removeAllChangeListeners, removeChangeListener
Class Detail
ZmList(type, search)
Creates an empty list of items of the given type.
Author: Conrad Damon.
Parameters:
{constant} type
the item type
{ZmSearch} search
the search that generated this list
Method Detail
add(item, index)
Adds an item to the list.
Parameters:
{ZmItem} item
the item to add
{int} index
the index at which to add the item (defaults to end of list)

addFromDom(node, args)
Adds an item to the list from the given XML node.
Parameters:
{Object} node
an XML node
{Hash} args
an optional list of arguments to pass to the item contructor

cache(offset, newList)
Caches the list.
Parameters:
{int} offset
the index
{AjxVector} newList
the new list

clear()
Clears the list, including the id hash.

copyItems(params)
Copies a list of items to the given folder.
Parameters:
{Hash} params
the hash of parameters
{Array} params.items
a list of items to move
{ZmFolder} params.folder
the destination folder
{Hash} params.attrs
the additional attrs for SOAP command
{closure} params.finalCallback
the callback to run after all items have been processed
{int} params.count
the starting count for number of items processed
{String} params.actionTextKey
key to optional text to display in the confirmation toast instead of the default summary. May be set explicitly to null to disable the confirmation toast

{ZmItem} create(args)
Creates an item from the given arguments. A subclass may override sortIndex() to add it to a particular point in the list. By default, it will be added at the end.

The item will invoke a SOAP call, which generates a create notification from the server. That will be handled by notifyCreate(), which will call _notify() so that views can be updated.

Parameters:
{Hash} args
a hash of arugments to pass along to the item constructor
Returns:
{ZmItem} the newly created item

createLocal(item)
Creates the item (local).
Parameters:
{ZmItem} item
the item to create

deleteItems(params)
Deletes one or more items from the list. Normally, deleting an item just moves it to the Trash (soft delete). However, if it's already in the Trash, it will be removed from the data store (hard delete).
Parameters:
{Hash} params
a hash of parameters
{Array} params.items
list of items to delete
{Boolean} params.hardDelete
true to force physical removal of items
{Object} params.attrs
additional attrs for SOAP command
{window} params.childWin
the child window this action is happening in
{closure} params.finalCallback
the callback to run after all items have been processed
{int} params.count
the starting count for number of items processed
{Boolean} params.confirmDelete
the user confirmed hard delete

deleteLocal(items)
Deletes the items (local).
Parameters:
{Array} items
an array of items

flagItems(params)
Sets and unsets a flag for each of a list of items.
Parameters:
{Hash} params
a hash of parameters
{Array} params.items
a list of items to set/unset a flag for
{String} params.op
the name of the flag operation ("flag" or "read")
{Boolean|String} params.value
whether to set the flag, or for "update" the flags string
{AjxCallback} params.callback
the callback to run after each sub-request
{closure} params.finalCallback
the callback to run after all items have been processed
{int} params.count
the starting count for number of items processed
{String} params.actionTextKey
pattern for generating action summarykey to action summary message

{ZmItem} get(index)
Gets the item.
Parameters:
{int} index
the index
Returns:
{ZmItem} the index

<static> {String} ZmList.getActionSummary(params)
Returns a string describing an action, intended for display as toast to tell the user what they just did.
Parameters:
{Object} params
hash of params: {String} type item type (ZmItem.*) {Number} numItems number of items affected {String} actionTextKey ZmMsg key for text string describing action {String} actionArg (optional) additional argument
Returns:
{String} action summary

{Array} getArray()
Returns the list as an array.
Returns:
{Array} an array of {ZmItem} objects

{ZmItem} getById(id)
Gets the item with the given id.
Parameters:
{String} id
an item id
Returns:
{ZmItem} the item

{AjxVector} getSubList(offset, limit)
Gets a vector containing a subset of items of this list.
Parameters:
{int} offset
the starting index
{int} limit
the size of sublist
Returns:
{AjxVector} the vector

{AjxVector} getVector()
Returns the list as a vector.
Returns:
{AjxVector} a vector of {ZmItem} objects

{Boolean} hasMore()
Gets if there are more items for this search.
Returns:
{Boolean} true if there are more items

{int} indexOf(item)
Returns the index of the given item in the list.
Parameters:
{ZmItem} item
the item
Returns:
{int} the index

modifyItem(item, mods, callback)
Applies the given list of modifications to the item.
Parameters:
{ZmItem} item
the item to modify
{Hash} mods
hash of new properties
{AjxCallback} callback
the callback

modifyLocal(items, mods)
Modifies the items (local).
Parameters:
{Array} items
an array of items
{Object} mods
a hash of properties to modify

moveItems(params)
Moves a list of items to the given folder.

Search results are treated as though they're in a temporary folder, so that they behave as they would if they were in any other folder such as Inbox. When items that are part of search results are moved, they will disappear from the view, even though they may still satisfy the search.

Parameters:
{Hash} params
a hash of parameters
{Array} params.items
a list of items to move
{ZmFolder} params.folder
the destination folder
{Hash} params.attrs
the additional attrs for SOAP command
{AjxCallback} params.callback
the callback to run after each sub-request
{closure} params.finalCallback
the callback to run after all items have been processed
{int} params.count
the starting count for number of items processed
{boolean} params.noUndo
true if the action is not undoable (e.g. performed as an undo)

moveLocal(items, folderId)
Moves the items (local).
Parameters:
{Array} items
an array of items
{String} folderId
the folder id

notifyCreate(node)
Create notification.
Parameters:
{Object} node
not used

remove(item)
Removes an item from the list.
Parameters:
{ZmItem} item
the item to remove

removeAllTags(params)
Removes all tags from a list of items.
Parameters:
{Hash} params
a hash of parameters
{Array} params.items
a list of items to tag/untag
{AjxCallback} params.callback
the callback to run after each sub-request
{closure} params.finalCallback
the callback to run after all items have been processed
{int} params.count
the starting count for number of items processed

set(respNode)
Populates the list with elements created from the response to a SOAP command. Each node in the response should represent an item of the list's type. Items are added in the order they are received; no sorting is done.
Parameters:
{Object} respNode
an XML node whose children are item nodes

setHasMore(bHasMore)
Sets the "more" flag for this list.
Parameters:
{Boolean} bHasMore
true if there are more items

{int} size()
Returns the number of items in the list.
Returns:
{int} the number of items

tagItems(params)
Tags or untags a list of items. A sanity check is done first, so that items aren't tagged redundantly, and so we don't try to remove a nonexistent tag.
Parameters:
{Hash} params
a hash of parameters
{Array} params.items
a list of items to tag/untag
{String} params.tagId
ID of tag to add/remove
{String} params.tag
the tag to add/remove from each item (optional)
{Boolean} params.doTag
true if adding the tag, false if removing it
{AjxCallback} params.callback
the callback to run after each sub-request
{closure} params.finalCallback
the callback to run after all items have been processed
{int} params.count
the starting count for number of items processed

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