Zimlet JavaScript API Reference - ZmContact

Class ZmContact


Extends ZmItem.

This class represents a contact (typically a person) with all its associated versions of email address, home and work addresses, phone numbers, etc. Contacts can be filed/sorted in different ways, with the default being Last, First. A contact is an item, so it has tagging and flagging support, and belongs to a list.

Most of a contact's data is kept in attributes. These include name, phone, etc. Meta-data and data common to items are not kept in attributes. These include flags, tags, folder, and modified/created dates. Since the attribute data for contacts is loaded only once, a contact gets its attribute values from that canonical list.



Defined in: ZmContact.js.

Class Summary
Constructor Attributes Constructor Name and Description
 
ZmContact(id, list, type, newDl)
Creates an empty contact.
Field Summary
Field Attributes Field Name and Description
<static>  
ZmContact.IS_ADDONE
This structure can be queried to determine if the first entry in a multi-value entry is suffixed with "1".
Method Summary
Method Attributes Method Name and Description
<static>  
ZmContact.compareByFileAs(a, b)
Compares two contacts based on how they are filed.
<static>  
ZmContact.computeCustomFileAs(customFileAs)
Computes the custom file as string by prepending "8:" to the given custom fileAs string.
<static>  
ZmContact.computeFileAs(contact)
Figures out the filing string for the contact according to the chosen method.
 
create(attr, batchCmd, isAutoCreate)
Creates a contact from the given set of attributes.
<static>  
ZmContact.createFromDom(node, args)
Creates a contact from an XML node.
 
createFromVCard(msgId, vcardPartId)
Creates a contct from a VCF part of a message.
<static>  
ZmContact.fileAsCompanyName(name, company)
Name printing helper "Company (Name)".
<static>  
ZmContact.fileAsFirstLast(first, last, fullname, nickname)
Name printing helper "First Last".
<static>  
ZmContact.fileAsLastFirst(first, last, fullname, nickname)
Name printing helper "Last, First".
<static>  
ZmContact.fileAsNameCompany(name, company)
Name printing helper "Name (Company)".
 
Gets the address book.
 
getAllDLMembers(callback)
Returns a list of all the distribution list members for this contact.
 
parses "groups" attr into an AjxEmailAddress with a few extra attributes (see ZmContactsHelper._wrapInlineContact)
 
getAttendeeKey(type, shortForm)
Gets display text for an attendee.
 
getAttendeeText(type, shortForm)
Gets display text for an attendee.
<static>  
ZmContact.getAttr(contact, attr)
Gets an attribute.
 
getAttr(name)
Gets the attribute.
<static>  
ZmContact.getAttributeName(name, index)
Gets an indexed attribute name taking into account if the field with index 1 should append the "1" or not.
 
getAttrs(prefix)
Gets the contact attributes.
 
Gets the company field.
 
getDLMembers(offset, limit, callback)
Returns a list of distribution list members for this contact.
 
getEmail(asObj)
Gets the email address.
 
Gets the emails.
 
getFields(field, sortByNameFunc)
Gets the fields.
 
getFileAs(lower)
Gets the filing string for this contact, computing it if necessary.
 
Gets the filing string for this contact, from the email address (used in case no name exists).
 
Gets the folder id.
 
Gets the full name.
 
Gets the group members.
 
Gets the header.
 
getHomeAddrField(instance)
Gets the home address.
 
getIcon(addrBook)
Gets the icon.
 
getId(includeUserZid)
Returns the contact id.
 
getImageUrl(maxWidth, maxHeight)
Get the image URL.
 
Gets the lookup email address, when an contact object is located using email address we store the referred email address in this variable for easy lookup
<static>  
ZmContact.getNormalizedAttrs(attrs, prefix, ignore)
Normalizes the numbering of the given attribute names and returns a new object with the re-numbered attributes.
 
Gets a normalized set of attributes where the attribute names have been re-numbered as needed.
 
Gets the other address.
 
gets the participant role.
 
gets the participant status.
 
Returns user's phone number
<static>  
ZmContact.getPrefix(s)
returns the prefix of a string in the format "abc123".
 
getToolTip(email, isGal, hint)
Gets the tool tip for this contact.
 
getUnknownFields(sortByNameFunc)
Gets the unknown fields.
 
getWorkAddrField(instance)
Gets the work address.
 
initFromEmail(email, strictName)
Initializes this contact using an email address.
 
initFromPhone(phone, field)
Initializes this contact using a phone number.
 
Checks if the contact is a DL.
 
Checks if the contact attributes are empty.
 
Checks if the contact is a group.
<static>  
ZmContact.isInTrash(contact)
Checks if the contact is in the trash.
 
