9.3. A First Look at project.kid
Let's take a look at project.kid. This is certainly the longest bit of code we've seen so far, and there's lots of new stuff in here.
We'll take a multipass approach where we run through the whole template at rather high speed to get a lay of the land, and then we'll take a slightly deeper look at scripting the DOM, using lots of examples from this template and master.js and project.js, and then we'll circle back around a third time to look at how you can meld server calls with simple DOM manipulation to achieve that "dynamic Ajax-driven" website effect that everybody seems to want these days.
9.3.1. Laying the Groundwork for Our Project Page
The first thing you should see in the project.kid file is a <?python> tag:
<?python from whatwhat.model import STATUS_BEHIND_SCHEDULE from whatwhat.utils import textilize def get_display_notes(project, show_all_notes): if show_all_notes: return project.notes return project.recent_notes ?>
This should look familiar to you. The project.kid template starts out with a quick bit of Python that imports the textilize function (which we explored in Chapter 8, "RSS, Cookies, and Dynamic Views in WhatWhat Status"), and the behind-schedule status identifier. The get_display_notes function is new, but it should be pretty easy to see what it does. If the show_all_notes value is true, it returns a list of all the notes; otherwise, it returns just a list of recent notes.
As I write this there is a functional port of the scriptaculous visual effects libraries sitting in the trunk of MochiKit's subversion repository, so there is an extremely high probability that you won't have to import all of this into your projects. You can just use MochiKit's visual effects library.
And the head portion of our template is rounded out by a couple of links to the stylesheets that make things look nice on our page.
9.3.2. Using Ajax to Update Project Status and Descriptions
Right at the top of our template body, we see the project name, description, and project status edit box.
These are created with the following code from the template:
As you can see, the update_project function is called whenever the status is changed. This same function is called whenever the description or project contact is updated, so let's take a closer look at it now:
In this case, the callback function is update_project_callback, which takes the JSON that is returned by the server, evaluates it, and updates the description and contact content using the innerHTML method discussed in Chapter 8. This is kind of an interesting hybrid approach. We mentioned earlier in this chapter that you can return plain XHTML or JSON, but in this case the server is returning two XHTML fragments wrapped in a JSON object. This allows WhatWhat Status to update the contact and description elements in a single request.
If you are particularly quick, you'll notice that the project status is updated on the server, but the status is not changed in the browser after that update is done. And if you're really quick, you've already figured out why: The status box is updated by the user, before this function is called, and will already match what was sent to the server.
When that's all done, the contact and desc XHTML fragments are set up, and the whole dictionary is returned as a JSON object. The tg.expose(allow_json=True) declares that it is okay for this function to return JSON, if that's what you ask for. And the way you ask is to send in a parameter tg_format='json'. This alerts the controller that what you want back is a JSON object, and it uses Bob Ippolito's simple_json package to turn the resulting dictionary into a JSON object. On its own, simple_json can handle native Python types; but if you include other objects in your dictionary, this might not work automatically for you. TurboGears makes extending simple_json easy, and even includes a file for your custom serialize in its standard quickstart. In this case, however, everything is standard, and it is automatically serialized.
There's a lot more code in the WhatWhat Status project template, but you should be able to work your way through all of it on your own.