Making An App With PhoneGap & jQm Part I: A Simple HTML5 Skeleton 5

In this series, I will explain how I am using PhoneGap & jQuery.Mobile (on top of jQuery) to build an App for Android while being able to test it in my desktop browser. This is not an introduction on PhoneGap or jQuery.Mobile per se. I will not focus on Java and I won’t explain how to install PhoneGap or build the app from an IDE like Eclipse; you may need to read some other tutorial first to cover those points and then come back to this page when you can build your app from your IDE. Don’t worry too much though, you won’t need much knowledge of Java for I will expose some ways we can use to test the app in a desktop browser without the need to recompile it everytime we change something.

Now this is my first app, which means that most of the code I’ve put in so far required some trial-and-error for it to work. Hopefully you’ll find (parts of) this tutorial useful and you’ll be able to code your way faster than me!

Note: I wouldn’t dare pretending my code is perfect, and for the very same reason it’s my first app there are most certainly better ways of doing some things; if you have any question or remark concerning my code, please do not hesitate to leave a comment, that’s the best way for everyone to improve their skills.

Table of Contents

Here is how the tutorial is split:

Part I: A Simple HTML5 Skeleton
HTML5 basic structure, resources order, multiple pages and a menu with icons
Part II: Loading JavaScript The Right Way
JavaScript load order, jqm settings, App.init() & execution levels
Part III: A Stateless Authentication Layer
REST concepts, public/private tokens, some PHP server code
Part IV: ?
I’m not there yet!

Let’s Start With a (Very) Basic HTML5 Template


Here’s the basis for all the code we’ll put in index.html. As you probably know, the HTML, CSS & JS code we’ll write in /assets/www will be loaded and executed by a modern browser like Chrome for Mobile, which means we can use most of the HTML5 specification in a reliable way, without having to fix other browser’s edge-cases.

<!DOCTYPE HTML>
<html>
<head>
	<meta charset="utf-8" />
	<title>App</title>
	<meta name="viewport" content="width=device-width, initial-scale=1" />
	<script charset="utf-8" src="js/app.js"></script>
	<link rel="stylesheet" href="css/app.css" />
</head>
<body>
	<h1>Hello!</h1>
</body>
</html>

Not much to say so far, this is a bit plain but don’t worry we’ll soon add lots of stuff! Make sure the file loads correctly in your desktop browser as well as on your emulator, better make sure the basics work as expected before we add a bunch of complex stuff.

Note the reference to js/app.js which will contain as much of the app’s JS code as possible, and css/app.css which is the same with CSS

The <meta name="viewport" /> tag fixes a layout bug related to zooming, in some devices.

Now I know that I promised not to focus on Java, but if your app is not supposed to be displayed horizontally, know that you can prevent the screen rotation by adding this to AndroidManifest.xml, as a property of your main activity:

<activity ... android:screenOrientation="portrait">

How to Load Resources In The Right Order

Now let’s add some of the resources (JS & CSS) which we’ll use throughout our app. We need to add a bunch of JS libraries —PhoneGap, jQuery & jQuery.Mobile— and their corresponding stylesheets. Because all of those libraries are critical for the app to work as expected, they will have to be loaded in the <head> part of the file so that they load as soon as possible. We will see in the next part of this tutorial how to make sure everyone of them has loaded properly before doing stuff in JavaScript.

The load order is critical as well. You want to load PhoneGap (cordova-2.7.0.js) first because it’s a pretty big library which has a bunch of self-executing code in it, used to establish a link between the HTML page and the phone native code. Then we have jQuery (jquery-1.9.1.min.js) which in itself is pretty much just a library; we need it loaded before jQuery.Mobile (jquery-1.3.1.min.js) because the latter does also have a lot of self-executing code used to modify the DOM to make it more mobile-fashioned.

Note that I have reserved some space for plugins your app might want to use later on, like FacebookConnect or ToastNotifications, because those are the kind of plugins which would probably need to be loaded early.

As for the stylesheets, this is rather straight-forward: jQuery.Mobile, FontAwesome which I’ll use later on as icons throughout the app, and finally our own stylesheet.

<head>
	<meta charset="utf-8" />
	<title>App</title>
	<meta name="viewport" content="width=device-width, initial-scale=1" />
<!-- critical -->
	<!-- PhoneGap, jQuery, App, jQuery.Mobile -->
	<script charset="utf-8" src="js/cordova-2.7.0.js"></script>
	<script charset="utf-8" src="js/jquery-1.9.1.min.js"></script>
	<script charset="utf-8" src="js/app.js"></script>
	<script charset="utf-8" src="js/jquery.mobile-1.3.1.min.js"></script>
<!-- critical -->
<!-- plugins -->
<!-- plugins-->
<!-- themes -->
	<!-- jQuery Mobile, FontAwesome & App -->
	<link rel="stylesheet" href="css/jquery-mobile/jquery.mobile-1.3.1.min.css" />
	<link rel="stylesheet" href="css/font-awesome/css/font-awesome.min.css" />
	<link rel="stylesheet" href="css/app.css" />
<!-- /themes -->
</head>

jQuery.Mobile Page Structure

jQuery.Mobile allows us to integrate multiple activities into the same file, which is exactly what we’ll do in our app. For this to work, each page has to be built the following way:

<div data-role="page" id="ActivityFoo">
	<div data-role="header">
		<h1>Header</h1>
	</div>
	<div data-role="content">
		<h1>Content</h1>
	</div>
	<div date-role="footer">
		<h1>Footer</h1>
	</div>
</div>

