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 ...

Encrypting Settings Files

When I was developing for Votizen, I always felt uneasy that we had our settings files with many important passwords and auth keys stored unencrypted on a third-party service. Sure, SSL was used for fetching and committing code, and only a few SSH public keys were allowed access to our repository, but it is one more opportunity for your site to be hacked. I recently read John Resig’s post Keeping Passwords in Source ...

Django Template Tags for JavaScript Deferment

I have been slowly working to improve my Django Shared project, which I use as the basis for all my Django projects. Recently, I added several new templatetags for deferring content and scripts: async_script, defer_html, defer_script, and render_deferred_html. Today’s article will cover how to use these templatetags in your own projects.

Getting ready

You will need to include django-shared in your own project, or extract the parts from templatetags/ If you use pip, ...

Django Foreign Key Object Patcher

This article may be helpful for optimizing query performance when fetching foreign key objects in Django on large tables. Most of the time using the select_related queryset function is enough to group the population of foreign key objects into the original query. However, if you are using a relational database and the tables used in select_related become sufficiently large (1m+ rows), then select_related will begin to perform very poorly. Today, we will discuss a generic ...

Using Celery to Handle Asynchronous Processes

This article continues the series on building a continuous deployment environment using Python and Django.

Those of you following along, now have the tools to setup a Python/Django project, fully test it, and deploy it. Today we will be discussing the Celery package, ...

Coverage and Mock

This article continues the series on building a continuous deployment environment using Python and Django.

So far we have covered the basics of setting up a Django project and testing it. Today we will discuss how to ensure your tests fully cover the ...

Testing and Django

This article continues last weeks series on building a continuous deployment environment using Python and Django.

Before we discuss testing in Django, lets define what makes up good testing infrastructure. There are many schools of thoughts on testing, but that's another article. Ignoring ...

Tips for Starting Your First Django Project

This Thursday, May 26 2011, I will be speaking on a Continous Deployment panel for Wealthfront & IMVU in downtown Palo Alto. In preparation for the talk, I thought I'd start a series explaining how easy it is to do continous deployment in Python/Django. Unfortunately, writing this first article took me two weeks, so the rest of the articles will be released after the panel. Over the next couple weeks, we will be discussing ...