license: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing,
     software distributed under the License is distributed on an
     "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
     KIND, either express or implied.  See the License for the
     specific language governing permissions and limitations
     under the License.

ContactAddress

Contains address properties for a Contact object.

Properties

  • pref: Set to true if this ContactAddress contains the user's preferred value. (boolean)
  • type: A string that tells you what type of field this is (example: ‘home’). _(DOMString)
  • formatted: The full address formatted for display. (DOMString)
  • streetAddress: The full street address. (DOMString)
  • locality: The city or locality. (DOMString)
  • region: The state or region. (DOMString)
  • postalCode: The zip code or postal code. (DOMString)
  • country: The country name. (DOMString)

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

  • Android
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS
  • Bada 1.2 & 2.0
  • Windows Phone 7 and 8
  • Windows 8

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="cordova-2.8.0.js"></script>
    <script type="text/javascript" charset="utf-8">

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

    // Cordova 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

  • pref: This property is not supported by Android 2.X devices and will always return false.

BlackBerry WebWorks (OS 5.0 and higher) Quirks

  • pref: This property is not supported on Blackberry devices and will always return false.
  • type: Partially supported. Only one each of “Work” and “Home” type addresses can be stored per contact.
  • formatted: Partially supported. Will return concatenation of all BlackBerry address fields.
  • streetAddress: Supported. Will return concatenation of BlackBerry address1 and address2 address fields.
  • locality: Supported. Stored in BlackBerry city address field.
  • region: Supported. Stored in BlackBerry stateProvince address field.
  • postalCode: Supported. Stored in BlackBerry zipPostal address field.
  • country: Supported.

iOS Quirks

  • pref: This property is not supported on iOS devices and will always return false.
  • formatted: Not currently supported.

Bada Quirks

  • formatted: This property is not supported
  • type: Has to be one of the following: WORK, HOME