Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
126 lines (89 sloc) 4.11 KB

Django Ajax Event

Goal

  • To make it easier to generate ajax requests, have Django respond with corresponding output, and react to this new data in your Javascript code.

How it Works

Note

jQuery is used for all the javascript code and namespaced events are utilized.

Django Ajax Event simplifies this process by formatting standard AjaxResponses (basically a wrapper around HttpResponse that guarantees JSON and formatting). On the client side, a piece of javascript code monitors incoming data for these specially formatted responses and makes sure to trigger the appropriate events.

Events facilitate a decentralized approach: whether it's an update to comments, or a shopping cart, or message - an event will be triggered and you can update the bits and pieces of your interface that need to worry about this new information rather than writing a large function that updates your shopping cart total, updates your shopping cart summary, flags products as 'being in your wishlist' all at the same time - each of these can be it's own widget, with it's own listener that listens for a ItemAddedToCart event.

See :ref:`json-sample`.

See :ref:`module-reference`.

Structure

An AjaxResponse consists of nested AjaxContent which has a type and a payload.

In javascript, a global DjangoListener instance triggers events based on the type and passes along the payload to any interested listeners. The goal being that you can create a set of decentralized widgets that respond to this data whether it's a notification, an update to a user's shopping cart, or a form validation response.

Sample JSON

The JSON generated by Django looks like this:

{
        "type" : "Response",
        "djangoPayload" : true,
        "payload" : [{
                "type" : "Message",
                "djangoPayload" : true,
                "payload" : "I can be a string, an array, an object. I can be an array of nested payloads too!"
        }, {
                "type" : "CartUpdate",
                "djangoPayload" : true,
                "payload" : { newQty: 5, product_id: 1, price: 250 }
        }]
}

Note

This would result in two events: Message.django and CartUpdate.django.

Example Javascript Code
// Append a message to a notification area.
jQuery(document).bind('Message.django', function(ajaxEvent){
        // <div id="notification_area"></div>
        // ajaxEvent.payload is an html string.
        jQuery('#notification_area').text(ajaxEvent.payload);
});

// Update a shopping cart.
jQuery(document).bind('CartUpdate.django', function(ajaxEvent){
        // <ul id="cart"><li id="product_id-1">Cool Product<span class="qty"></span></li></ul>
        // ajaxEvent.payload.newQty is an integer
        jQuery('#cart').find('#product_id-'+product_id).find('.qty').val(ajaxEvent.payload.newQty);
});

// You can bind multiple events to the same response.
jQuery(document).bind('CartUpdate.django',function(ajaxEvent){
        // <div id="total_value">$<span class="value"></span></div>
        // ajaxEvent.payload.value is an integer
        var value = parseInt(jQuery('#total_value .value').text());
        jQuery('#total_value .value').text(value);
});

Module Reference

Included Events

There is currently one custom :class:`AjaxEvent` subclass provided with the app. It can serve as an example of how to implement your own.

Warning

Only top level AjaxEvents result in events being triggered. Nested payloads aren't triggered automatically - it's up to your to control them.

:class:`AjaxMessage`

Indices and tables