Ajax Load

nedjo - April 5, 2008 - 03:18

Helper module to load and add JavasScript and CSS data for Ajax-loaded content.

When loading new content via AJAX, there is the potential need to load CSS and Javascript files and data not already available on the page. Ajax Load is a helper module designed to handle this task. It should only be installed for use with another module.

Ajax Load was written to accompany a patch that added AJAX loading to the Views module. When enabled, Ajax Load will ensure that any needed JS and CSS files are loaded along with dynamically loaded views.

Maintained by markus_petrux and nedjo.

Developer usage

To see a full working example, download the dev version, which includes an ajax_load_example module.

Ajax Load implements a drupal_alter() hook, hook_ajax_data_alter().

Ajax Load expects an object or array that is about to be sent in JSON format. The object should have a __callbacks property with Javascript callbacks that the JSON data are to be fed into.

Here is an example similar to the usage in ajax.inc in Views:

<?php
        $object = new StdClass();
        $object->content = $item->content;
        // Register the JavaScript callback for this module.
        $object->__callbacks = array('Drupal.example.ajaxResponse');
        // Allow other modules to extend the data returned.
        drupal_alter('ajax_data', $object, 'example', $item);
        drupal_json($object);
?>

In this snippet we set a __callbacks property on the object to be returned and then pass it through drupal_alter(). As well as the object, we pass two additional optional arguments: an object type argument - in this case, 'example' - and the original object, in this case, the item. These optional arguments can be used in hook_ajax_data_alter() implementations to help decide what alterations to apply.

On the Javascript side, the AJAX submit handler must call the callbacks specified in the __callbacks array. Here is code similar to what's used in ajax_view.js:

        .submit(function () {
          $('input[type=submit]', this).after('<span class="example-throbbing">&nbsp</span>');
          $(this).ajaxSubmit({
            url: ajax_path,
            type: 'GET',
            success: function(response) {
              // Call all callbacks.
              if (response.__callbacks) {
                $.each(response.__callbacks, function(i, callback) {
                  eval(callback)(target, response);
                });
              }
            },
            error: function() { alert(Drupal.t("An error occurred at ") + ajax_path); },
            dataType: 'json'
          });
  
          return false;
        })

Note that, in the success handler, we call all registered __callbacks. Other modules - e.g., ajax_load - can add their own callbacks to be called here.

The callbacks must include at least two arguments:

target: the element to be processed. E.g., if the AJAX call returns content to be rendered to the page, this might be the element that the content is to be rendered into. If in doubt, pass document (the full document).
response: the full JSON object returned by the AJAX call. This object may include properties set by other modules through the drupal_alter() call.

A sample callback:

Drupal.example = {};
Drupal.example.ajaxResponse = function (target, response) {
  $(target).append(response.data).
  Drupal.attachBehaviors(target);
};

Ajax Load makes the following alterations to an object it is fed:

add arrays of Javascript and CSS data/files
add a Javascript callback to the __callbacks array to receive the returned data

When the JSON data are returned, Javascript and CSS files are examined and, if not already present, are loaded. All going well, Javascript behaviours and CSS instructions should be present as needed for the dynamically loaded content to function and display correctly. Drupal.attachBehaviors() is called when all new Javascript files have loaded.