Making use of the device API is what makes PhoneGap so brilliant. What’s equally brilliant is how simple it is to integrate some of these functions within your app.

One of these functions is the native notification which can be used in place of, or in addition to, any error messages that you might need to display in your app.

• Sample iOS app project on GitHub

A basic jQuery data request that might require an error message

In my previous PhoneGap article I used an example of how one might load external data into an app. This article centered around jQuery’s ajax() request which, in its simplest form might look like so:

$.ajax({
	url: 'http://your-site.com/your-resource.php',
	dataType: 'jsonp',
	success: function(data, status){
		//handle your data
	}
});

This would attempt to load some data and then execute some code. There is no provision to handle an error, however.

Using the error callback setting to handle any errors

jQuery’s ajax() request can have an additional setting, just like the success handler, to deal with any error’s that might crop up.

$.ajax({
	url: 'http://your-site.com/your-resource.php',
	dataType: 'jsonp',
	jsonp: 'jsoncallback',
	timeout: 5000,
	success: function(data, status){
		//handle your data
	},
	error: function(){
	   //handle your error
	}
});

Just like with the success handler this ajax() request will now run some code if an error is encountered. Magic.

Creating a basic error handler

Using a couple of techniques it’s easy to communicate if and when an error occurs:

$.ajax({
	url: 'http://your-site.com/your-resource.php',
	dataType: 'jsonp',
	jsonp: 'jsoncallback',
	timeout: 5000,
	success: function(data, status){
		//handle your data
	},
	error: function(){
		$('#response').text('There was an error loading the data.');
		alert('There was an error loading the data');
	}
});

Lines 9-12: here I am adding an error message to an element within the document and also using a bog standard Javascript alert dialog to show the same message.

While this is sufficient at communicating to the user that an error was encountered, it also communicates something else; the fact that they’re using a web app, as identified by the rather unsightly ‘index.html‘ title of the error notification.

Using PhoneGap native notification alerts to handle errors more elegantly

PhoneGap native notification alerts can easily be used in your app. The anatomy of a notification alert function is as follows:

navigator.notification.alert(
	'Your message',
	yourCallback,
	'Your title',
	'Your dismiss button title'
);

It’s pretty self-explanatory. The alert has four arguments; the message that you want to display within the dialog, a callback function to act on the notification, a title and a button label.

Using a native notification alert in its simplest form would involve something like this:

$.ajax({
	url: 'http://your-site.com/your-resource.php',
	dataType: 'jsonp',
	jsonp: 'jsoncallback',
	timeout: 5000,
	success: function(data, status){
		//handle your data
	},
	error: function(){
		navigator.notification.alert(
			'Something went wrong...',
			null,
			'Error',
			'Done'
		);
	}
});

Note that I do not have a suitable callback function (yet), so I have passed an argument of null for the time being.

This yields a much more acceptable notification alert.

Using a native confirmation notification

This can be taken a step further so that the notification dialog displays two buttons, rather than a single button that dismisses the message. To do this we need to use a confirmation notification instead of the normal alert notification. The arguments for this notification are almost the same, bar the button label where now two values can be passed – separated by a comma. Like so:

navigator.notification.confirm(
	'Your message',
	yourCallback,
	'Your title',
	'Button one label,Button two label'
);

This makes the confirmation notification perfect for use with a data request. If there is an error we can inform the user with a native notification message and allow them to dismiss it or try loading the data again, depending on which button they choose to press.

Creating a callback function

For the purpose of this article I’ve just created a really simple callback function:

function yourCallback(button) {
	if (button == 2) {
		dataRequest();
	}
}

This function takes the button index as an argument and depending on which button was pressed (in my case, the second button) will attempt to load the data again, by calling the necessary function.

Putting it all together

Using the same code example as in my previous article, that covers loading data into a PhoneGap app, I can add the callback function and native confirmation notification to handle any errors with the data request:

$(document).ready(function(){
	$(document).bind('deviceready', function(){
		onDeviceReady();
	});
	
	function yourCallback(button) {
		if (button == 2) {
			dataRequest();
		}
	}
	
	function dataRequest() {
		var output = $('#output').text('Loading data...');

		$.ajax({
			url: 'http://samcroft.co.uk/demos/updated-load-data-into-phonegap/landmarks.php',
			dataType: 'jsonp',
			jsonp: 'jsoncallback',
			timeout: 5000,
			success: function(data, status){
				output.empty();
				
				$.each(data, function(i,item){ 
					var landmark = '<h1>'+item.name+'</h1>'
					+ '<p>'+item.latitude+'<br>'
					+ item.longitude+'</p>';

					output.append(landmark);
				});
			},
			error: function(){
				output.text('There was an error loading the data.');
				navigator.notification.confirm(
					'Something went wrong. Would you like to retry?',
					yourCallback,
					'Error',
					'No,Yes'
				);
			}
		});
	}
	
	dataRequest();
});

Note: the error handler is invoked because I have not added my domain to the server whitelist ExternalHosts within the Cordova.plist.

The result is a native confirmation notification that gives the user an option of retrying the data request.

• Sample iOS app project on GitHub