Contacts

The contacts object provides functions for creating and finding contacts.

Since: BlackBerry WebWorks 2.0

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. Only the fields specified in the contactFields parameter will be returned in the contact object.

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-09-29



Got questions about leaving a comment? Get answers from our Disqus FAQ.

comments powered by Disqus