Contacts

The contacts object provides functions for creating and finding contacts.


Learning Resources:

Sample - Working with Contacts Sample that demonstrates how to use the BlackBerry Contacts API [BlackBerry Community Samples on GitHub].

Supported Platform(s)

- BlackBerry 10
View Supported Platform Table
APIBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
blackberry.pim.contacts.create           Y 
blackberry.pim.contacts.find           Y 
blackberry.pim.contacts.getContact           Y 
blackberry.pim.contacts.getContactAccounts           Y 
blackberry.pim.contacts.invokeContactPicker           Y 

Configuration Document Settings

To use all of the API described for this object, you must ensure the following settings are in your configuration document:

You must declare the feature element(s) below in your configuration document:

Feature IDBB5.0BB6.0BB7.0PB1.0PB2.0BB10Ripple
<feature id="blackberry.pim.contacts" />           Y 
Permission Elements (PlayBook and BlackBerry 10+)
You must declare the permission element(s) below in your configuration document:
- <rim:permit>access_pimdomain_contacts</rim:permit>
Permits your app to access contacts.

Functions

static blackberry.pim.contacts.Contact blackberry.pim.contacts.create ([properties : Object])


Returns a new Contact object. This method does not persist the Contact object to the device contacts database. To persist the Contact object to the device, invoke the Contact.save method.


Supported Platforms
 - BlackBerry 10


Parameters
properties Optional object literal that specifies the field values for the Contact object. The object should be in the following form (with any number of properties):
{
    displayName: <display name - String>,
    name: <name - ContactName>,
    nickname: <nickname - String>,
    phoneNumbers: <phone numbers - ContactField[]>,
    emails: <email addresses - ContactField[]>,
    addresses: <addresses - ContactAddress[]>,
    ims: <IM addresses - ContactField[]>,
    organizations: <organization - ContactOrganization[]>,
    birthday: <birthday - Date>,
    note: <note - String>,
    photos: <photos - ContactField[]>,
    categories: <user defined categories - ContactField[]>,
    urls: <web pages - ContactField[]>
}

Code Example:
function onSaveSuccess(contact) {
    console.log("Contact with id=" + contact.id + " is saved!");
}

function onSaveError(error) {
    console.log("Error saving contact: " + error.code);
}

function createContact() {
    var contacts = blackberry.pim.contacts,
        ContactField = contacts.ContactField,
        name = {},
        workPhone = { type: ContactField.WORK, value: "123-456-789" },
        workEmail = { type: ContactField.WORK, value: "abc@blah.com" },
        homeEmail = { type: ContactField.HOME, value: "hello@me.com" },
        contact;
        
    name.familyName = "Smith";
    name.givenName = "Joe";
    contact = contacts.create({
         "displayName": "Batman",
         "name": name,
         "phoneNumbers": [workPhone],
         "emails": [workEmail, homeEmail]
    });
    contact.save(onSaveSuccess, onSaveError);
}

static void blackberry.pim.contacts.find (contactFields : String[], findOptions : blackberry.pim.contacts.ContactFindOptions, onFindSuccess : function, [onFindError : function])


Queries the device contacts database. The search results are passed to the onFindSuccess callback function specified by the onFindSuccess parameter.


Supported Platforms
 - BlackBerry 10


Parameters
contactFields A String array of contact fields to be used as search qualifier. Only these fields will have values in the resulting Contact objects.
findOptions Options to be applied to the search.
onFindSuccess Success callback function that is invoked with the contacts returned from the contacts database.

contacts: The array of Contact objects from the search.
onFindError Optional error callback function. Invoked when error occurs. Possible errors are: permission denied error (if access_pimdomain_contacts is not specified) or illegal arguments error (if mandatory parameters are missing or invalid).

error: The blackberry.pim.contacts.ContactError object which contains the error code.

Code Example:
var contacts = blackberry.pim.contacts,
    ContactFindOptions = contacts.ContactFindOptions;

function onFindSuccess(results) {
    console.log("Found " + results.length + " contacts in total");
}

function onFindError(error) {
    console.log("Error: " + error.code);
}

function searchContactsByName() {
    var searchFirstName = {
             "fieldName" : ContactFindOptions.SEARCH_FIELD_GIVEN_NAME,
             "fieldValue" : "John"
        },
        searchLastName = {
             "fieldName" : ContactFindOptions.SEARCH_FIELD_FAMILY_NAME,
             "fieldValue" : "Smith"
        },
        sortOrg = {
             "fieldName" : ContactFindOptions.SORT_FIELD_ORGANIZATION_NAME,
             "desc" : false
        },
        findOptions = {
             filter: [searchFirstName, searchLastName], // filter
             sort: [sortOrg],                           // sort
             limit: 20                                  // limit
        };
    // The first 20 contacts (based on specified sort specs) with given name "John"
    // and family name "Smith" will be returned
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}

