Contacts

The contacts object provides functions for creating and finding contacts.

Installation:

To use this API in your project, add the contacts plugin:

webworks plugin add com.blackberry.pim.contacts

Learning Resources:

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

create()

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.

Synopsis:

blackberry.pim.contacts.Contact blackberry.pim.contacts.create(properties)

Parameters:

properties {Object}

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[]>
}
                        

Returns:

{blackberry.pim.contacts.Contact}

The contact object.

Example:

<script type="text/javascript">

    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);
    }
</script>
            

find()

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

Synopsis:

void blackberry.pim.find(contactFields,findOptions,onFindSuccess,onFindError)

Parameters:

contactFields {String[]}

A String array of contact fields to be used as search qualifier. Only these fields will have values in the resulting Contact objects.

findOptions {blackberry.pim.contacts.ContactFindOptions}

Options to be applied to the search.

onFindSuccess {function}

Success callback function that is invoked with the contacts returned from the contacts database.

contacts {blackberry.pim.contacts.Contact[]}

The array of Contact objects from the search.

onFindError {function}

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 {blackberry.pim.contacts.ContactError}

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

Example:

<script type="text/javascript">

    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);
    }
</script>
            

getContact()

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.

Synopsis:

blackberry.pim.contacts.Contact blackberry.pim.contacts.getContact(contactId)

Parameters:

contactId {String}

The identifier of the contact

Returns:

{blackberry.pim.contacts.Contact}

The contact object.

Example:

<script type="text/javascript">

    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);
        }
    }

</script>
            

getContactAccounts()

Retrieves all contact accounts.

Synopsis:

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

Returns:

{blackberry.pim.contacts.ContactAccount[]}

The contact account object.

invokeContactPicker()

Invokes contact picker card.

Synopsis:

void blackberry.pim.contacts.invokeContactPicker(options,onDone,onCancel,onInvoke)

Parametercs:

options {blackberry.pim.contacts.ContactPickerOptions}

An object of type blackberry.pim.contacts.ContactPickerOptions which describes all options available to the contact picker.

onDone {function}

The callback function that will be triggered when the user is finished with the contact picker.

data {Object}

The data returned by the contact picker. The returned data varies depends on the picker mode.

  1. If mode = blackberry.pim.contacts.ContactPickerOptions.MODE_SINGLE:
    {
        // id of the selected contact
        contactId: "123"
    }
  2. If mode = blackberry.pim.contacts.ContactPickerOptions.MODE_MULTIPLE:
    {
        // ids of the selected contacts
        contactIds: ["123", "456", "789"]
    }
                                            
  3. If mode = blackberry.pim.contacts.ContactPickerOptions.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 {function}

The callback function that will be triggered if the user presses cancel in the contact picker.

onInvoke {function}

The callback function that will be triggered when the contact picker is invoked.

onInvoke.error {blackberry.pim.contacts.ContactError}

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

Example:

<script type="text/javascript">

    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);
    }

</script>
            

Last modified: 2014-04-10