phonegap bridge – telephony cis 136 building mobile apps 1
TRANSCRIPT
Phonegap Bridge – Telephony
CIS 136 Building Mobile Apps
1
2
Telephony
Contacts API
3
Contacts API Plugin: org.apache.cordova.contacts
provides an interface that can be used to create, locate, edit, copy and delete contacts
Interfaces with the native Contacts API provided by the mobile platform
Contacts API is available thru the navigator object
4
Creating a contact Synchronous API call Has no callback functions Creates an empty object Syntax:var contact = navigator.contacts.create();
Next steps are: to populate the properties of the object with contact data save the object to the Contacts’ application database
5
Example<!DOCTYPE html><html> <head> <title>Contact Example</title> <script type="text/javascript" charset="utf-8" src="cordova.js"></script> <script type="text/javascript" charset="utf-8"> document.addEventListener("deviceready", onDeviceReady, false); function onDeviceReady() { var myContact = navigator.contacts.create({"displayName": "Test User"}); myContact.note = "This contact has a note."; console.log("The contact, " + myContact.displayName + ", note: " + myContact.note); }
</script> </head> <body> <h1>Example</h1> <p>Create Contact</p> </body></html>
6
Finding a contact
Asynchronous API call Queries the device contacts database and returns an array of
Contact objects Syntax:navigator.contacts.find(contactFields, contactSuccess, contactError, contactFindOptions);
Parameters contactFields: Contact fields to use as a search qualifier. The resulting
Contact object only features values for these fields. (DOMString[]) [Required]
contactSuccess: Success callback function invoked with the contacts returned from the database. [Required]
contactError: Error callback function, invoked when an error occurs. [Optional]
contactFindOptions: Search options to filter contacts. [Optional]
7
contactFind options properties that can be used to filter the results of a
contacts.find operation
filter: The search string used to filter contacts. (DOMString) (Default: "")
multiple: Determines if the find operation returns multiple contacts. (Boolean) (Default: false)
8
Example 1// success callbackfunction onSuccess(contacts) { for (var i=0; i<contacts.length; i++) { alert(contacts[i].displayName); }};// error callbackfunction onError(contactError) { alert('onError!');};// specify contact search criteriavar options = new ContactFindOptions(); options.filter=""; // empty search string returns all contacts options.multiple=true; // return multiple results fieldsToReturn = ["displayName"]; // return contact.displayName field
// find contactsnavigator.contacts.find(fieldsToReturn, onSuccess, onError, options);
9
Example 2document.addEventListener("deviceready", onDeviceReady, false);
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!');
}
</script>
</head>
<body>
<h1>Example</h1>
<p>Find Contacts</p>
</body>
</html>
10
Look at your contacts on your mobile device
what fields do you see on your device?
11
Contact Objects Objects
Contact ContactName ContactField ContactAddress ContactOrganization ContactFindOptions ContactError
12
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.
13
Contact object propertiesdescribe 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.
14
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
15
Name Objectdefines 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.
16
Examplevar 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!');};
17
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
18
Examplefunction 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 fieldsToShow = ["displayName", "addresses"];
navigator.contacts.find(fieldsToShow, onSuccess, onError, options);
19
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
20
Examplefunction 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);
21
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
22
Examplevar 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();
23
Contact data exampleJSON string{“FullName”: “Michael Smith”,“LastName”: “Smith”,“Firstname”: “Michael”,“EMailAddress”: [email protected],“OfficePhone:” : “333-212-5555”,“MobilePhone”: “333-212-5556”}
24
Contact Success provides the Contact array resulting from a contacts.find
operation Parameters
contacts: The contact array resulting from a find operation
25
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