unfoldthat.com

Quick, simple and arguably proper Ajax (without touching server-side)

My beliefs

First of all, I’d like to clarify things a little bit. I have some axioms, beliefs and biases about how Ajax should work. They aren’t the theme of the post, it’s just a declaration: in this particular blog post, when I say “right” I mean “according to these idiosyncratic points”, however really right they are:

1. If I disable Javascript on the page, the page should still behave well: forms can be submitted, comments are being posted, et cetera. (It is probably called graceful degradation.)
2. GET is not ever used for not-idempotent requests. If I want to create something¹, I send POST^{2 3}. If I want to load something without changing anything on the server, I use GET. (This is probably a RESTful way, but I don’t swear it is.)
3. To make a POST request, you should have a form and just send it. If you don’t have a form, you’re probably breaking the first rule. If you have a form, but for some reason still collecting parameters by hand in Javascript, you’re acting strange.
4. To make a GET request, you can have a link (<a href=...>). If you’re using links for something like POST requests, I loathe you. But you can also send a form with GET, because it can be useful, for example, for filtering things.

Don’t touch server-side

I don’t like changing my beautiful server-side code for some ajaxy stuff. Yeah, sometimes it’s necessary, so I just get over it and do that’s necessary. But it’s not always necessary.

For example, let’s assume you have some fragment on a page, and you’d like to allow user to refresh it using ajax (for whatever reason). You can add a check for ajax to your server-side code, add a couple of ifs and duplicate code a lot.⁴ But why? Your app can just ask server for the full next page, extract actual content from it and insert it into the current page. (There can be performance concerns if loading the full page eats too much resources on your server and your website is really popular. Poor you.)

This is simple

And however frightening it may sound, sending GET requests for a portion of a page is really simple. For example, if you’re using jQuery, you can do:

<a href="/my_page/" class="ajaxed_refresh">Refresh!</a>

<div id="page">
  <div class="content">      
    <ul>
      <li>Thing 1</li>
      <li>Another thing</li>
      <li>And the third one</li>
    </ul>        
  </div>
</div>

<script>
function set_refresh_callback() {

  $('.ajaxed_refresh').click(function(e) {
    e.preventDefault();
  
    var page_url = $(this).attr('href');
    $('#page').load(page_url + ' div.content');

    return false;        
  });
}

$(document).ready(set_refresh_callback);
  
</script>

What’s happening here?

1. We show a page and a link. The link is a normal HTML link. If user clicks on your link, the standard “click-the-link” behavior is expected: the page will be loaded again. Without JS, everything is as expected.
2. In our javascript, we override this behavior. We prevent the default one, so user won’t leave the page.
3. We get the url which should be loaded. It’s in the “href” tag of the link, so we’re not repeating ourselves.
4. We call jQuery().load() method with parameter page_url + ' div.content'. For example, if url is /my_page/, the parameter will be "/my_page/ div.content". jQuery will understand it as “load /my_page/, extract element div.content from it and place it into the #page element”.

Yes, that simple. jQuery().load() seems awesome at first. As an exercise, add a link to this page which loads another page in ajaxy way. This can be done without any new javascript code.

.load() with POST

As I said, POST is the way to create things. If you want to show form, send it with AJAX and replace some part of your page with the result, it’s still simple.

My usual pattern on the server-side is to receive a POST request and return the page with a form again with errors, if there were any, or, if not, return a 303⁵ redirect. It’s called “Post/Redirect/Get” and it is a really good way to create things on web.⁶

jQuery().load() receive a second parameter - form data. If it’s present, the request is sent as POST request. So the only thing we should do is to convert all the form data into the JS dict.

You won’t believe it, but there is no method in jQuery to convert form data into the dict. You can convert it to the QueryString ("a=1&b=2"), or to some really weird data structure ([{ name: 'a', value: 1 }, { name: 'b', value: 2 }]), but not to the dict ({ a: 1, b: 2 }. On the other hand, to send .load() as POST, one have to pass data parameter in the last format. Crazy, huh?

I have a simple function for you to serialize forms in a useful way:

function serialize_form(form) {
    var params = {};
    
    $.each(form.serializeArray(),
           function(k, v) {
               params[v.name] = v.value;
           });

    return params;
}

Now the task is simple:

<div id="page">
  <form action="/create_thingy/" method="post" class="ajaxed_form">
    <input name="title">
    <input type="submit">
  </form>
</div>

<script>
function set_form_callback() {

  $('.ajaxed_form').submit(function(e) {
    e.preventDefault();
  
    var action = $(this).attr('action');
    $('#page').load(action + ' div.content', serialize_form( $(this) ));

    return false;        
  });
}

$(document).ready(set_form_callback);
  
</script>

The actual <form> is untouched, and it works with and without javascript. Wonderful!

But .load() is too stupid

Let’s try to write an awesome paginator with our new-learned trick.

<div id="page">
  <div class="content">
    <ul>
      <li>Blog post one</li>
      <li>Another blog post</li>
      <li>Last blog post on the page</li>
    </ul>
  </div>
  <div class="paginator">
    <a href="/page/2/">Next page</a>
  </div>      
</div>

We again want to just .load() a new page into something. But into what exactly should we load it?

• If we load .content into #page, it will replace content, not append it!
• If we load .content into .content, it will replace content and create a strange hierarchy: <div id="age"><div class="content"><div class="content">...
• If we load something into .paginator, nothing will be gone, but hierarchy will still be strange.

For some reason which I can’t understand at all, jQuery function can’t do an appending load(). So we’ll have to do it by hand.

What we’re going to do is to get the page contents into the varialbe, extract everything we need and append it into the right places:

<script>
function set_paginator_callback() {
    $('a.paginator').click(function() {
        var href = $(this).attr('href');
        var content = $.get(href, function (data) {
        
            var resp = $(data)

            resp.find('.content ul li').appendTo( $('.content ul') );
            resp.find('.paginator').replaceAll( $('.paginator') );

            set_paginator_callback();
        });
    });
};

$(document).ready(set_paginator_callback);
</script>

We’re loading the page, extracting needed element, placing them into the current page and resetting callbacks (don’t forget to do it!). Yay!

Cool story bro

The approach discussed there works with popular frameworks (for example, you don’t have to change Django’s generated forms at all), can update lots of elements, simple, generic, idiomatic, error-prone with malformed pages and inline javascripts and a little bit rude to your server.

There is no problem to catch errors, set callbacks, et cetera, but please figure it out on your own.

You don’t have to use it and it’s definitely not the only one way. But it gets things done, and I like it.

28th of August, 2011

Please send your comments, ideas, rants and job offers at v.golev@gmail.com.

Made with Nginx, Jekyll, Git, EC2 and Emacs.