Demystifying Drupal AJAX Callback Commands

Include Drupal AJAX library // Render a page of messages. function mymodule_messages_page() { // Include AJAX library. drupal_add_library(‘system’, ‘drupal.ajax’); // Create inital page content. $content = theme_item_list(array( ‘title’ => t(‘Unread Messages’), ‘type’ => ‘ul’, ‘attributes’ => array( ‘id’ => ‘unread-msgs’), ‘items’ => mymodule_messages_list(mymodule_get_unread_messages()), )); $content .= ‘<div id=”current-msg”><h2></h2><p></p></div>’; $content .= theme_item_list(array( ‘title’ => t(‘Read Messages’), ‘type’ => ‘ul’, ‘attributes’ => array(‘id’ => ‘read-msgs’), ‘items’ => mymodule_messages_list(mymodule_get_read_messages(), FALSE), )); return $content; } mymodule/mymodule.module Function to build a page of messages. On line #4, using the drupal_add_librry() function to include the AJAX library on the page.

Attach AJAX to page elements // Return array of message titles for use in a list. function mymodule_messages_list($messages, $display_link = TRUE) { $list_items = array(); foreach ($messages as $mid => $msg) { // Build link to AJAX callback to load message. $link = l($msg->subject, ‘read-message-callback/nojs/’ . $mid, array( // Add class to link so Drupal knows to use AJAX. ‘attributes’ => array(‘class’ => array(‘use-ajax’)), )); // Create list item for message. $list_items[] = array( ‘id’ => ‘msg-’ . $mid, // Set data to read message link or just message subject. ‘data’ => $display_link ? $link : $msg->subject, ); } return $list_items; } mymodule/mymodule.module Function to build a list of messages. On line #6, creating a link element which links to our callback path. On line #8, adding the class ‘useajax’ so AJAX framework knows to serve link with an AJAX request.

3.a Define a callback path // Implements hook_menu(). function mymodule_menu() { $items = array(); //.. Other menu items. // None JS callback, for graceful degredation. $items[‘read-message-callback/nojs/%’] = array( ‘title’ => ‘AJAX Callback to Read Message’, ‘access arguments’ => array(‘access content’), ‘page callback’ => ‘mymodule_read_message_callback’, ‘page arguments’ => array(1,2), ‘type’ => MENU_CALLBACK, ); // Create AJAX callback. Add ajax_delivery callback. $items[‘read-message-callback/ajax/%’] = array( ‘delivery callback’ => ‘ajax_deliver’, ) + $items[‘read-message-callback/nojs/%’]; return $items; } mymodule/mymodule.module Creating two menu items for callback functions. The first is for handling graceful degredation when reached outside an AJAX Request. The second is the AJAX callback, which add a delivery callback of “ajax_callback” so Drupal know to return an AJAX Response object.

3.b Return array of commands using a render array [D7] // AJAX Callback to read a message. function mymodule_read_message_callback($method, $mid) { $message = mymodule_load_message($mid); // @TODO: Graceful degredation if not from ajax method or if no message. $commands = array( // Replace content of current message subject. ajax_command_html(‘#current-msg h2’, $message->subject), // Replace content of current message body. ajax_command_html(‘#current-msg p’, $message->content), // Remove message from unread list. ajax_command_remove(‘#msg-’ . $mid), // Add message to read list ajax_command_append(‘#read-msgs’, ‘<li>’ . $message->subject . ‘</li>’), ); // Return an AJAX render array. return array( ‘#type’ => ‘ajax’, ‘#commands’ => $commands, ); } mymodule/mymodule.module Lines #5 thru #14, building an array of Core AJAX Callback commands. Each mapps to a javascript function. Line #16 building a render array of type ‘ajax’. Drupal will package into JSON and send back to the client.

Add a function to ‘Drupal.ajax.prototype.commands’ (function($, Drupal) { // Add new command for reading a message. Drupal.ajax.prototype.commands.readMessage = function(ajax, response, status){ // Place content in current-msg div. $(‘#current-msg h2’).html(response.subject); $(‘#current-msg p’).html(response.content); // Remove from unread list. $(‘#msg-’ + response.mid).remove(); // Add message to read list. $(‘#read-msgs’).append(‘<li>’ + response.subject + ‘</li>’); } })(jQuery, Drupal); mymodule/js/commands.js Attach a new ‘readMessage’ command to the Drupal AJAX Commands JavaScript object. Function takes in the 3 arguments “ajax”, “response” & “status”. Wraps jQuery functions to display a message on the page.

Callback returns commands using an AJAXResponse() [D8] namespace Drupal\mymodule\Controller; use Drupal\Core\Controller\ControllerBase; class MyModuleController extends ControllerBase { // … // AJAX Callback to read a message. public function readMessageCallback($method, $mid) { $msg = mymodule_load_message($mid); // Create AJAX Response object. $response = new AjaxResponse(); // Replace content of current message subject. $response->addCommand(new HtmlCommand(‘#current-msg h2’, $msg->subject)); // Replace content of current message body. $response->addCommand(new HtmlCommand(‘#current-msg p’, $msg->content)); // Remove message from unread list. $response->addCommand(new RemoveCommand(‘#msg-’ . $mid)); // Add message to read list. $item = ‘<li>’ . $msg->subject . ‘</li>’; $response->addCommand(new AppendCommand(‘#read-msgs’, $item)); // Return ajax response. return $response; } mymodule/src/Controller/MyModuleController.php Returning an AjaxResponse object instead of a render array like in Drupal 7. AjaxResponse has an ‘addCommand’ method, which takes the argument of a command object.

Define command object that implements CommandInterface namespace Drupal\mymodule\Ajax; use Drupal\Core\Ajax\CommandInterface; class ReadMessageCommand implements CommandInterface { protected $message; // Constructs a ReadMessageCommand object. public function __construct($message) { $this->message = $message; } // Implements Drupal\Core\Ajax\CommandInterface:render(). public function render() { return array( ‘command’ => ‘readMessage’, ‘mid’ => $this->message->mid, ‘subject’ => $this->message->subject, ‘content’ => $this->message->content, ); } } mymodule/src/Ajax/ReadMessageCommand.php Creating a Command object which implements the CommandInterface. Must declare a ‘render’ method, which will return an associative array. This associative array must have an element with the key of ‘command’ and value of the JavaScript function to run.

Attach library to a render array namespace Drupal\mymodule\Controller; use Drupal\Core\Controller\ControllerBase; class MyModuleController extends ControllerBase { // … // Render a page of my messages public function messagesPage() { // .. build $content // Create render array. $page[] = array( ‘#type’ => ‘markup’, ‘#markup’ => $content, ); // Attach JavaScript library. $page[‘#attached’][‘library’][] = ‘mymodule/mymodule.commands’; return $page; } // … } mymodule/mymodule.module Function for building messages page is now using a render array. to the ‘#attached’, ‘library’ array of that render array, including the custom library. No longer including the AJAX library, as Drupal will know to include it from the libraries.yml file.