Dispatching AJAX requests with Drupal and JSON

1 :: Heed MENU_CALLBACK!

One of the frequently overlooked capabilities of Drupal is the so-called MENU_CALLBACK. Strangely, this straightforward menu-item type is among the unpopular ones. MENU_CALLBACK is simple. It only indicates that your defined path will be wired to some callback function in your module. Let’s see how this works:

The above snippet maps the path website.com/json/dispatcher to the function mymodule_dispatcher(). Everything that comes after the path will be passed into the function as parameters. For example if we used this URL: website.com/json/dispatcher/hello/world, and defined the function like this: function mymodule_dispatcher($var1, $var2) – then in the function $var1 would equal ‘hello’, and $var2 → ‘world’ respectively. This callback functionality is exactly what we need to create an AJAX+JSON event dispatcher.

2 :: Possibilities with callback function.

The trick to writing callback functions ( mymodule_dispatcher() in our case ) is in knowing the Drupal’s framework. Commonly, Drupal is considered to be a CMS (Content Management System). Only when looking deeper, one would uncover the well-designed, powerful framework which makes all the surface functionality possible. If Drupal was a bicycle factory, and you were an engineer working on imroving the bicycles – you would be allowed to redirect the product into your own conveyer belt at any points during production. You could let the factory build the bicycle frame, then redirect it to your own conveyer belt to make your additions/alterations, after which you could let it back into regular production.

Alright, I’m getting a little ahead of myself there. In our module we will talk back to the client using drupal_to_js() function. This function accepts either an associative array or an object, and returns well-cooked JSON.

This snippet would output valid JSON, which is easily parsable by javascript.

3 :: Designing our dispatcher.

Dispatcher is there to dispatch. Let’s follow the KISS principle and use PHP’s switch() control statement.

With this simple dispatcher we can accept any URL such as website.com/json/dispatcher/[anything], and most importantly, nobody stops us from POSTing values into that URL. This means we can use Drupal’s framework, and talk directly to client (bypassing theming). Javascript developer would only have to post values to your dispatcher, and work with returned JSON. Lets expand the function a little bit, using the login/register example.

As you can see – in the above example I used such Drupal framework’s functions as drupal_execute(), form_get_errors(), user_authenticate(), and drupal_get_messages(). It shows once again that the hardest part about writing callbacks is in knowing which Drupal’s functions to use to achieve the desired effect (without reinventing the bicycle).

4 :: Client Side

The only thing left here is for js developer to create forms with the expected fields. They would then ajax-submit them to our json/dispatcher/register, json/dispatcher/login, or json/dispatcher/logout, and receive the JSON response back from server, which they would then parse and use for any presentational purposes.