Using jQuery Mobile With Django HTML5 Boilerplate

In the last article, I introduced the Django HTML5 Boilerplate package, which incorporates HTML5 Boilerplate into an easy to use Django package. Today’s article will take that one step further by showing how to use DH5BP to create a base template for your HTML 5 mobile app. We will be using jQuery mobile and the jQuery Widget for Showing Add To Home Message on iOS.

Getting ready

Install Django HTML5 Boilerplate into your virtual environment:

pip install django-html5-boilerplate

Download the Add to Home Message JavaScript to your Django static files.

How do it…

All examples explained below are available as a gist.

Create a mobile base file (iOSAndjQueryMobileBase.html) to extend within your application:

{% extends 'dh5bp/base_script_in_head.html' %}
{% load staticfiles %}
{% load url from future %}
{% block title %}{APP_TITLE}{% endblock %}
{% block head %}
{% endblock %}
{% block pre_main_script %}
{% endblock %}
{% block post_main_script %}
{% endblock %}

Create a new template to display a page (mobileSite.html):

{% extends 'iOSAndjQueryMobileBase.html' %}
{% load url from future %}
{% load staticfiles %}
{% block head %}
    {% put styles here %}
{% endblock %}
{% block content %}

Page Title

Page content goes here.

Page Footer

{% endblock %}

Remember to reference this template in one of your views.

Lastly, create a js/main.js in your static files:

(function() {

  $('#page1').on('pageinit', function() {
    // put your logic for handling page1 here

How it works…

The iOSAndjQueryMobileBase.html template (name it whatever you like) extends the special DH5BP template dh5bp/base_script_in_head.html, which I recently introduced for mobile applications. It is the same as dh5bp/base.html, except the script tags are loaded before body is rendered, instead of after. This is important for libraries like jQuery mobile that hijack the DOM and do a lot of manipulation as the page is being rendered. Mainly, the template adds a common page title, the apple meta properties for making your HTML 5 app look native, some icon links (you will need to create these), and references to the jQuery mobile CSS & JS. It does not introduce any new blocks.

In your mobileSite.html template (name it whatever you like), we extend the iOSAndjQueryMobileBase.html template, implementing the head and content blocks. The head head block may not be necessary, if all your CSS is included in the parent template, but it illustrates how you could add page specific styles (or other stuff that belongs in head). The content block shows how to add markup, and contains an example of jQuery Mobile markup. Please read their documentation for more examples and information.

By putting jQuery Mobile in the header, it will hijack the DOM and fire its events as the page renders. It is important to make sure that jQuery Mobile is loaded after your JavaScript file, or important events like pageinit won’t fire as expected. We put jQuery Mobile in the head to prevent the page from looking different before jQuery hijacks the DOM.

The main.js file is where the logic for your mobile application goes. It first shows the Add to Home message, if necessary, before attaching all the jQuery Mobile page listeners. Inside the pageinit callback it is safe to reference and attach events to elements in that page using regular jQuery. In jQuery Mobile a page refers to an element with data-role="page", not the HTML document, so you can have many pages in one HTML document or pull other pages in using AJAX.

You will definitely want to read the documentation on jQuery Mobile to learn how to mark it up and interact with it via JavaScript. It is really powerful, but somewhat confusing at first.

There’s more…

As I have several mobile project in production, rather than copy this pattern into each project, I have created a package that contains the iOSAndjQueryMobileBase.html for reuse on my own projects. Please include it in your own projects, if you find it useful:

pip install django-html5-mobile-boilerplate

The documentation to use it is available at Django HTML5 Mobile Boilerplate on Github.

Django HTML5 Boilerplate

I am a big fan of the HTML 5 Boilerplate project, and in that past, I have made some half-hearted attempts to incorporate it into a reusable Django module. I think the problem with my attempts and the other attempts that I have found recently on the web is that nobody automated the process of converting H5BP into a django module, so each time H5BP is updated (which happens frequently), somebody has to ...

Using PhantomCSS for Regression Testing Your CSS

I finally had a chance to play with PhantomCSS, a CSS regression testing tool that compares screenshots to see if CSS changes have affected the design, and wanted to share my experience with you. We are using it at Ariba to validate that I do not break any designs as I migrate us from two giant, unmanageable CSS files into smaller, modularize and better written lessCSS files. PhantomCSS uses

jQuery Widget for Showing Add To Home Message on iOS

I recently wrote an article discussing Making HTML5 Apps Appear Native on iOS where I mentioned building a widget for telling the users to add your application to the home screen. This article introduces a simple jQuery plugin that can be used to show the Add to Home message on an iOS device. It is fully customizable, but looks good right out of the box.

Getting ready

Download the plugin at the

Rotating Multi-State Button

One of the designers at Ariba, recently came up with a design that needed a tri-state button to govern toggling some content. We came up with an interesting solution where the button has three colors on the outside, with the bottom color governing the content being shown. I am not sure if the widget will survive a usability study, but I put together a proof of concept using HTML 5 technologies and wanted to share ...

Python Script for Automatically Copying Modified Files

I had a situation at work where I needed to copy static resources from one directory to another, any time they changed. A simple symlink wouldn’t do, because the destination location was on a shared drive, and not all users would have access to my machine. Although, there are existing solutions for this problem, it seemed a simple enough problem to write my own python script. Today’s article will describe my python script for monitoring ...

Making HTML5 Apps Appear Native on iOS

In version 6 of iOS, Apple added a simple, but powerful new feature allowing HTML5 webpages, saved to the home screen, to look like native apps. One of the best apps doing this right now is weather app (try opening it on your iOS device). Today’s article describes how you can make your HTML5 apps look native when they are saved on and opened from the home screen.

How do it…


Bash Profile Tips & Tricks & Conditional Sourcing

One trick I like to use, since I develop on multiple computers, is to define my .bash_profile in a shared place (such as Dropbox), and setup a symlink to it on the each of my computers. This works great, even when I have slightly different configurations for each computer, because my configuration only lives in one place and I conditionally target each class of computer. Today’s article describes some of my tips and ...

Variable Hoisting in JavaScript

The JavaScript Variable Scope article covered the basics of variable scope in JavaScript. Today I’d like to continue that discussion, exploring a more complicated concept called hoisting, where the names of variables declared inside of a function are hoisted to the front of the function, so that they may be accessed, even before they are defined.

How do it…

Here is a simple example of hoisting:
 function foo() { alert(a); var ...

JavaScript Variable Scope

JavaScript scopes variables in a unique way that often confuses developers coming from other languages. First, as discussed in the Context Binding Functions article, the this keyword is dynamic, and second, as we᾿ll discuss today, variable scopes change depending on how you declare them.

How do it…

The most basic way to declare a variable is:
 var foo1 = 'bar'; 
The variable foo1 will be added to the current execution ...