Want to use the powerful jQuery JavaScript library in your Drupal module or theme? Excellent! You just need to know a few tips and potential gotchas before you get to work.
First, if you haven't already, check out the general tips for using the jQuery that comes with your CMS. As you'll see, these principles also apply when you're using jQuery in Drupal.
Including jQuery: the JavaScript Code
Even though jQuery comes with Drupal, you still need to wrap your code in a particular incantation of JavaScript (which may vary depending on which major version of core Drupal you're running). And then you need to load this JavaScript code on your Drupal site.
I'll summarize both steps here, but you'll want to get the full details from the documentation on drupal.org.
(I'll give the links in a moment.)
Basically, instead of wrapping your jQuery code in the $(document).ready function, the way the jQuery docs would tell you to do it, you use a special Drupal object, Drupal.behaviors.
Instead of this:
$(document).ready(function () {
// Your jQuery code here.
});
you do this (in Drupal 6):
Drupal.behaviors.myModuleBehavior = function (context) {
// Your jQuery code here.
};
The myModuleBehavior property will, of course, change depending on your module or theme name.
In Drupal 7, it's more like:
Drupal.behaviors.myModuleBehavior = {
attach: function (context, settings) {
$('input.myCustomBehavior', context).once('myCustomBehavior', function () {
// Apply the myCustomBehaviour effect to the elements only once.
});
}
};
To get the syntax right, you'll definitely want to peruse the full introduction on using the Drupal JavaScript API.
And note that, since you're using Drupal-specific code, you won't be able to test this function on a JavaScript tweaking site like jsfiddle.
Sure, you can test the jQuery code there first (I do). But you'll want to test this Drupal wrapper on a development copy of your live Drupal site.
So where do you put this JavaScript code so that it will actually load? You could edit the <head> element of your theme file, but that would be rather repulsive. Drupal offers several methods for programmatically loading a JavaScript file, whether you're including it in a module or a theme.
My favorite method is to include the filename in the ".info file" for the module or theme. Here's an example of how the file mytheme.js might be included at the start of an .info file:
name = My theme
description = Theme developed by me.
core = 7.x
scripts[] = mytheme.js
For more on this example, and other ways to include your JavaScript, see this Drupal doc on loading your JavaScript file in Drupal
Using jQuery Plugins
Just as Drupal can be extended with modules, jQuery can be extended with jQuery plugins. The canonical source for jQuery plugins is the jQuery Plugin Registry, but just as with Drupal modules, plugins are developed and (hopefully) maintained by a wide community of developers, not the official jQuery developers.
In theory, any jQuery plugin that can work with the jQuery version you're running should work on your site. In practice, you'll need to choose and test carefully, just as you would with a module.
Before you copy any code into your custom module or theme, check whether there's already a third-party Drupal module that implements this jQuery plugin.
The famous jQuery UI plugin, for instance, used to be implemented with the jQuery UI module. With Drupal 7, though, jQuery UI is now included in core.
The jQuery Plugins module is an effort to collect the most popular and useful jQuery plugins into a single module. I haven't used it myself, but I plan to give it a try if I want to use a plugin that's on its list.
jQuery Version Woes
Although Drupal's inclusion of jQuery is usually helpful, the drawback is that this included version will always be old. Every major Drupal release takes years to develop, which means that by the time it comes out, jQuery's already released several new versions.
This can cause trouble when jQuery plugins and even Drupal modules and themes require a newer jQuery version. The standard approach is to load that newer jQuery with the jQuery Update module. But if that doesn't work, you'll need to investigate further options for solving jQuery troubles in Drupal.
jQuery: Worth Your Time
Once you find out how easy jQuery is, and how integrated it already is into Drupal, you'll start finding uses for it all the time. The learning curve isn't that steep, and you get lots of power for a small amount of study.
Want more? Drupal.org has an excellent series of documentation articles on using JavaScript in Drupal.
