ContactName

Contains name properties of a [Contact](../Contact/contact.html) object.

Properties

  • formatted: The complete name of the contact. (DOMString)
  • familyName: The contacts family name. (DOMString)
  • givenName: The contacts given name. (DOMString)
  • middleName: The contacts middle name. (DOMString)
  • honorificPrefix: The contacts prefix (example Mr. or Dr.) (DOMString)
  • honorificSuffix: The contacts suffix (example Esq.). (DOMString)

Details

The ContactName object stores name properties of a contact.

Supported Platforms

  • Android 2.X
  • BlackBerry WebWorks (OS 5.0 and higher)
  • iOS

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

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

    // Cordova is ready
    //
    function onDeviceReady() {
		var options = new [ContactFindOptions](../ContactFindOptions/contactfindoptions.html)();
		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

  • formatted: Partially supported. Will return the concatenation of honorificPrefix, givenName, middleName, familyName and honorificSuffix but will not store.

BlackBerry WebWorks (OS 5.0 and higher) Quirks

  • formatted: Partially supported. Will return concatenation of BlackBerry firstName and lastName fields.
  • familyName: Supported. Stored in BlackBerry lastName field.
  • givenName: Supported. Stored in BlackBerry firstName field.
  • middleName: This property is not supported, and will always return null.
  • honorificPrefix: This property is not supported, and will always return null.
  • honorificSuffix: This property is not supported, and will always return null.

iOS Quirks

  • formatted: Partially supported. Will return iOS Composite Name but will not store.