Here’s how we’d integrate two activities into our index.html file :

<body>
	<div data-role="page" id="ActivityFoo">
		<div data-role="header">
			<h1>Header 1</h1>
			<div class="topmenu" data-role="controlgroup" data-type="horizontal">
				<a class="current-page-item" href="index.html#ActivityFoo" title="Foo" data-role="button"><i class="fontawesome icon-home"></i></a>
				<a href="index.html#ActivityBar" title="Bar" data-role="button"><i class="fontawesome icon-ticket"></i></a>
			</div>
		</div>
		<div data-role="content">
			<h1>Content 1</h1>
		</div>
		<div date-role="footer">
			<h1>Footer 1</h1>
		</div>
	</div>
	<div data-role="page" id="ActivityBar">
		<div data-role="header">
			<h1>Header 2</h1>
			<div class="topmenu" data-role="controlgroup" data-type="horizontal">
				<a href="index.html#ActivityFoo" title="Foo" data-role="button"><i class="fontawesome icon-home"></i></a>
				<a class="current-page-item" href="index.html#ActivityBar" title="Bar" data-role="button"><i class="fontawesome icon-ticket"></i></a>
		</div>
		<div data-role="content">
			<h1>Content 2</h1>
		</div>
		<div date-role="footer">
			<h1>Footer 2</h1>
		</div>
	</div>
</body>

… and so on. I have added the basis for a navigation menu, using icons from FontAwesome. Here’s the result:

A simple yet beautiful navigation menu using FontAwesome icons

A simple yet beautiful navigation menu using FontAwesome icons

The Final Code

<!DOCTYPE HTML>
<html>
<head>
	<meta charset="utf-8" />
	<title>App</title>
	<meta name="viewport" content="width=device-width, initial-scale=1" />
<!-- critical -->
	<!-- PhoneGap, jQuery, App, jQuery.Mobile -->
	<script charset="utf-8" src="js/cordova-2.7.0.js"></script>
	<script charset="utf-8" src="js/jquery-1.9.1.min.js"></script>
	<script charset="utf-8" src="js/app.js"></script>
	<script charset="utf-8" src="js/jquery.mobile-1.3.1.min.js"></script>
<!-- critical -->
<!-- plugins -->
<!-- plugins-->
<!-- themes -->
	<!-- jQuery Mobile, FontAwesome & App -->
	<link rel="stylesheet" href="css/jquery-mobile/jquery.mobile-1.3.1.min.css" />
	<link rel="stylesheet" href="css/font-awesome/css/font-awesome.min.css" />
	<link rel="stylesheet" href="css/app.css" />
<!-- /themes -->
</head>
<body>
	<div data-role="page" id="ActivityFoo">
		<div data-role="header">
			<h1>Header 1</h1>
			<div class="topmenu" data-role="controlgroup" data-type="horizontal">
				<a class="current-page-item" href="index.html#ActivityFoo" title="Foo" data-role="button"><i class="fontawesome icon-home"></i></a>
				<a href="index.html#ActivityBar" title="Bar" data-role="button"><i class="fontawesome icon-ticket"></i></a>
			</div>
		</div>
		<div data-role="content">
			<h1>Content 1</h1>
		</div>
		<div date-role="footer">
			<h1>Footer 1</h1>
		</div>
	</div>
	<div data-role="page" id="ActivityBar">
		<div data-role="header">
			<h1>Header 2</h1>
			<div class="topmenu" data-role="controlgroup" data-type="horizontal">
				<a href="index.html#ActivityFoo" title="Foo" data-role="button"><i class="fontawesome icon-home"></i></a>
				<a class="current-page-item" href="index.html#ActivityBar" title="Bar" data-role="button"><i class="fontawesome icon-ticket"></i></a>
		</div>
		<div data-role="content">
			<h1>Content 2</h1>
		</div>
		<div date-role="footer">
			<h1>Footer 2</h1>
		</div>
	</div>
</body>
</html>

Sorry if this first part was a bit slow, we’ll soon be looking at some more interesting stuff. Part 2 of this tutorial should be published within a few hours/days; in the mean time, happy coding! UPDATE: It’s online, check it out!

5 thoughts on “Making An App With PhoneGap & jQm Part I: A Simple HTML5 Skeleton

  1. Reply health blog Sep 6,2013 1:30 pm

    Does your site have a contact page? I’m having trouble locating it
    but, I’d like to send you an email. I’ve got some
    creative ideas for your blog you might be interested in hearing.
    Either way, great site and I look forward to seeing it improve over time.

  2. Pingback: adding authentication to the app | Leon's Final Year Project

  3. Reply vikis Aug 20,2014 11:07 am

    give your cordova-2.7.0.js. I’m getting Uncaught ReferenceError: require is not defined cordova.js:23 and Uncaught ReferenceError: module is not defined app.js:1 in chrome console. I got them from https://github.com/apache/cordova-js and http://appjs.com/

  4. Reply Alex Feb 25,2015 12:31 am

    Hi,
    Very nice tutorial – yet I must ask you if the complete source code is available for download somewhere (e.g GitHub or some other location) because even if I can see the final code for index.html, this is pretty useless or at least I cannot use it (as it won’t run properly) without files like app.js, app.css, icons.
    I know this is an old post, I’ve just came across it looking for some HTML5/CSS3 Cordova examples/templates/best practices.
    Thanks!

  5. Reply carce Mar 19,2015 9:02 pm

    Hi,
    The tutorial is great, but without the css I just see a mess. Is the code available any where?
    REgards

Leave a Reply