Skip to content
JavaScript

jQuery and jQuery UI in Drupal 7

5 min read

The inclusion of jQuery in a custom Drupal theme seems to cause a lot of confusion to people new to Drupal. There is, of course, a proper way of doing it and it's not that difficult once you know how.

Drupal 7 comes packaged with both jQuery and jQuery UI. It uses these two JavaScript libraries to drive parts of its own user interfaces like the admin overlay screens and improvements to content tables etc.. However, the way Drupal works requires it to know that the page being rendered contains JavaScript that will require one or both of these libraries in order for it to be included.

Including jQuery in your templates

When you want to include some jQuery or other JavaScript in your theme's template you need to use the drupal_add_js method. You do this in the theme's template.php file using the relevant hook. For example, if you want to include a jQuery script on every page you would use the following in your template.php file:-

function MYTHEME_preprocess_page(&$vars) {
  drupal_add_js(path_to_theme().'/scripts/page.js','file');
}

This will include the 'page.js' script on every page where the file is located in a 'scripts' folder within the current theme. MYTHEME needs replacing with the name of your theme. If you only want the 'page.js' script running on the home page of your site then you'd just add a conditional statement to the MYTHEME_preprocess_page method:-

function MYTHEME_preprocess_page(&$vars) {
  // Only include page.js on the front page
  if ($vars['is_front']) {
    drupal_add_js(path_to_theme().'/scripts/page.js','file');
  }
}

Using the drupal_add_js method you can also include JavaScript from an external source:-

drupal_add_js('http://example.com/example.js', 'external');

You can also include your JavaScript within the method call:-

drupal_add_js('jQuery(document).ready(function () { alert("Hello world!"); });', 'inline');

Personally, I believe that the JavaScript code should be kept out of the PHP and included as a file as described earlier. This just keeps things neater and both the PHP and JavaScript code are easier to read.

Using jQuery in Drupal 7

If you look at the inline JavaScript example above you'll notice that the jQuery method is being used in the JavaScript. As of Drupal 7 you can no longer rely on $() being recognised as the jQuery function. This is to ensure that there are no conflicts between JavaScript libraries that may be in use on a site. It might seem a pain, but this is a good practice. So when ever you are including some jQuery make sure it's properly wrapped either as the above example or like the following:-

(function ($) {
  $(document).ready(function(){
    alert("Hello world!");
  });
})(jQuery);

Including jQuery UI in your templates

As I mentioned earlier, Drupal 7 comes packaged with jQuery UI as well as jQuery. Including it can be a bit of a mystery at first, but it is really simple. When you need to include part of the jQuery UI library use the drupal_add_library method in your template.php file:-

function MYTHEME_preprocess_page(&$vars) {
  drupal_add_library('system','ui.dialog');
  drupal_add_js(path_to_theme().'/scripts/page.js','file');
}

This will include the jQuery UI dialog method so that page.js can now use it. The second parameter represents what is being included; so you could also use things like 'ui.accordion' and 'ui.tabs' to include the jQuery UI accordion and tabs methods respectively.

The drupal_add_library method allows you to include a set of JavaScript and/or CSS files from any installed module: drupal_add_library($module, $name). jQuery UI is included with the System module.

jQuery and jQuery UI versions

The version of jQuery gets locked down with the release of Drupal during development to ensure stability. It is all part of the testing process. The Drupal developers fully test the system before releasing a new major version of the CMS, including the JavaScript functionality. The incremental changes that go on throughout the year do not provide the time to test at this level so the jQuery version stays the same.

This unfortunately can mean you get stuck with an old version that will not work with a plugin you want to use. In which case you may need to consider using a contributed module like jQuery Update which at the time of writing will update Drupal 7 to jQuery 1.5.2 and jQuery UI 1.8.11.

Closing comments

Hopefully you've seen that including jQuery and jQuery UI is not that taxing.

You can of course use the drupal_add_js and drupal_add_library methods in any of your template.php methods. So for example you can include jQuery for a particular node type using the MYTHEME_preprocess_node method. You can also use the same methods from within a custom module (although remembering to keep the scripts within the context of the module not a theme).

Have fun including JavaScript to enhance your users' experience!

© 2024 Andy Carter