Contacts

Contacts

The contacts object provides access to the device contacts database.

Methods

Arguments

Objects

contacts.create

Returns a new Contact object.

var contact = navigator.contacts.create(properties);

Description

contacts.create is a synchronous function that 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

Quick Example 

var myContact = navigator.contacts.create({"displayName": "Test User"});

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        var myContact = navigator.contacts.create({"displayName": "Test User"});
        myContact.gender = "male";
        console.log("The contact, " + myContact.displayName + ", is of the " + myContact.gender + " gender");
    }


    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Create Contact</p>
  </body>
</html>

contacts.find

Queries the device contacts database and returns one or more Contact objects, each containing the fields specified.

navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);

Description

contacts.find is an asynchronous function that queries the device contacts database and returns an array of Contact objects. The resulting objects are passed to the contactSuccess callback function specified by the contactSuccess parameter.

Users must specify the contact fields to be used as a search qualifier in the contactFields parameter. Only the fields specified in the contactFields parameter will be returned as properties of the Contact objects that are passed to the contactSuccess callback function. A zero-length contactFields parameter will result in an array of Contact objects with only the id property populated. A contactFields value of ["*"] will return all contact fields.

The contactFindOptions.filter string can be used as a search filter when querying the contacts database. If provided, a case-insensitive, partial value match is applied to each field specified in the contactFields parameter. If a match is found in a comparison with any of the specified fields, the contact is returned.

Parameters

Supported Platforms

Quick Example 

function onSuccess(contacts) {
    alert('Found ' + contacts.length + ' contacts.');
};

function onError(contactError) {
    alert('onError!');
};

// find all contacts with 'Bob' in any name field
var options = new ContactFindOptions();
options.filter="Bob"; 
var fields = ["displayName", "name"];
navigator.contacts.find(fields, onSuccess, onError, options);

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        // find all contacts with 'Bob' in any name field
        var options = new ContactFindOptions();
        options.filter="Bob"; 
        var fields = ["displayName", "name"];
        navigator.contacts.find(fields, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            console.log("Display Name = " + contacts[i].displayName);
        }
    }

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Contact

Contains properties that describe a contact, such as a user's personal or business contact.

Properties

Methods

Details

The Contact object represents a user contact. Contacts can be created, saved to, or removed from the device contacts database. Contacts can also be retrieved (individually or in bulk) from the database by invoking the contacts.find method.

Note: Not all of the above contact fields are supported on every device platform. Please check each platform's Quirks section for information about which fields are supported.

Supported Platforms

Save Quick Example 

function onSuccess(contact) {
    alert("Save Success");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// create a new contact object
var contact = navigator.contacts.create();
contact.displayName = "Plumber";
contact.nickname = "Plumber";       //specify both to support all devices

// populate some fields
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;

// save to device
contact.save(onSuccess,onError);

Clone Quick Example 

// clone the contact object
var clone = contact.clone();
clone.name.givenName = "John";
console.log("Original contact name = " + contact.name.givenName);
console.log("Cloned contact name = " + clone.name.givenName);

Remove Quick Example 

function onSuccess() {
    alert("Removal Success");
};

function onError(contactError) {
    alert("Error = " + contactError.code);
};

// remove the contact from the device
contact.remove(onSuccess,onError);

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        // create
        var contact = navigator.contacts.create();
        contact.displayName = "Plumber";
        contact.nickname = "Plumber";       //specify both to support all devices
        var name = new ContactName();
        name.givenName = "Jane";
        name.familyName = "Doe";
        contact.name = name;

        // save
        contact.save(onSaveSuccess,onSaveError);

        // clone
        var clone = contact.clone();
        clone.name.givenName = "John";
        console.log("Original contact name = " + contact.name.givenName);
        console.log("Cloned contact name = " + clone.name.givenName); 

        // remove
        contact.remove(onRemoveSuccess,onRemoveError);
    }

    // onSaveSuccess: Get a snapshot of the current contacts
    //
    function onSaveSuccess(contact) {
        alert("Save Success");
    }

    // onSaveError: Failed to get the contacts
    //
    function onSaveError(contactError) {
        alert("Error = " + contactError.code);
    }

    // onRemoveSuccess: Get a snapshot of the current contacts
    //
    function onRemoveSuccess(contacts) {
        alert("Removal Success");
    }

    // onRemoveError: Failed to get the contacts
    //
    function onRemoveError(contactError) {
        alert("Error = " + contactError.code);
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X Quirks

Android 1.X Quirks

BlackBerry WebWorks (OS 5.0 and higher) Quirks

iOS Quirks

ContactAddress

Contains address properties for a Contact object.

Properties

Details

The ContactAddress object stores the properties of a single address of a contact. A Contact object can have one or more addresses in a ContactAddress[] array.

Supported Platforms

Quick Example 

// display the address information for all contacts
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].addresses.length; j++) {
            alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
                    "Type: " + contacts[i].addresses[j].type + "\n" +
                    "Formatted: " + contacts[i].addresses[j].formatted + "\n" + 
                    "Street Address: "  + contacts[i].addresses[j].streetAddress + "\n" + 
                    "Locality: "  + contacts[i].addresses[j].locality + "\n" + 
                    "Region: "  + contacts[i].addresses[j].region + "\n" + 
                    "Postal Code: "  + contacts[i].addresses[j].postalCode + "\n" + 
                    "Country: "  + contacts[i].addresses[j].country);
        }
    }
};

