JSON communication with the server
There are enough use cases (and they are becoming more) when you want to get data from the server and the most common data format nowadays for that is JSON, for various good reasons.
Let’s construct a simple form who’s data we want to submit to the server and know if it all went ok or not. For now we just print the submitted data on the django console (from where you started the local dev server) and we let the user know about the submission with the small text “Submitted” beside the submit button.
So let’s get started with the JavaScript side. Dojango luckily provides us with the basic infrastructure, so let’s create a template that extends dojango/base.html (it is available since the settings.py includes the app “dojango”, see here for instructions), that provides us with everything we need to have dojo running even the doctype of the document and HTML headers, just in short a valid HTML file, we only have to worry about our code.
So let’s build the simple.html file in the templates folder of our django app (I called my app “core”).

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{% extends "dojango/base.html" %}
 
{% block dojango_page_title %}Simple AJAX with dojango{% endblock %}
 
{% block dojango_header_extra %}
	<script type="text/javascript">
		function userFormSubmit(){
			var form = dojo.byId("userForm");
			dojo.xhrPost({url:form.action,
				handleAs: "json",
				content:{surname:form.surname.value,
					firstname:form.firstname.value
				},
				load:function(response, ioArgs){
					dojo.byId("info").innerHTML = "Submitted";
				}
			});
		}
	</script>
{% endblock %}
 
{% block dojango_content %}
	<form id="userForm" onsubmit="userFormSubmit(); return false;" action="/simple-ajax-set/">
		First name: <input id="firstname" /><br />
		Surname: <input id="surname" /><br />
		<input type="submit" value="Submit" /> <span id="info"></span>
	</form>
{% endblock %}

As you can see we are overriding a couple of blocks, that are defined in the dojango/base.html. The first one (line 3) is just for setting the page title, the second one (line 5) is for putting our JavaScript code inside html-head. And “dojango_content” (line 21) is finally the content of the body node.
We also have to wire up the template to render when we access http://localhost:8000/simple/ and the AJAX method, that we submit the data to, like so in the urls.py:

1
2
3
4
5
6
7
8

from django.conf.urls.defaults import *
 
urlpatterns = patterns('',
    (r'^dojango/', include('dojango.urls')),
 
    (r'^simple/', 'core.views.simple'),
    (r'^simple-ajax-set/', 'core.views.simple_ajax_set'),
)

We just added the two last lines that map our URLs (line 6 and 7) to the view functions.
Our views.py just needs to implement these two functions, like this.

1
2
3
4
5
6
7
8
9
10
11
12

from django.shortcuts import render_to_response
from dojango.decorators import json_response
 
def simple(request):
    return render_to_response('simple.html')
 
@json_response
def simple_ajax_set(request):
    firstname = request.POST['firstname']
    surname = request.POST['surname']
    print firstname, surname
    return {'success':True}

The function “simple” (line 4) uses the standard django way to render a view and return the content to the client. It finds the template simple.html in the app’s template path.
The function “simple_ajax_set” (line 8) will receive our form data and (for now) only print them. You can see the first speciality here, it uses the decorator “json_response” that we imported from dojango.decorators. This decorator takes care of returning proper JSON data, all the data you stuff in there are returned to the client JSON encoded, it basically is json_encode as described here. If you have AJAX calls and want to return JSON data, this is the easiest way to do it and it comes with dojango. It is a special (though very simple) implementation that has not made it’s way into the django core because it is really just AJAX-focused, while the django serializer is django model focused. Additionally this implementation solves a couple of problems and adds some features that are very useful when working with AJAX data, for more explainations see this article.

Handle the return
Now we can submit the form and see that the data got submitted. We don’t know yet if the data had been successfully handled on the server. So let’s add proper error handling.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

