With the first and second parts of this tutorial we have gotten pretty far when it comes to understanding PhoneGap and in this last part we will take a look at some more device API’s that we can make use of when creating our mobile applications with PhoneGap.
The Contacts API
The name in this API is pretty self explanatory , with this API we can access the device’s contacts database and it allows us to either create , find , clone or delete a contact.
To create a contact we need to use the contacts.create method and using that method to create a simple contact is as simple as:
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
var contact = navigator.contacts.create();
//Names
contact.displayName = "Jane";
contact.nickname = "Jane";
var name = new ContactName();
name.givenName = "Jane";
name.familyName = "Doe";
contact.name = name;
//Phone Numbers
var phoneNumbers = [];
phoneNumbers[0] = new ContactField('work', '212-555-1234', false);
phoneNumbers[1] = new ContactField('mobile', '917-555-5432', true);
contact.phoneNumbers = phoneNumbers;
contact.save(saveSuccess,saveError);
}If we take a look at the code you can see that we first waited for the device to be ready, like we usually do when it comes to these API’s, then we use the contacts.create method and assign it to the variable called contact.
The next step was to give our contact a display name ( I also set a nickname for compatibility), in the next part we set the contact’s name and family name, this is where we can place other things like middleName, honorificPrefix and honorificSuffix.
Next we add the contact’s phone numbers, and these must be placed inside an array because one person can have various phone numbers, it’s the same idea with e-mails.
The last things we need to do is save the contact to the database and provide success and error functions where we can just place an alert or anything we please.
This was just the create method, we can also clone, find or even remove contacts from the database.
The Connection API
In some cases you may need the application to be aware of what connection, if any, the device is using. Whether you’re downloading a file or synchronizing data, it’s always a good idea for the app to be mindful of the type of connection.
In order to check for all types of connections and alert the proper one we’d use something like:
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
checkConnection();
}
function checkConnection() {
var networkState = navigator.connection.type;
var states = {};
states[Connection.UNKNOWN] = 'Unknown';
states[Connection.ETHERNET] = 'Ethernet';
states[Connection.WIFI] = 'WiFi';
states[Connection.CELL_2G] = 'Cell 2G';
states[Connection.CELL_3G] = 'Cell 3G';
states[Connection.CELL_4G] = 'Cell 4G';
states[Connection.CELL] = 'Cell generic';
states[Connection.NONE] = 'No connection';
alert('Connection type: ' + states[networkState]);
}In this piece of code, after the document has finished loading we call the checkConnection function and in that function all we do is provide readable names for all types of connection so that we can alert that to the user.
The connection API is a very simple one to put into use but it’s also a very specific API , it’s not needed in all applications but is very helpful when called upon.
The device API
This will be the last API we will be talking about and with this API we can gather all the information we may need about the device our application is running on, like the OS, model and version of that OS so that if, for example, we have code that needs a certain version of Android to run we won’t run it if the test we did on the device version comes back negative. To get all the information from the device and place it on the screen we use something like:
document.addEventListener("deviceready", onDeviceReady, false);
function onDeviceReady() {
var info = document.getElementById('info');
info.innerHTML = 'Device Model: ' + device.model + '<br />' +
'Platform: ' + device.platform + '<br />' +
'Version: ' + device.version + '<br />' +
'Cordova: ' + device.cordova + '<br />' +
'Identifier: ' + device.uuid;
}In this API, after the document has finished loading, we first grab the element where we want our device info to be placed and then grab all of its characteristics; first we get the model, then the OS and its version, then the Cordova version and finally we get the device’s Universally Unique Identifier. Now we have this data we can do something useful with it like show the correct UI.
Conclusion
When it comes to phone applications there are literally thousands of applications for all the OS’s but the transition between creating a web app and a phone app used to be quite rough and now we can do it smoothly using all the languages we already use on our daily life.
There is still a lot of PhoneGap to discover and build upon but these three articles have been your long introduction to what it can do and just how much you can customize your application depending on the device or even location.
Now go build some great mobile applications with PhoneGap.