function onError(contactError) {
    alert('onError!');
};

// find all contacts
var options = new ContactFindOptions();
options.filter=""; 
var filter = ["displayName","addresses"];
navigator.contacts.find(filter, onSuccess, onError, options);

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        // find all contacts
        var options = new ContactFindOptions();
        options.filter=""; 
        var filter = ["displayName","addresses"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        // display the address information for all contacts
        for (var i=0; i<contacts.length; i++) {
            for (var j=0; j<contacts[i].addresses.length; j++) {
                alert("Pref: " + contacts[i].addresses[j].pref + "\n" +
                        "Type: " + contacts[i].addresses[j].type + "\n" +
                        "Formatted: " + contacts[i].addresses[j].formatted + "\n" + 
                        "Street Address: "  + contacts[i].addresses[j].streetAddress + "\n" + 
                        "Locality: "  + contacts[i].addresses[j].locality + "\n" + 
                        "Region: "  + contacts[i].addresses[j].region + "\n" + 
                        "Postal Code: "  + contacts[i].addresses[j].postalCode + "\n" + 
                        "Country: "  + contacts[i].addresses[j].country);
            }
        }
    };

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X Quirks

Android 1.X Quirks

BlackBerry WebWorks (OS 5.0 and higher) Quirks

iOS Quirks

ContactField

Supports generic fields in a Contact object. Some properties that are stored as ContactField objects include email addresses, phone numbers, and urls.

Properties

Details

The ContactField object is a reusable component that is used to support contact fields in a generic fashion. Each ContactField object contains a value property, a type property, and a pref property. A Contact object stores several properties in ContactField[] arrays, such as phone numbers and email addresses.

In most instances, there are no pre-determined values for the type attribute of a ContactField object. For example, a phone number can have type values of 'home', 'work', 'mobile', 'iPhone', or any other value that is supported by the contact database on a particular device platform. However, in the case of the Contact photos field, PhoneGap makes use of the type field to indicate the format of the returned image. PhoneGap will return type: 'url' when the value attribute contains a URL to the photo image, or type: 'base64' when the returned value attribute contains a Base64 encoded image string.

Supported Platforms

Quick Example 

// create a new contact
var contact = navigator.contacts.create();

// store contact phone numbers in ContactField[]
var phoneNumbers = [3];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
contact.phoneNumbers = phoneNumbers;

// save the contact
contact.save();

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        // create a new contact
        var contact = navigator.contacts.create();

        // store contact phone numbers in ContactField[]
        var phoneNumbers = [3];
        phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
        phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); // preferred number
        phoneNumbers[2] = new ContactField('home', '203-555-7890', false);
        contact.phoneNumbers = phoneNumbers;

        // save the contact
        contact.save();

        // search contacts, returning display name and phone numbers
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","phoneNumbers"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            // display phone numbers
            for (var j=0; j<contacts[i].phoneNumbers.length; j++) {
                alert("Type: " + contacts[i].phoneNumbers[j].type + "\n" + 
                        "Value: "  + contacts[i].phoneNumbers[j].value + "\n" + 
                        "Preferred: "  + contacts[i].phoneNumbers[j].pref);
            }
        }
    };

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android Quirks

BlackBerry WebWorks (OS 5.0 and higher) Quirks

iOS Quirks

ContactFindOptions

Contains properties that can be used to filter the results of a contacts.find operation.

Properties

Supported Platforms

Quick Example 

// success callback
function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert(contacts[i].displayName);
    }
};

// error callback
function onError(contactError) {
    alert('onError!');
};

// specify contact search criteria
var options = new ContactFindOptions();
options.filter="";          // empty search string returns all contacts
options.multiple=true;      // return multiple results
filter = ["displayName"];   // return contact.displayName field

// find contacts
navigator.contacts.find(filter, onSuccess, onError, options);

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        // specify contact search criteria
        var options = new ContactFindOptions();
        options.filter="";          // empty search string returns all contacts
        options.multiple=true;      // return multiple results
        filter = ["displayName"];   // return contact.displayName field

        // find contacts
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            alert(contacts[i].displayName);
        }
    };

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

