Skip to main content

A template-block-based Django helper for jQuery-PJAX.

Project description

Overview of DjPj (formerly Django-PJAX-Blocks)

DjPj is a simple, flexible way to add PJAX support to your Django project and
deliver a faster browsing experience to users of your website.

If you don't know what PJAX is, `read about how it works`__ below. In a
nutshell, it makes navigating between pages on your website faster by loading
only the part of the page that needs to change, rather than the whole thing.
It's is a well-established technique; if you're reading this on GitHub, you
probably loaded this content via PJAX.


In a nutshell, your DjPj-enabled website will respond to PJAX requests with
the contents of a single template block of your choosing. It requires no
changes to your views, which means it's easy to add PJAX support to
third-party Django apps.

Getting started

PJAX requires cooperation between your front end (the Javascript that runs in
your visitors' web browsers) and your Django back end.

1. Set up the front end with jquery-pjax

The front end is handled by the jquery-pjax library, so first of all, read about
`how to use jQuery-PJAX`__ and pick one of the techniques there.


2. Install DjPj on your server

First, make sure the views you're PJAXing return TemplateResponse__. DjPj works
by changing the way your templates are rendered, so it doesn't work with
pre-rendered ``HttpResponse``s.


Install DjPj from PyPI::

> pip install djpj

3. Start using PJAX - basic usage examples

Imagine you have a template, ``blog_post.html`` that looks like this::

<title>{{ blog_post_title }}</title>


<div id="blog_post">
{% block blog_post %}
{% endblock %}

Respond to PJAX requests to ``blog_post_view`` with the contents of the
"blog_post" template block::

def blog_post_view(request, ...)
return TemplateResponse(request, "blog_post.html", context)

If you want PJAX to correctly update the title of your page, include a
``title_block`` or ``title_variable`` argument to ``pjax_block``::

@pjax_block("blog_post", title_variable="blog_post_title")
def blog_post_view(request, ...)

The "container" in PJAX parlance is the HTML element the contains the content
you want to swap out. In the example above, the name of the block is the same
as the id of the container element - they're both "blog_post". In these cases
you can just omit the first argument entirely, and DjPj will look for a block
whose name is the same as the container's id::

def blog_post_view(request, ...)

Use DjPj's middleware to enable PJAX without modifying your views

If your site uses third-party views that you can't modify - for example, views
defined by an ecommerce or CMS package - you can use DjPj's middleware instead
of decorating views directly. This can also be handy when you have a number of
views that you want to PJAXify which all share a common URL pattern.

Here's what it looks like::

# DjangoPJAXMiddleware should appear last in MIDDLEWARE_CLASSES

('^/blog/', '@pjax_block("blog_post", title_variable="blog_post_title")'),

Each entry in ``DJPJ_PJAX_URLS`` is a 2-tuple with the first element a regular
expression matching the URLs you want to PJAXify, and the second a string
containing Python code defining the decorator, just as it would be done in

Using a different template for PJAX requests

You can also use a specific template for PJAX requests, instead of returning a
specific block. To do this, use the ``pjax_template`` decorator, and pass your
PJAX template's name as the first argument::

from djpj import pjax_template

def my_view(request)
context = {"post_title": "My First Blog Post", ...}
return TemplateResponse(request, "template.html", context)

Your template should include a ``<title>`` tag if you want the title to be
updated in the user's web browser.

Customising the behaviour of DjPj

You can customise how DjPj selects blocks and templates by supplying your own
functions to the ``pjax_block`` and ``pjax_template`` decorators. `Read more
about that on GitHub.`__


How does PJAX work?

Normally, when you click a link, your browser has to set up everything from
scratch: HTML has to be parsed, scripts have to be compiled and executed,
stylesheets interpreted and applied. It's a lot of work, and when you're
browsing between different pages on the same website, much of this work is
duplicated. It's like heating up a new skillet for every pancake.

When a user clicks a link on your PJAX-enabled website, the server sends only
the content that needs to change to display the new page. The fresh dollop of
content drops into place in your page, and the browser doesn't have to do all
the work associated with a full page load. To complete the trick, we manipulate
the browser history to make the back and forward buttons work normally.


DjPj relies on defunkt's `jquery-pjax`__ – the canonical
client-side PJAX library and the same one used by GitHub.


DjPj was originally adapted from Jacob Kaplan-Moss' `Django-PJAX`__.


Python and Django compatibility

This package is tested in Django 1.4+ and Python 2.6, 2.7, 3.3+ and PyPy.


Tests are run using nose. To install::

pip install nose

And to run the tests::


Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
DjPj-0.3.1-py2.py3-none-any.whl (14.0 kB) Copy SHA256 hash SHA256 Wheel py2.py3
DjPj-0.3.1.tar.gz (13.3 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page