function userFormSubmit(){
	var form = dojo.byId("userForm");
	dojo.xhrPost({url:form.action,
		handleAs:"json",
		content:{surname:form.surname.value,
			firstname:form.firstname.value
		},
		load:function(response, ioArgs){
			if (response.success){
				dojo.byId("info").innerHTML = "Submitted successfully";
			} else {
				dojo.byId("info").innerHTML = "Error: "+response.error;
			}
		},
		error:function(data){ // This happens on a 500 error or alikes.
			dojo.byId("info").innerHTML = "Error sending data.";
		}
	});
}

If you looked into the return data (i.e. via FireBug) you might have seen that {"success":true} was returned. But until now this was passed into the load function (line 8) as a string, but we want them as JSON. So we have to tell the xhrPost() call to handle it as JSON (line 4). Now we can also evaluate the success value easily as shown in line 9. If the server returns success with the value false we know something went wrong on the server. Let’s implement on the server that the surname has to have at least three characters. In the case of an error the server returns the additional property “error” which we then show to the user (line 12) to inform him about the error.
The function in line 15 handles all kind of connection and/or submission errors that may occur in a lower level. Make sure to not leave your users in the dark about this.
Let’s look at the server code for that:

1
2
3
4
5
6
7
8
9
10
11
12
13

@expect_post_request
@json_response
def simple_ajax_set(request):
    ret = {}
    firstname = request.POST['firstname']
    surname = request.POST['surname']
    if len(surname)<3:
        ret['error'] = 'Surname is too short.'
        ret['success'] = False
    if ret['success']:
        # Store the data here
        pass
    return ret

We extended the function a little bit to do some simple error checking. You can see that we add the key “error” to the ret dict, which is then passed to the client if the surname was shorter than three characters. The JSON string returned in this case is {"success": false, "error": "Surname is too short."}.
Note that we didn’t explicitly set the value for success to True, the decorator json_response handles that for us. If no exception is thrown it assumes that the function went ok and it can return success=True. This comes in very handy, especially when you just have simple one task AJAX functions that i.e. just delete an item, you don’t have to return explicitly that the deletion went well, json_response does that for you if you throw no exception. We just made it the default behavior since it was right for most of our use cases.

A quick summary of the main features of dojango:

• a reusable django app that provides dojo
• easy dojo setup inside django
• build an optimized dojo
• some helper functions, i.e. JSON conversion
• switch easily between different dojo versions.

The main purpose of dojango is to help you using dojo within your django projects. Currently it delivers the main infrastructure to easily switch between several dojo versions and includes several functions that helps developing rich internet applications. Now we are able to chain dojo and django on a solid basis and we work at porting the actual django form widgets to use dojo widgets.

We would be happy, if a lot of people would test the current version and tell us about bugs, strange behaviors, misunderstandings, … Also we are open for everyone who would like to help out extending dojango. In coincidence Roberto Saccon (big thanks!) already testet dojango with google app engine and it worked at first go.

Of course we were also hacking some. We just can’t avoid it, we are all three involved in very much the same things, mainly dojo. Though everyone has his specialties. Some dojo addicts including Nikolai are currently finalizing the work on the layout and styling stuff, in order to make dojo 1.2 a great success and, as Alex Russell coined the main goal, to make it a better user experience. Tobi and I we were discussing a lot and coding less for getting out a first version of the dojo integration into django. Stay tuned on this blog, there will be a release very very soon (I am talking about days, less than a week for sure). After hacking all the code Tobi is mainly finishing up documentation and getting some first input from the outside in order to make even the first release a good release.

This year there are some conferences coming up that we want to attend. For the Ajax in Action we have applied for a couple of talks and hopefully will be able to give some, we are waiting on the feedback.
But the biggest thing this year will definitely be the Ajax Experience in Boston, which is kicked off by the Dojo Developer Day. If you are coming along, be sure to join us the Saturday before the conference, we just thought it might be funny to grab some german beer (and food) in Boston, just need to reserve it once we know how many we will be. This will be exciting, we are looking forward to meeting a lot of the people we know from various online communications and we will surely get a loooot of very interesting input, and hopefully we can also give back a little bit.

And those are just some of the things that are currently going on …