Checks if the contact is locked.
 
Checks if the contact is read-only.
 
Checks if the contact is shared.
<static>  
ZmContact.mapAttrs(attrs)
Takes a hash of attrs and values and maps it to our attr names as best as it can.
 
modify(attr, callback, isAutoSave, batchCmd)
Updates contact attributes.
 
removeAttr(name)
Removes the attribute.
<static>  
ZmContact.setAttr(contact, attr, value)
Sets the attribute.
 
setAttr(name, value)
Sets the attribute.
 
Sets the participant role.
 
Sets the participant status.
 
Returns a string representation of the object.
Methods borrowed from class ZmItem:
cache, canAddTag, clear, deleteLocal, flagLocal, getById, getDefaultDndAction, getRestUrl, getTagImageFromIds, getTagImageInfo, hasTag, move, moveLocal, removeAllTagsLocal, rename, setFlag, tagLocal
Methods borrowed from class ZmModel:
addChangeListener, removeAllChangeListeners, removeChangeListener
Class Detail
ZmContact(id, list, type, newDl)
Creates an empty contact.
Parameters:
{int} id
the unique ID
{ZmContactList} list
the list that contains this contact
{constant} type
the item type
{object} newDl
true if this is a new DL
Field Detail
<static> ZmContact.IS_ADDONE
This structure can be queried to determine if the first entry in a multi-value entry is suffixed with "1". Most attributes add a numerical suffix to all but the first entry.

Note: In most cases, ZmContact#getAttributeName is a better choice.

Method Detail
<static> {int} ZmContact.compareByFileAs(a, b)
Compares two contacts based on how they are filed. Intended for use by sort methods.
Parameters:
{ZmContact} a
a contact
{ZmContact} b
a contact
Returns:
{int} 0 if the contacts are the same; 1 if "a" is before "b"; -1 if "b" is before "a"

<static> {String} ZmContact.computeCustomFileAs(customFileAs)
Computes the custom file as string by prepending "8:" to the given custom fileAs string.
Parameters:
{Hash} customFileAs
a set of contact attributes
Returns:
{String} the name format

<static> ZmContact.computeFileAs(contact)
Figures out the filing string for the contact according to the chosen method.
Parameters:
{ZmContact|Hash} contact
a contact or a hash of contact attributes

create(attr, batchCmd, isAutoCreate)
Creates a contact from the given set of attributes. Used to create contacts on the fly (rather than by loading them). This method is called by a list's create() method.

If this is a GAL contact, we assume it is being added to the contact list.

Parameters:
{Hash} attr
the attribute/value pairs for this contact
{ZmBatchCommand} batchCmd
the batch command that contains this request
{boolean} isAutoCreate
true if this is a auto create and toast message should not be shown

<static> {ZmContact} ZmContact.createFromDom(node, args)
Creates a contact from an XML node.
Parameters:
{Object} node
a "cn" XML node
{Hash} args
args to pass to the constructor
Returns:
{ZmContact} the contact

createFromVCard(msgId, vcardPartId)
Creates a contct from a VCF part of a message.
Parameters:
{String} msgId
the message
{String} vcardPartId
the vcard part id

<static> {String} ZmContact.fileAsCompanyName(name, company)
Name printing helper "Company (Name)".
Parameters:
{String} name
the contact name
{String} company
the company
Returns:
{String} the name format

<static> {String} ZmContact.fileAsFirstLast(first, last, fullname, nickname)
Name printing helper "First Last".
Parameters:
{String} first
the first name
{String} last
the last name
{String} fullname
the fullname
{String} nickname
the nickname
Returns:
{String} the name format

<static> {String} ZmContact.fileAsLastFirst(first, last, fullname, nickname)
Name printing helper "Last, First".
Parameters:
{String} first
the first name
{String} last
the last name
{String} fullname
the fullname
{String} nickname
the nickname
Returns:
{String} the name format

<static> {String} ZmContact.fileAsNameCompany(name, company)
Name printing helper "Name (Company)".
Parameters:
{String} name
the contact name
{String} company
the company
Returns:
{String} the name format

{ZmAddrBook} getAddressBook()
Gets the address book.
Returns:
{ZmAddrBook} the address book

getAllDLMembers(callback)
Returns a list of all the distribution list members for this contact.
Parameters:
callback
{AjxCallback} callback to run with results

{AjxVector} getAllGroupMembers()
parses "groups" attr into an AjxEmailAddress with a few extra attributes (see ZmContactsHelper._wrapInlineContact)
Returns:
{AjxVector} the group members or null if not group