ContactName

Contains name properties of a Contact object.

Properties

Details

The ContactName object stores name properties of a contact.

Supported Platforms

Quick Example 

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        alert("Formatted: " + contacts[i].name.formatted + "\n" + 
                "Family Name: "  + contacts[i].name.familyName + "\n" + 
                "Given Name: "  + contacts[i].name.givenName + "\n" + 
                "Middle Name: "  + contacts[i].name.middleName + "\n" + 
                "Suffix: "  + contacts[i].name.honorificSuffix + "\n" + 
                "Prefix: "  + contacts[i].name.honorificSuffix);
    }
};

function onError(contactError) {
    alert('onError!');
};

var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","name"];
navigator.contacts.find(filter, onSuccess, onError, options);

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","name"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            alert("Formatted: " + contacts[i].name.formatted + "\n" + 
                    "Family Name: "  + contacts[i].name.familyName + "\n" + 
                    "Given Name: "  + contacts[i].name.givenName + "\n" + 
                    "Middle Name: "  + contacts[i].name.middleName + "\n" + 
                    "Suffix: "  + contacts[i].name.honorificSuffix + "\n" + 
                    "Prefix: "  + contacts[i].name.honorificPrefix);
        }
    };

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android Quirks

BlackBerry WebWorks (OS 5.0 and higher) Quirks

iOS Quirks

ContactOrganization

Contains organization properties of a Contact object.

Properties

Details

The ContactOrganization object stores a contact's organization properties. A Contact object stores one or more ContactOrganization objects in an array.

Supported Platforms

Quick Example 

function onSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        for (var j=0; j<contacts[i].organizations.length; j++) {
            alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
                    "Type: " + contacts[i].organizations[j].type + "\n" +
                    "Name: " + contacts[i].organizations[j].name + "\n" + 
                    "Department: "  + contacts[i].organizations[j].department + "\n" + 
                    "Title: "  + contacts[i].organizations[j].title);
        }
    }
};

function onError(contactError) {
    alert('onError!');
};

var options = new ContactFindOptions();
options.filter="";
filter = ["displayName","organizations"];
navigator.contacts.find(filter, onSuccess, onError, options);

Full Example 

<!DOCTYPE html>
<html>
  <head>
    <title>Contact Example</title>

    <script type="text/javascript" charset="utf-8" src="phonegap.js"></script>
    <script type="text/javascript" charset="utf-8">

    // Wait for PhoneGap to load
    //
    document.addEventListener("deviceready", onDeviceReady, false);

    // PhoneGap is ready
    //
    function onDeviceReady() {
        var options = new ContactFindOptions();
        options.filter="";
        filter = ["displayName","organizations"];
        navigator.contacts.find(filter, onSuccess, onError, options);
    }

    // onSuccess: Get a snapshot of the current contacts
    //
    function onSuccess(contacts) {
        for (var i=0; i<contacts.length; i++) {
            for (var j=0; j<contacts[i].organizations.length; j++) {
                alert("Pref: " + contacts[i].organizations[j].pref + "\n" +
                        "Type: " + contacts[i].organizations[j].type + "\n" +
                        "Name: " + contacts[i].organizations[j].name + "\n" + 
                        "Department: "  + contacts[i].organizations[j].department + "\n" + 
                        "Title: "  + contacts[i].organizations[j].title);
            }
        }
    };

    // onError: Failed to get the contacts
    //
    function onError(contactError) {
        alert('onError!');
    }

    </script>
  </head>
  <body>
    <h1>Example</h1>
    <p>Find Contacts</p>
  </body>
</html>

Android 2.X Quirks

Android 1.X Quirks

BlackBerry WebWorks (OS 5.0 and higher) Quirks

iOS Quirks

ContactError

A ContactError object is returned to the contactError callback when an error occurs.

Properties

Constants

Description

The ContactError object is returned to the user through the contactError callback function when an error occurs.

contactSuccess

Success callback function that provides the Contact array resulting from a contacts.find operation.

function(contacts) {
    // Do something
}

Parameters

Example 

function contactSuccess(contacts) {
    for (var i=0; i<contacts.length; i++) {
        console.log("Display Name = " + contacts[i].displayName;
}

contactError

Error callback function for contact functions.

function(error) {
    // Handle the error
}

contactFields

Required parameter of the contacts.find method. Use this parameter to specify which fields should be included in the Contact objects resulting from a find operation.

["name", "phoneNumbers", "emails"]

contactFindOptions

Optional parameter of the contacts.find method. Use this parameter to filter the contacts returned from the contacts database.

{ 
    filter: "",
    multiple: true,
};

Options