One of the great ‘new’ features of Drupal 7 is the ability to use AJAX commands outside of FORM API allowing back-end and front-end developers to leverage high performance and solid JSON responses. JSON AJAX commands can be used simply and solidly in Drupal 7 to update blocks, nodes, pages and basically any element of a page with better performance on the client and server-side then loading AHAH page fragments.
In this tutorial we’re going to create a simple and lightweight module that loads some content into a predefined page. Creating a module is pretty simple stuff but if you get lost, check out my Super simple custom module tutorial.
From the beginning: hook_menu and nojs
Start by creating a custom module and enabling it. Happy days. The next step is to go ahead and define three new menu paths in hook_menu which will be:
- The JSON response that sends the commands to the core drupal.ajax library that ends in /ajax.
Right, so hook_menu tells Drupal which function names to call when each path is accessed using the ‘callback’ parameter but we still need to define those functions in our module so that Drupal has something to run. This is where the magic happens…
The Callbacks: The trigger page
Lets start with the trigger page which as you remember is the page that will contain a solitary link to execute our marvelous AJAX commands. This function needs to do 3 things and they are …
- Tell Drupal to load in it’s core AJAX libraries.
- Present the user with a link that runs our AJAX commands and has the id my-special-link (important for later on … trust me).
The best part is that each of those 3 things only takes one line of code to do (very exciting stuff).
The Callbacks: The AJAX response
This is where we get down and dirty, and this is the whole reason for this tutorials existence … ready for it? AJAX Commands! AJAX Commands are so simple it hurts however their documentation (available at http://api.drupal.org/api/drupal/includes%21ajax.inc/group/ajax_commands/7) can be a bit daunting for a newbie. In this callback we only need to do 3 things (and you guessed it, each of them is only a single line of code).
- Define an array to hold all our awesome AJAX commands in.
- Add a new AJAX command to our array that inserts the text ’Hello world’ after our link (using the id my-special-link (told you we’d need that).
- Return our AJAX commands in (super fast) JSON.
The Callbacks: The fallback
If you wanted to apply Drupal.ajax to more than one link on a page you’re best bet would be to target the links using a jQuery $.each() loop however for the purposes of our quick and dirty demo, we’re going to be targeting a single element using an ID.
Drupal 7’s AJAX commands are practical, stable, clean and simple and I’d really like to see more developers leveraging them and creating some really cool AJAX driven Drupal sites. This tutorial is completely basic but I hope it’s at least got you curious about exploring the documentation pages (http://api.drupal.org/api/drupal/includes%21ajax.inc/group/ajax_commands/7) and doing AJAX the ‘Drupal way’.