Titanium SDK

# Titanium.Contacts.Person

An object that represents a contact record for a person or organization in the system contacts address book.

Availability
0.8
0.8
9.2.0
Extends
Titanium.Proxy

# Overview

A person object is created using Titanium.Contacts.createPerson.

The following two kinds of properties exist for this object:

  • single value - contains either a string or number type value, an array of string type values, or null if unset.
  • multi-value - contains a dictionary with typical keys of home, work and/or other. Each key contains either a string type value, an array of string type values, or a dictionary containing key/value pairs with string type values.

# Adding and Modifying Properties

Support for adding and modifying properties is currently supported on iOS and Android.

# Keys as Address Book UI Labels

Keys act as labels in the address book user interface.

Although there is limited support for custom, arbitrarily-named, keys when used with multi-value properties, there is no support them with single value properties.

On iOS, creating custom keys is not recommended, and will lead to undefined results.

If a label has been created by the user of the device and used with a multi-value property, it will exist as a key with the same name.

See examples in Titanium.Contacts for more information.

These APIs are unavailable on macOS if the app is built on a version of Xcode < 12.

# Properties

# address

Availability
0.8
0.8
9.2.0
address :Dictionary

Addresses for the person. Multi-value. Read-only on Android.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work, and/or other.
  • Values: arrays of dictionary types with seven keys, CountryCode, Street, City, , State, Country and PostalCode, each with a string type value.

On Android:

'CountryCode' and 'County' are currently not supported.

On iOS:

The CountryCode key value may be one of the recognized two-character ISO 3166-1 country codes, and determines the format in which the contact is presented by the address book user interface. See the wikipedia section ISO 3166-1 alpha-2 for a comprehensive list of codes.

# alternateBirthday

Availability
3.6.0
9.2.0
alternateBirthday :Dictionary

Alternate birthday of the person. Single Dictionary.

The format of the dictionary accepted by this property is as follows:

  • Keys: calendarIdentifier, era, year, month, day and isLeapMonth.
  • Values: Use chinese, hebrew and islamic-civil for calendarIdentifier. Use number type for era, year, month and day. These must be consistent with corresponding calendarIdentifier. Use boolean type for isLeapMonth.

# apiName READONLY

Availability
3.2.0
3.2.0
9.2.0
apiName :String

The name of the API that this proxy corresponds to.

The value of this property is the fully qualified name of the API. For example, Titanium.UI.Button returns Ti.UI.Button.

# birthday

Availability
0.8
0.8
9.2.0
birthday :String

Date of birth of the person. Single value.

Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"

# bubbleParent

Availability
3.0.0
3.0.0
9.2.0
bubbleParent :Boolean

Indicates if the proxy will bubble an event to its parent.

Some proxies (most commonly views) have a relationship to other proxies, often established by the add() method. For example, for a button added to a window, a click event on the button would bubble up to the window. Other common parents are table sections to their rows, table views to their sections, and scrollable views to their views. Set this property to false to disable the bubbling to the proxy's parent.

Default: true

# date

Availability
0.8
0.8
9.2.0
date :Dictionary

Dates associated with the person. Multi-value.

Adding or modifying this property is not currently supported.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of anniversary and/or other.
  • Values: array of string type.

Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"

# department

Availability
0.8
0.8
9.2.0
department :String

Department of the person. Single value.

# email

Availability
0.8
0.8
9.2.0
email :Dictionary

Email addresses for the person. Multi-value. Read-only on Android.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work, and/or other.
  • Values: array of string type.

# firstName

Availability
0.8
0.8
9.2.0
firstName :String

First name of the person. Single value.

# firstPhonetic

Availability
0.8
0.8
9.2.0
firstPhonetic :String

Phonetic first name of the person. Single value.

# fullName READONLY

Availability
0.8
0.8
9.2.0
fullName :String

Localized full name of the person. Single value. Read-only on Android.

The full name will be printed in the order of. Prefix,first name, middle name, family name, suffix.

# id READONLY

Availability
0.8
id :Number

Record identifier of the person. Single value.

# identifier READONLY

Availability
5.0.0
9.2.0
identifier :String

Identifier of the person.

Prior to iOS 9, use the recordId property.

# image

Availability
0.8
0.8
9.2.0
image :Titanium.Blob

Image for the person. Single value. Read-only for >= iOS9

Set to null to remove the image.

# instantMessage

Availability
0.8
0.8
9.2.0
instantMessage :Dictionary

Instant messenger information of the person. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work and/or other.
  • Values: arrays of dictionary types with two keys, service and username, each with a string type value.

