Dmitri Lebedev, 2011

This is a middleware that allows your to render only parts of the site pages and send them as JSON object to the client.

It allows you to:

  • update any parts of the pages when needed
  • start using history PushState without changing the views

If GET arguments have partial parameter with names of blocks, the middleware will extract them from the page and send to the client as a JSON string with names as keys:

  • request: &partial=block1,block2
  • response: {'block1': '...', 'block2': '...'}

Use a special template tag to delay HTML loading:

{% delayed_block big_table %}
    Real content. It will be loaded by Javascript at document.ready event.
{% delayed_stub %}
    Stub content that is rendered immediately.
{% enddelayed_block %}

The real delayed content is rendered only if it is requested directly in the partial GET parameter.

Use middleware.set_js_data to set variables that will be available in Javascript both in a normal page and in a partial JSON response.

The Javascript module in example/media/js/partial.js does this and some more interesting things. Run the Django project in example to see all the features.


Check out a sample Django project in the source code. Here is a very basic usage example, assuming you use jQuery on the client:


    <head><title>{% block title %}My site{% endblock %}</title></head>
        <div id="menu">{% block menu %}{% endblock %}</div>
        <div id="content">{% block content %}...{% endblock %}</div>


{% extends "base.html" %}
{% block title %}{{ some_object.title }}{% endblock %}
{% block content %}{{ some_object.content }}{% endblock %}

Assume, the page with doc1.html was already loaded on the client. To update it, we run this jQuery code:

    url: window.location.href,
    data: {partial: 'content,title'},
    success: function(json, status, xhr) {
    dataType: 'json'

will send a GET request to page.url?partial=content,title and receive a JSON string:

{'content': '...', 'title': '...'}


Use pip or easy_install to install the package:

$ pip install django-partial-page

or clone this repository to get the latest revision:

$ hg clone ssh://


  • Django 1.x (tested on 1.3, but should work in 1.2 too)
  • Threading (threading.local instance to save the rendered blocks)


You may need to change the name of the GET parameter if it collides with the names you already use. Set settings.PARTIAL_PARAM_NAME to the string you need.


This middleware captures the output of BlockNode.render(), so in a partial response, all the changes to response.content string will be ignored. If you need to manipulate the HTML output, try using template tags instead.


This software is in public domain