function listAllContacts() {
    var sort = [{
             "fieldName": ContactFindOptions.SORT_FIELD_FAMILY_NAME,
             "desc": false
        }, {
             "fieldName": ContactFindOptions.SORT_FIELD_GIVEN_NAME,
             "desc": true
        }],
        // no filter - return all contacts
        findOptions = { 
             // sort contacts first by family name (desc), then by given name (asc)
             sort: sort,  
             limit: 20     // limit - return up to 20 contacts
        };
    // The first 20 contacts (based on specified sort specs) will be returned
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}

function listAllContactsWithEmptyFindOptions() {
    var findOptions = {};
    
    //Will return all contacts with no particular sort order
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}

function findContactErrorMissingFilterValue() {
    var findOptions = {
          filter: [{
                "fieldName": ContactFindOptions.SEARCH_FIELD_GIVEN_NAME,
                "fieldValue": ""
          }, {
                "fieldName": ContactFindOptions.SEARCH_FIELD_FAMILY_NAME,
                "fieldValue": "Smith"
          }],
          sort: [{
                "fieldName": ContactFindOptions.SORT_FIELD_FAMILY_NAME,
                "desc": false
          }, {
                "fieldName": ContactFindOptions.SORT_FIELD_GIVEN_NAME,
                "desc": true
          }],
          limit: 2
       };
    // Error - illegal argument (reason: fieldValue = "" for first search field)
    contacts.find(["name"], findOptions, onFindSuccess, onFindError);
}

static blackberry.pim.contacts.Contact blackberry.pim.contacts.getContact (contactId : String)


Retrieves the contact with specified contactId. This function is especially useful if you have previously obtained an contact object, and you want to get a fresh copy from the backend to make sure all its properties are up-to-date.


Supported Platforms
 - BlackBerry 10


Parameters
contactId The identifier of the contact

Code Example:
var contacts = blackberry.pim.contacts;

function getContactById(contactId) {
    var contact = contacts.getContact(contactId);
    if (contact) {
       alert("Contact id #" + contactId + " corresponds to '" + contact.name.givenName + " " + contact.name.familyName +"'.");
    } else {
       alert("There is no contact with id: " + contactId);
    }
}

static blackberry.pim.contacts.ContactAccount[] blackberry.pim.contacts.getContactAccounts ()


Retrieves all contact accounts.


Supported Platforms
 - BlackBerry 10

static void blackberry.pim.contacts.invokeContactPicker (options : blackberry.pim.contacts.ContactPickerOptions, onDone : function, onCancel : function, onInvoke : function)


Invokes contact picker card.


Supported Platforms
 - BlackBerry 10


Parameters
options An object of type blackberry.pim.contacts.ContactPickerOptions which describes all options available to the contact picker.
onDone The callback function that will be triggered when the user is finished with the contact picker.

data: The data returned by the contact picker. The returned data varies depends on the picker mode.
  1. If mode = MODE_SINGLE:
    {
       // id of the selected contact
       contactId: "123"
    }
  2. If mode = MODE_MULTIPLE:
    {
       // ids of the selected contacts
       contactIds: ["123", "456", "789"]
    }
  3. If mode = MODE_ATTRIBUTE:
    {
       // id of the contact
       contactId: "193",
       // value of the selected attribute
       value: "1234567890",
       // field name of the selected attribute
       field: "phoneNumbers",
       // field type of the selected attribute
       type: "work"
    }
onCancel The callback function that will be triggered if the user presses cancel in the contact picker.
onInvoke The callback function that will be triggered when the contact picker is invoked.

error: The blackberry.pim.contacts.ContactError object which contains the error code. If the contact picker is invoked successfully, the error object will be undefined.

Code Example:
var contacts = blackberry.pim.contacts,
    ContactPickerOptions = contacts.ContactPickerOptions;

function onCancel() {
    alert("User pressed cancel in contact picker.");
}

function onInvoke(error) {
    if (error) {
       alert("Error invoking contact picker: " + error.code);
    } else {
       alert("Contact picker invoked!");
    }
}

function onContactSelected(data) {
    alert("Id of selected contact: " + data.contactId);
}

function onContactsSelected(data) {
    alert("Total # contacts selected: " + data.contactIds.length);
}

function onContactAttributeSelected(data) {
    alert("The selected field '" + data.field + "(" + data.type + ")' has value '" + data.value + "' belongs to contact with id: " + data.contactId);
}

function invokeContactPickerSingle() {
    contacts.invokeContactPicker({
        mode: ContactPickerOptions.MODE_SINGLE,
        fields: ["phoneNumbers"]
    }, onContactSelected, onCancel, onInvoke);
}

function invokeContactPickerMultiple() {
    contacts.invokeContactPicker({
        mode: ContactPickerOptions.MODE_MULTIPLE,
        fields: ["phoneNumbers"]
    }, onContactsSelected, onCancel, onInvoke);
}

function invokeContactPickerAttribute() {
    contacts.invokeContactPicker({
        mode: ContactPickerOptions.MODE_ATTRIBUTE,
        fields: ["phoneNumbers", "emails"]
    }, onContactAttributeSelected, onCancel, onInvoke);
}
Documentation generated by JsDoc Toolkit 2.4.0 on Mon Feb 11 2013 14:51:05 GMT-0500 (EST)