{String} getAttendeeKey(type, shortForm)
Gets display text for an attendee. Prefers name over email.
Parameters:
{constant} type
the attendee type
{Boolean} shortForm
if true, return only name or email
Returns:
{String} the attendee

{String} getAttendeeText(type, shortForm)
Gets display text for an attendee. Prefers name over email.
Parameters:
{constant} type
the attendee type
{Boolean} shortForm
if true, return only name or email
Returns:
{String} the attendee

<static> {Object} ZmContact.getAttr(contact, attr)
Gets an attribute.
Parameters:
{ZmContact} contact
the contact
{String} attr
the attribute
Returns:
{Object} the attribute value or null for none

{String} getAttr(name)
Gets the attribute.
Parameters:
{String} name
the attribute name
Returns:
{String} the value

<static> ZmContact.getAttributeName(name, index)
Gets an indexed attribute name taking into account if the field with index 1 should append the "1" or not. Code should call this function in lieu of accessing ZmContact.IS_ADDONE directly.
Parameters:
name
index

{Hash} getAttrs(prefix)
Gets the contact attributes.
Parameters:
{String} prefix Optional
if specified, only the the attributes that match the given prefix will be returned
Returns:
{Hash} a hash of attribute/value pairs

{String} getCompanyField()
Gets the company field. Company field has a getter b/c fileAs may be the Company name so company field should return "last, first" name instead *or* prepend the title if fileAs is not Company (assuming it exists).
Returns:
{String} the company

getDLMembers(offset, limit, callback)
Returns a list of distribution list members for this contact. Only the requested range is returned.
Parameters:
offset
{int} offset into list to start at
limit
{int} number of members to fetch and return
callback
{AjxCallback} callback to run with results

getEmail(asObj)
Gets the email address.
Parameters:
{boolean} asObj
if true, return an AjxEmailAddress
Returns:
the email address

{Array} getEmails()
Gets the emails.
Returns:
{Array} an array of all valid emails for this contact

{Array} getFields(field, sortByNameFunc)
Gets the fields.
Parameters:
{Array} field
the fields
{function} sortByNameFunc Optional
sort by function
Returns:
{Array} an array of field name/value pairs

{String} getFileAs(lower)
Gets the filing string for this contact, computing it if necessary.
Parameters:
{Boolean} lower
true to use lower case
Returns:
{String} the file as string

{String} getFileAsNoName()
Gets the filing string for this contact, from the email address (used in case no name exists). todo - maybe return this from getFileAs, but there are a lot of callers to getFileAs, and not sure of the implications on all the use-cases.
Returns:
{String} the file as string

{String} getFolderId()
Gets the folder id.
Returns:
{String} the folder id

{String} getFullName(html)
Gets the full name.
Parameters:
html
Returns:
{String} the full name

{AjxVector} getGroupMembers()
Gets the group members.
Returns:
{AjxVector} the group members or null if not group

{String} getHeader()
Gets the header.
Returns:
{String} the header

{String} getHomeAddrField(instance)
Gets the home address.
Parameters:
{Object} instance
(not used)
Returns:
{String} the home address

{String} getIcon(addrBook)
Gets the icon.
Parameters:
{ZmAddrBook} addrBook
address book of contact
Returns:
{String} the icon

{String} getId(includeUserZid)
Returns the contact id. If includeUserZid is true it will return the format zid:id
Parameters:
includeUserZid
{boolean} true to include the zid prefix for the contact id
Returns:
{String} contact id string

{String} getImageUrl(maxWidth, maxHeight)
Get the image URL. Please note that maxWidth and maxHeight are hints, as they have no effect on Zimlet-supplied images. maxWidth {int} max pixel width (optional - default 48, or pass ZmContact.NO_MAX_IMAGE_WIDTH if full size image is required) maxHeight {int} max pixel height (optional - default to maxWidth, or pass ZmContact.NO_MAX_IMAGE_HEIGHT if full size image is required)
Parameters:
maxWidth
maxHeight
Returns:
{String} the image URL

getLookupEmail(asObj)
Gets the lookup email address, when an contact object is located using email address we store the referred email address in this variable for easy lookup
Parameters:
{boolean} asObj
if true, return an AjxEmailAddress
Returns:
the lookup address

<static> {Hash} ZmContact.getNormalizedAttrs(attrs, prefix, ignore)
Normalizes the numbering of the given attribute names and returns a new object with the re-numbered attributes. For example, if the attributes contains a "foo2" but no "foo", then the "foo2" attribute will be renamed to "foo" in the returned object.
Parameters:
{Hash} attrs
a hash of attributes to normalize.
{String} prefix Optional
if specified, only the the attributes that match the given prefix will be returned
{Array} ignore Optional
if specified, the attributes that are present in the array will not be normalized
Returns:
{Hash} a hash of normalized attributes

