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

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

Cross Browser and Legacy Supported RequestFrameAnimation

There is an awesome new feature in HTML 5, window.requestAnimationFrame, which tells the browser that you wish to perform an animation and requests that the browser schedule a repaint of the window for the next animation frame1. This allows you to do animations more efficiently and without using setInterval or series of setTimeout function(s). I have created a Demo that attempts to use the browser’s requestAnimationFrame side-by-side with the legacy polyfill executing.

Article ...

Legacy Support for HTML 5 Forms

As discussed in the article, HTML 5 Feature Detection Using Modernizr, HTML 5 contains many new input types and attributes. While, most new browsers support them (although often imperfectly), the majority of people still use browsers that do not. However, we can use JavaScript to provided legacy support for the new HTML 5 input attributes and types in browsers that lack support. Toadys article introduces a widget for the YUI 3 gallery, that emulates ...

HTML 5 Feature Detection Using Modernizr

HTML 5 is probably the most exciting improvement to come to the web, since the popularization of AJAX. However, as shown by last weeks article (HTML 5 Forms), only the most cutting edge browsers support many of the new HTML 5 features. To progressively enhance a site for HTML 5 enabled browsers, developers need a way to detect if the browser supports a desired HTML 5 feature. Enter Modernizr by Faruk Ates ...

HTML 5 Forms

HTML 5 is quickly gaining in popularity and is appearing more frequently across the web. While you may hear about the awesomeness of HTML5s new JavaScript and CSS features, the actual HTML improves are often missed. Lets look at the thirteen new form field types and some of the more useful new form field attributes. Not all browsers support HTML 5 forms yet, and those that dont will render the new input types as text ...

Introducing Web Workers

The HTML 5 specification introduces a new technology called Web Workers, allowing developers to spawn new threads for processing JavaScript code. This is a major improvement from the current state of the web, as it allows JavaScript code to execute outside of the UI thread, so your application is still responsive during long-running scripts. However, due to the nature of Web Workers there are restrictions to what they can and cant do, and how to ...