The service key value may be one of AIM, Facebook, GaduGadu, GoogleTalk, ICQ, Jabber, MSN, QQ, Skype, or Yahoo. These values are key sensitive.

# jobTitle

Availability
0.8
0.8
9.2.0
jobTitle :String

Job title of the person. Single value.

# kind

Availability
0.8
0.8
9.2.0
kind :Number

Determines the type of information the person record contains; either person or organization. Read-only on Android.

This API can be assigned the following constants:

# lastName

Availability
0.8
0.8
9.2.0
lastName :String

Last name of the person. Single value.

# lastPhonetic

Availability
0.8
0.8
9.2.0
lastPhonetic :String

Phonetic last name of the person. Single value.

# lifecycleContainer

Availability
3.6.0
lifecycleContainer :Titanium.UI.Window | Titanium.UI.TabGroup

The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.

If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks will also be called on the proxy. Proxies that require the activity lifecycle will need this property set to the appropriate containing Window or TabGroup.

# middleName

Availability
0.8
0.8
9.2.0
middleName :String

Middle name of the person. Single value.

# middlePhonetic

Availability
0.8
0.8
9.2.0
middlePhonetic :String

Phonetic middle name of the person. Single value.

# nickname

Availability
0.8
0.8
9.2.0
nickname :String

Nickname of the person. Single value.

# note

Availability
0.8
0.8
9.2.0
note :String

Notes for the person. Single value.

# organization

Availability
0.8
0.8
9.2.0
organization :String

Organization to which the person belongs. Single value.

# phone

Availability
0.8
0.8
9.2.0
phone :Dictionary

Phone numbers for the person. Multi-value. Read-only on Android.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work, other, mobile, pager, workFax, homeFax, main, and/or iPhone.
  • Values: array of string type.

# prefix READONLY

Availability
0.8
0.8
9.2.0
prefix :String

Prefix for the person. Single value.

# recordId

Availability
0.8
9.2.0
recordId :Number

Record identifier of the person. Single value. Deprecated since iOS 9.

For iOS 9 and later, use the identifier property. Previously, a contact can be selected without requiring User permission. In such case this property returns -1.

# relatedNames

Availability
0.8
0.8
9.2.0
relatedNames :Dictionary

Names of people to which the person is related. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of mother, father, parent, brother, sister, child, friend, spouse, partner, assistant, manager, and/or other.
  • Values: array of string type.

# socialProfile

Availability
3.6.0
9.2.0
socialProfile :Dictionary

Social profile information of the person. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of home, work and/or other.
  • Values: arrays of dictionary types with two keys, service and username each with a string type value.

The service key value may be one of twitter, sinaweibo, gamecenter, facebook, myspace, linkedin, or flickr. These values are key sensitive.

# suffix READONLY

Availability
0.8
0.8
9.2.0
suffix :String

Suffix for the person. Single value.

# url

Availability
0.8
0.8
9.2.0
url :Dictionary

URLs of webpages associated with the person. Multi-value.

The format of the dictionary accepted by this property is as follows:

  • Keys: any of homepage, home, work, and/or other.
  • Values: array of string type.

# Methods

# addEventListener

Availability
0.8
0.8
9.2.0
addEventListener(name, callback) → void

Adds the specified callback as an event listener for the named event.

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to invoke when the event is fired.

Returns

Type
void

# applyProperties

Availability
3.0.0
3.0.0
9.2.0
applyProperties(props) → void

Applies the properties to the proxy.

Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that myproxy[key] = value.

Parameters

Name Type Description
props Dictionary

A dictionary of properties to apply.

Returns

Type
void

# fireEvent

Availability
0.8
0.8
9.2.0
fireEvent(name[, event]) → void

Fires a synthesized event to any registered listeners.

Parameters

Name Type Description
name String

Name of the event.

event Dictionary

A dictionary of keys and values to add to the Titanium.Event object sent to the listeners.

Returns

Type
void

# removeEventListener

Availability
0.8
0.8
9.2.0
removeEventListener(name, callback) → void

Removes the specified callback as an event listener for the named event.

Multiple listeners can be registered for the same event, so the callback parameter is used to determine which listener to remove.

When adding a listener, you must save a reference to the callback function in order to remove the listener later:

var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);

To remove the listener, pass in a reference to the callback function:

window.removeEventListener('click', listener);

Parameters

Name Type Description
name String

Name of the event.

callback Callback<Titanium.Event>

Callback function to remove. Must be the same function passed to addEventListener.

Returns

Type
void

Contents