{Hash} getNormalizedAttrs(prefix)
Gets a normalized set of attributes where the attribute names have been re-numbered as needed. For example, if the attributes contains a "foo2" but no "foo", then the "foo2" attribute will be renamed to "foo" in the returned object.

Note: This method is expensive so should be called once and cached temporarily as needed instead of being called for each normalized attribute that is needed.

Parameters:
{String} prefix Optional
if specified, only the the attributes that match the given prefix will be returned.
Returns:
{Hash} a hash of attribute/value pairs

{String} getOtherAddrField(instance)
Gets the other address.
Parameters:
{Object} instance
(not used)
Returns:
{String} the other address

{String} getParticipantRole()
gets the participant role.
Returns:
{String} the value

{String} getParticipantStatus()
gets the participant status.
Returns:
{String} the value

{String} getPhone()
Returns user's phone number
Returns:
{String} phone number

<static> ZmContact.getPrefix(s)
returns the prefix of a string in the format "abc123". (would return "abc"). If the string is all number, it's a special case and returns the string itself. e.g. "234" would return "234".
Parameters:
s

{String} getToolTip(email, isGal, hint)
Gets the tool tip for this contact.
Parameters:
{String} email
the email address
{Boolean} isGal
(not used)
{String} hint
the hint text
Returns:
{String} the tool tip in HTML

{Array} getUnknownFields(sortByNameFunc)
Gets the unknown fields.
Parameters:
{function} sortByNameFunc Optional
sort by function
Returns:
{Array} an array of field name/value pairs

{String} getWorkAddrField(instance)
Gets the work address.
Parameters:
{Object} instance
(not used)
Returns:
{String} the work address

initFromEmail(email, strictName)
Initializes this contact using an email address.
Parameters:
{AjxEmailAddress|String} email
an email address or an email string
{Boolean} strictName
if true, do not try to set name from user portion of address

initFromPhone(phone, field)
Initializes this contact using a phone number.
Parameters:
{String} phone
the phone string
{String} field
the field or company phone if null

{Boolean} isDistributionList()
Checks if the contact is a DL.
Returns:
{Boolean} true if a group

{Boolean} isEmpty()
Checks if the contact attributes are empty.
Returns:
{Boolean} true if empty

{Boolean} isGroup()
Checks if the contact is a group.
Returns:
{Boolean} true if a group

<static> {Boolean} ZmContact.isInTrash(contact)
Checks if the contact is in the trash.
Parameters:
{ZmContact} contact
the contact
Returns:
{Boolean} true if in trash

{Boolean} isLocked()
Checks if the contact is locked. This is different for DLs than read-only.
Returns:
{Boolean} true if read-only

{Boolean} isReadOnly()
Checks if the contact is read-only.
Returns:
{Boolean} true if read-only

{Boolean} isShared()
Checks if the contact is shared.
Returns:
{Boolean} true if shared

<static> {Object} ZmContact.mapAttrs(attrs)
Takes a hash of attrs and values and maps it to our attr names as best as it can. Scalar attrs will map if they have the same name or only differ by case. A multivalued attr will map to a set of our attributes that share the same case-insensitive base name. Some examples: FIRSTNAME: "Mildred" => firstName: "Mildred" email: ['a', 'b'] => email: 'a', email2: 'b' WorkEmail: ['y', 'z'] => workEmail1: 'y', workEmail2: 'z' IMaddress: ['f', 'g'] => imAddress1: 'f', imAddress2: 'g'
Parameters:
{Object} attrs
hash of attr names/values
Returns:
{Object} hash of attr names/values using known attr names ZmContact.F_*

modify(attr, callback, isAutoSave, batchCmd)
Updates contact attributes.
Parameters:
{Hash} attr
a set of attributes and new values
{AjxCallback} callback
the callback
{boolean} isAutoSave
true if it is a auto save and toast should not be displayed.
batchCmd

removeAttr(name)
Removes the attribute.
Parameters:
{String} name
the attribute name

<static> ZmContact.setAttr(contact, attr, value)
Sets the attribute.
Parameters:
{ZmContact} contact
the contact
{String} attr
the attribute
{Object} value
the attribute value

setAttr(name, value)
Sets the attribute.
Parameters:
{String} name
the attribute name
{String} value
the attribute value

setParticipantRole(value)
Sets the participant role.
Parameters:
{String} value
the participant role value

setParticipantStatus(value)
Sets the participant status.
Parameters:
{String} value
the participant status value

{String} toString()
Returns a string representation of the object.
Returns:
{String} a string representation of the object

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