CIS 136 Building Mobile Apps Contacts CIS 136 Building Mobile Apps
Contacts API provides an interface that can be used to create, locate, edit, copy and delete contacts Interfaces with the native Contacts database provided by the mobile platform
Creating a contact Synchronous API call, as it has no callback functions Create method creates an empty object Syntax: var contact = navigator.contacts.create([parameters]); Next steps are: to populate the properties of the object with contact data save the object to the Contacts’ application database
Example - Creating a contact <script> $(document).on("deviceready", onDeviceReady); function onDeviceReady() { var myContact = navigator.contacts.create({"displayName": "Test User"}); myContact.note = "This contact has a note."; myContact.save(onSuccess,onError) } </script> </head> <body> <h1>Example</h1> <p>Create Contact</p> </body> </html>
Contact data example using JSON string var myContact = navigator.contacts.create({ “FullName”: “Michael Smith”, “LastName”: “Smith”, “Firstname”: “Michael”, “EMailAddress”: mSmith@yahoo.com, “OfficePhone:” : “333-212-5555”, “MobilePhone”: “333-212-5556” });
Finding a contact Asynchronous method that queries the device contacts database and returns an array of Contacts as objects Syntax: navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions); Parameters contactFields: Required. Contact fields to use as a search qualifier. The resulting Contact object only features values for these fields. contactSuccess: Required. Success callback function invoked with the contacts returned from the database. Returns an Array contactError: Optional. Error callback function, invoked when an error occurs. contactFindOptions: Optional. Search options to filter contacts.
Contact Error Returned through the ContactError callback function Properties code: One of the predefined error codes listed below. Constants ContactError.UNKNOWN_ERROR ContactError.INVALID_ARGUMENT_ERROR ContactError.TIMEOUT_ERROR ContactError.PENDING_OPERATION_ERROR ContactError.IO_ERROR ContactError.NOT_SUPPORTED_ERROR ContactError.PERMISSION_DENIED_ERROR
contactFindOptions properties that can be used to filter the results of a contacts.find operation filter: The search string used to filter contacts. (Default: "") multiple: Determines if the find operation returns multiple contacts. (Boolean) (Default: false)
Finding contacts - Example 1 // specify contact search criteria var options = new ContactFindOptions(); options.filter=""; // empty search string returns all contacts options.multiple=true; // return multiple results fieldsToReturn = {"displayName“}; // return contact.displayName field // find contacts navigator.contacts.find(fieldsToReturn, onSuccess, onError, options); // success callback function onSuccess(contacts) { for (var i=0; i<contacts.length; i++) { alert(contacts[i].displayName); } }; // error callback function onError(contactError) { alert('onError!');
Finding contacts - Example 2 $(document).on("deviceready", onDeviceReady); function onDeviceReady() { // find all contacts with 'Bob' in any name field var options = new ContactFindOptions(); options.filter = "Bob"; var fieldsToReturn = ["displayName", "name"]; navigator.contacts.find(fields,ToReturn onSuccess, onError, options); } function onSuccess(contacts) { for (var i = 0; i < contacts.length; i++) { console.log("Display Name = " + contacts[i].displayName); function onError(contactError) { alert('onError!');
Look at your contacts on your mobile device what fields do you see on your device?
Contact Objects Objects Contact ContactName ContactField ContactAddress ContactOrganization ContactFindOptions ContactError
Contact Object methods clone() Returns a new Contact object that is a deep copy of the calling object, with the id property set to null. remove() Removes the contact from the device contacts database, otherwise executes an error callback with a ContactError object. save() Saves a new contact to the device contacts database, or updates an existing contact if a contact with the same id already exists.
Contact object properties describe a contact, such as a user's personal or business contact id A unique identifier for the contact displayName The name of the contact name (object) – defines different components of the name (i.e. given name, family name, middle name, etc.) nickname Casual name phoneNumbers (array) –phone numbers Emails (array) email addresses Addresses (array) – physical addresses – home, business, etc.
Contact properties (continued) ims (array) – instant messaging addresses Organizations (array) – a list of the organizations the contact is associated with Birthday Contacts date of birth note Variable used for text-based notes photos (array) – photos of the contact categories (array) user-defined categories associated with the contacts (i.e. friend, family, etc) urls (array) – web addresses associated with the contact
Name Object defines different components of the name (i. e Name Object defines different components of the name (i.e. given name, family name, middle name, etc.) Includes string values: formatted: contacts complete name givenName: family name middleName: middle name honorificPrefix: Dr. Mrs. Mr. etc honorificSuffix: Jr, III, PhD, etc.
Example var options = new ContactFindOptions(); options.filter = ""; fieldsToShow= ["displayName", "name"]; navigator.contacts.find(fieldsToShow, onSuccess, onError, options); 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!');
Addresses (array) – physical addresses – home, business, etc. Two-dimensional array of contact address objects with these values pref: Boolean value that defines if the entry is the default address for the contact type: String defining the address type (home/work) formatted: Full address formatted for display streetAddress: Full street address locality: city region: state postalCode: Zip code country Country associated with address
Example function onSuccess(contacts) { // find all contacts var options = new ContactFindOptions(); options.filter = ""; var fieldsToShow = ["displayName", "addresses"]; navigator.contacts.find(fieldsToShow, onSuccess, onError, options); 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!');
Two-dimensional array of organization objects with these values Organizations (array) – a list of the organizations the contact is associated with Two-dimensional array of organization objects with these values pref: Boolean value that defines if the entry is the preferred or default organization for the contact type: String defining the type of organization (home/work) name: name of the organization department: department where the contact works title: Contacts title in the organizations
Example – 2 dimensional 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);
Phones, emails, and ims Two-dimensional array of objects with these values pref: Boolean value that defines if the entry is the default value type: String defining the type of value (home/work) value: Contact value such as phone number or email address
Example var contact = navigator.contacts.create(); // store contact phone numbers in ContactField[] var phoneNumbers = []; phoneNumbers[0] = new ContactField('work', '212-555-1234', false); phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true); phoneNumbers[2] = new ContactField('home', '203-555-7890', false); contact.phoneNumbers = phoneNumbers; // save the contact contact.save();
More Information https://github.com/apache/cordova-plugin-contacts