Using jQuery with Drupal

You know those nifty "smooth scrolling" effects you've seen? Well, today I'm going to show you how to implement this animation on your Drupal site. As a bonus, you'll learn how to add any jQuery snippet or plugin the "Drupal way". But first, a little background.

About a week ago, as I was helping my wife with her website, she asked if I could make her site have this, "cool scrolling thing" that she had found while doing some research.

I mumbled something about looking into it and put it on my mental "to do" list.

A few days later I received an email from the Drupal LinkedIn Group that featured a discussion on the very same question. Clearly the universe wanted me to write a blog post on this topic, so here we are. On the LinkedIn discussion, one of the suggestions was to use this bit of code from Cedric Dugas. 

But if you take a look at the code, you're still left with a question - what's the best way to implement this in a Drupal theme? As David Carrus noted in the discussion, there are a couple of ways to do this in Drupal. I'm going to show you my favorite and we're also going to use a different snippet of jQuery to create this effect - one that works better in my opinion.

The Setup

To follow along you're going to need a few things. First of all, the jQuery snippet. The best way to create this effect was originally written by Karl Swedberg, but is available in an easy digestible form at CSS Tricks. You can get the code there and also see an example in case you're still not sure what "smooth scrolling" is all about. This particular method will allow us to have an animated scrolling effect to any element on our page with the id attribute defined.

The second thing you're going to need is an installation of Drupal and access to your theme folder, but be sure you try this out in a test environment. You don't want any little mistakes bringing your site down.

Step One

The first step is to grab the code above (from CSS Tricks) and place in a new file.

For this example I've named my file, "jquery.smooth-scroll.js". I've placed it in a folder called "js" that I created in the sites/all/themes/MY_THEME folder, where 'MY_THEME' is the name of the active theme for your site.

But we're not quite done with this file yet. We need to add what are called, "JavaScript closures". They are functions that limit the scope of variables to keep them from stepping on the toes of any global variables that might be referenced. If you don't understand that last bit, no worries. Here's the snippet of code we need to include:

jQuery(document).ready(function($) {

// Place the code from CSS Tricks here!


To be clear, the jQuery you got from CSS Tricks goes right below the code comment, which can be safely deleted. There are a couple of other ways to deal with JavaScript closures which you can read about in the documentation, but for our purposes, this will work just fine.

Step Two

The next thing we have to do is let Drupal know we want to use this file in our theme. The way I like to add JavaScript to my themes is to use the drupal_add_js function in the template.php file. If your theme doesn't have a template.php file, go ahead and create one and save it to your theme folder. 

Now there are other ways to add JavaScript to your theme, but I prefer this one. On some occasions I have had to use conditional logic to add jQuery plugins to specific pages and it is easier for me to be consistent with how I solve these sorts of problems, so I always use this method. The link to the documentation above discusses other ways of doing it if you're interested.

The way you tell Drupal to include the file you created is using this line of code in template.php:

drupal_add_js(drupal_get_path('theme', 'YOUR_THEME_NAME') .'/js/jquery.smooth-scroll.js');

All that you need to modify to get this to work in your theme is to change 'YOUR_THEME_NAME' to the name of your theme and to make sure that your path is correct on the last bit. If you didn't save the file with your jQuery with the same name and in the same place as I did, make sure you modify that appropriately.

Step Three

If you're new to Drupal, skipping this step will cause you no end of confusion. Yes, you must go clear the cache. Whenever you make a change to a file in your theme, you should go clear the cache so that it takes effect. 

Step Four

This next step is really easy and is why I used the example from CSS Tricks. This jQuery works by using the id attribute in the link to the element you want to scroll to. Clear as mud?

Let's say you have an h1 tag at the bottom of the page that you would like users to be able to "smooth scroll" down to. The markup of the h1 tag looks like this:

<h1 id="drupal-rocks">Ten Reasons Drupal Is Awesome!</h1>

And the link to that h1 tag looks like this:

<a href="#drupal-rocks">Read why Drupal is so awesome!</a>

Note the hash tag in front of the id name in the href attribute. Pretty easy, right? You can now have an animated scroll to any element on your page that has the id attribute defined. A "Return to Top" link like you'll find on this site is something that comes to mind as a practical application, but you could also use it to create a single page site like this guy.

Not bad, eh?

About the Author

John Hannah, Drupal theme designer

I’m John Hannah, a front-end developer, avid Drupalista and the guy behind Friendly Machine. I currently work for Woodward Design Group.

When I'm not building websites, I travel as much as possible and enjoy hanging out with my wonderful family. My favorite place to spend time online is Twitter, so please feel free to connect with me there.