How to get started?
In my previous blog posts I’ve shown how to use PhoneGap with Xcode and Eclipse in targeting iOS and Android platforms. For this blog post, I will show how to use the PhoneGap API with Visual Studio and the Windows Phone 7 emulator as your development environment.
For this sample project, we will also be using JQuery and JQuery Mobile UI.
Now to get started, PhoneGap has documentation on what tools to download and what steps to follow. After you have your development environment setup, you can look over PhoneGap’s API documentation. The API is not to cumbersome and is straight-forward in following for each of the different device hardware. Most of the API involvrs javascript callbacks as I will show below in example code.
For this blog post, I will discuss how to use the following:
1. Device
2. Accelerometer
3. Camera
4. Geolocation
5. Notification
Most of the API methods and objects will exist on most of the major platforms (iOS, Android, WP7). However, some things will be specific on some platforms. Android and WP7 has a search and back button but iOS doesn’t. The menu button only exists on Android. In general, you should be able to use the PhoneGap universally on all platforms. But its good practice to test and run on each device to make sure it works they way you expect.
The sample project was developed fully in Visual Studio and tested with the Windows Phone 7 emulator. The 5 device hardware features that I will interact with using the PhoneGap API is shown on their own phone screen. The examples are very simple to explain how to use the PhoneGap API.
Below is a screen shot of the sample project’s Solution Explorer in Visual Studio. Notice the “www” folder. This folder is created with the PhoneGap project template and where all your web files (HTML, CSS, JavaScript, etc) exist.
Before we dive into the API code for each phone screen, I want to mention when using the PhoneGap API you should place your javascript code inside the javascript event OnDeviceReady. If you place your javascript code that calls the PhoneGap API in here, you can guarantee the device is loaded and ready to interact with. Below is the code included in the index.html file.
<script type="text/javascript">
document.addEventListener("deviceready", onDeviceReady, false);
// once the device ready event fires, you can safely do your thing!
function onDeviceReady()
{
}
</script>
Now lets dive into example code.
Device – Gather device specific information
The HTML and jQuery Mobile UI for the Device screen.
<body>
<div id="home" data-role="page">
<div data-role="header">
<h1>Device</h1>
<a href="#accelerometerpage" data-icon="add">Next</a>
</div>
<div data-role="content">
PhoneGap Device API
<!--<a href="#newpage" data-role="button">Second Page</a>
<br/>-->
<p id="devicename"></p>
<p id="devicephonegap"></p>
<p id="deviceplatform"></p>
<p id="deviceuuid"></p>
<p id="deviceversion"></p>
</div>
</div>
</body>
The jquery code inside onDeviceReady. The device object is from PhoneGap’s API and its value is added to the innerthtml for each #device element.
<script type="text/javascript">
document.addEventListener("deviceready", onDeviceReady, false);
// once the device ready event fires, you can safely do your thing!
function onDeviceReady()
{
console.log("onDeviceReady. You should see this message in Visual Studio's output window.");
$('#devicename').html(device.name);
$('#devicephonegap').html(device.phonegap);
$('#deviceplatform').html(device.platform);
$('#deviceuuid').html(device.uuid);
$('#deviceversion').html(device.version);
}
</script>
The HTML and jQuery Mobile UI for the Accelerometer screen.
<div id="accelerometerpage" data-role="page">
<div data-role="header">
<a href="#home" data-icon="back">Back</a>
<h1>Accelerometer</h1>
<a id="camerabutton" href="#camerapage" data-icon="add">Next</a>
</div>
<div data-role="content">
PhoneGap Accelerometer API
<p id="aX"></p>
<p id="aY"></p>
<p id="aZ"></p>
<p id="aTime"></p>
</div>
</div>
The jquery code inside onDeviceReady. The navigator object is from PhoneGap’s API. Here the navigator object calls the watchAcceleration method where the first input is the success callback method, the second parameter is the error callback method and the third parameter is the frequency in millisections the success callback method will fire.
var watchId = navigator.accelerometer.watchAcceleration(onAccelSuccess, onError, { frequency: 1000 });
function onAccelSuccess(a) {
$('#aX').html(a.x);
$('#aY').html(a.y);
$('#aZ').html(a.z);
$('#aTime').html(a.timestamp);
}
function onError() {
// TODO: write error logic
}
The HTML and jQuery Mobile UI for the Camera screen. Here we will write to the imageuri the fileURI of the image we capture. It will write out the location and filename of the image.
<div id="camerapage" data-role="page">
<div data-role="header">
<a href="#accelerometerpage" data-icon="back">Back</a>
<h1>Camera</h1>
<a href="#geolocationpage" data-icon="add">Next</a>
</div>
<div data-role="content">
PhoneGap Camera API
<p id="imageuri"></p>
</div>
</div>
The jquery code inside onDeviceReady. The navigator object calls camera then the getPicture method. The input parameters are similar to the Accelerometer except the third parameter where we define inline the quality, destinationType and Camera.DestinationType.FILE_URI. The file_uri that is returned in the success callback method will be added to the innerhtml at imageuri.
navigator.camera.getPicture(onCameraSuccess, onError, { quality: 50, destinationType: Camera.DestinationType.FILE_URI });
function onCameraSuccess(fileUri) {
$('#imageuri').html(fileUri);
}
The HTML and jQuery Mobile UI for the Geolocation screen. Similar to the Accelerometer screen, we will write the lat/lon values to the innerhtml.
<div id="geolocationpage" data-role="page">
<div data-role="header">
<a href="#camerapage" data-icon="back">Back</a>
<h1>Geolocation</h1>
<a href="#notificationpage" data-icon="add">Next</a>
</div>
<div data-role="content">
PhoneGap Geolocation API
<p id="lat"></p>
<p id="lon"></p>
</div>
</div>
The jquery code inside onDeviceReady. Here we’re calling the watchPosition of geolocation object and on the success callback method retrieving the lat and lon values.
navigator.geolocation.watchPosition(onGeolocationSuccess, onError, { frequency: 1000 });
function onGeolocationSuccess(p) {
$('#lat').html(p.coords.latitude);
$('#lon').html(p.coords.longitude);
}
The HTML and jQuery Mobile UI for the Geolocation screen. Here we created an anchor tag that will look like a mobile button that will display a PhoneGap notification alert.
<div id="notificationpage" data-role="page">
<div data-role="header">
<a href="#geolocationpage" data-icon="back">Back</a>
<h1>Notification</h1>
<a href="#storagepage" data-icon="add">Next</a>
</div>
<div data-role="content">
PhoneGap Notification API
<br/>
<a id="notificationbutton" href="" data-role="button">Click Me!</a>
</div>
</div>
The jquery code inside onDeviceReady. Here we use jquery to create a handler for notificationbutton that will call PhoneGap’s API object navigator.notification.alert. When the success callback method is reached it will update the innerhtml text of the button to Clicked.
$('#notificationbutton').click( function() {
navigator.notification.alert("You clicked me!", onNotificationSuccess, "Click", "Ok");
});
function onNotificationSuccess()
{
$('#notificationbutton').html('Clicked');
}
I hope this helps in getting started with PhoneGap’s API. There is a lot more that can be discussed.
Here is the code for the sample project.
Pingback: How to use PhoneGap API + iOS, Android | InterKnowlogy Blogs
Pingback: Using PhoneGap to Access Native iPad APIs | InterKnowlogy Blogs