Last updated February 19, 2008. Created on December 30, 2005.
Edited by ax, nedjo. Log in to edit this page.

The file drupal.js is a collection of utility functions providing functionality commonly needed in Javascript applications. As drupal.js is loaded automatically the first time a module calls drupal_add_js(), its methods are always available to other scripts.

Testing for appropriate Javascript support

function isJsEnabled() tests for availablility of a number of Javascript methods commonly needed and used in Drupal Javascript applications. This function is commonly used in combination with addLoadEvent() so that a particular behaviour can be implemented only if appropriate Javascript support is available. This test is referred to as a "killswitch". An example is the first lines of autocompete.js:

// Global Killswitch
if (isJsEnabled()) {
  addLoadEvent(autocompleteAutoAttach);
}

AJAX data exchanges

Two functions in drupal.js provide cross-browser methods for AJAX--dynamic data exchanges between the client and server. These can be used, e.g., to dynamically refresh selected page content based on user actions.

function HTTPGet() and its pair function HTTPPost() are used to send data to a server and specify a handler for the response.

function HTTPGet(uri, callbackFunction, callbackParameter) accepts three arguments: the uri to post to, the function to handle the response, and a callback parameter--usually, a reference to the calling object. The uri will generally be a Drupal path pointing (via a menu item) to the function that parses the client request and sends back a response. Since a Get operation sends information in url-encoded arguments, the data being sent is typically appended to the uri. If a node id is being sent, for example, the uri might look like:

'modulename/action/' + nid;

In the PHP handler function, the nid could then be accessed as arg(2).

function HTTPPost(uri, callbackFunction, callbackParameter, object) is similar to HTTPGet() except that it uses a Post rather than Get operation and includes the additional argument, object. This is the data to be posted to the server.

For more information on using these functions, see the tutorial on using AJAX.

Working with CSS class names

CSS class names play an important part in Drupal's Javascript implementation. Several drupal.js methods focus on adding, removing, and manipulating class selectors.

If you're wanting to add a class name to an element, you might be tempted simply to set its classname attribute:

elt.classname = 'name';

But this method would overwrite any existing class name. By using function addClass(node, className), you ensure that a new name is added to any existing ones. addClass() takes as arguments the node being acted upon and the specified class name.

Similarly, removeClass(node, className) (same two arguments) removes only the specified class name, leaving any others in place.

hasClass(node, className) tests if a given element has a given class name, while toggleClass(node, className) will add a class name if its not present, or remove it if it is.

Element position

function absolutePosition(el) will return the absolute position of an element on the screen. The return value is an object with properties of x and y, representing the absolute x and y coordinates of the element.

Adding events

Similar to addClass(), two functions provide methods for adding events to elements. addLoadEvent(func) adds a function to the window onload event. This is typically used in combination with isJsEnabled(), see above.

function addSubmitEvent(form, func) adds a function to a given form's submit event. This is useful for changing the behaviour of a form. See autocomplete.js for a sample usage (to prevent a form from submitting if the suggestions popup is open).

Looking for support? Visit the Drupal.org forums, or join #drupal-support in IRC.