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.