Rotating banners in WordPress with jQuery

Recently I had a project that needed to have a rotating banner on the main page. Most rotating banners out there are connected to feature posts or articles. WooThemes and some of Matt Brett’s projects often use this method.

This wasn’t going to cut it for me. I needed to have rotating banners that were not associated to any posts, could link off site, be updated/maintained by the client, and preferably not use any custom field voodoo. The last thing I wanted to do was use a post category since it would be major over kill.

So I came up with a solution that fit all my requirements above and works great. Figured I would share what I did in case anyone else needs a similar solution.

The rotating banners were accomplished using:

• jQuery
• jQuery Carousel plugin
• WordPress Link Manger

Let’s get started here.

Step 1: setup a link category

When you’re logged into the WP admin panel, click on Links on the left (under Media, above Pages). The Links section will expand and now we need to create a Link Category.

Add your Banner category

After you have added your Banner category (or whatever you decide to name it) you want to find the ID for that category. There are 2 ways you can do this. First, place you cursor over the category and look in browser status bar.

The second option is to use Sivel’s Simply Show IDs plugin which will tell you the ID. Either way, just make sure you note what the ID is for your category since we will need it later.

Step 2: add some banners

Now we will add some links to the category. Click Add New under Links.

The name and description is for your reference and will not be shown or used. Make sure you place the link in the category you created. Lastly you will need to put the location of the image in the Image Address field. The easiest way is to upload your banners using the WordPress Media manager. If you go that route your image location will be something similar to http://yoursite.com/wp-contents/uploads/11/09/banner.jpg.

Step 4: downloading  and moving jQuery Carousel

Now that we have the banner category created and some links/images in the category we need to get things setup behind the scenes.

First, download jQuery Carousel.

Secondly, unzip the files. You will see a bunch of files, most of which we won’t need.

Open up your theme folder (/wp-contents/themes/yourtheme/) and create a folder inside called js.

Now we need to move jquery.jcarousel.pack.js or jquery.jcarousel.js (look in the /libs/) to this folder. The path should be similar to /wp-contents/themes/yourtheme/js/jquery.jcarousel.pack.js

Note: It is up to you which version of jCarousel you use. I prefer the packed version since it is smaller and we will not need to do any editing.

After the jCarousel javascript file has been moved we need to move over the CSS. Open jquery.jcarousel.css, copy the contents, and paste it into your theme’s style.css.

So to recap, you should have:
/wp-contents/themes/yourtheme/js/jquery.jcarousel.pack.js
/wp-contents/themes/yourtheme/style.css (should contain the CSS from jquery.jcarousel.css)

Step 5: setting up jCarousel and jQuery

Once you have added the necessary jCarousel CSS to your theme’s style.css you will need to edit it to meet the dimensions of your banner.

/* @group jcarousel */

.jcarousel-banners {
 border: 1px solid #cfcfcf;
 margin:0 0 30px 0;
}

.jcarousel-container {
 position: relative;
}

.jcarousel-clip {
 z-index: 2;
 padding: 0;
 margin: 0;
 overflow: hidden;
 position: relative;
}

.jcarousel-list {
 z-index: 1;
 overflow: hidden;
 position: relative;
 top: 0;
 left: 0;
 margin: 0;
 padding: 0;
}

.jcarousel-list li,
.jcarousel-item {
 float: left;
 list-style: none;
 /* We set the width/height explicitly. No width/height causes infinite loops. */
 width: 578px;
 height: 130px;
}

/**
 * The buttons are added dynamically by jCarousel before
* the</pre>
<ul>
<ul>list (inside the</ul>
</ul>
<div>described above) and
 * have the classnames "jcarousel-next" and "jcarousel-prev".
 */
.jcarousel-next {
 display: none;
}
.jcarousel-prev {
 display: none;
}

.jcarousel-banners .jcarousel-list li,
.jcarousel-banners .jcarousel-item {
 position: relative;
 float: left;
 list-style: none;
 width: 578px;
 height: 130px;
}

.jcarousel-banners .jcarousel-container-horizontal {
 width: 578px;
}

.jcarousel-banners .jcarousel-clip-horizontal {
 width: 578px;
 height: 130px;
}

.jcarousel-banners .jcarousel-item {
 width: 578px;
 height: 130px;
}

Above is what the CSS looks like for my website. The size of the banners is 578x130px. Change this to the size of your banners. You might need to do some further tweaking later.

Now the CSS is done and jCarousel is in place we need to tell WordPress to use jQuery and jCarousel when it loads a page.

Open up functions.php inside your theme directory. You may have to create it if your theme does not have one. Now add this:

if (!is_admin()) {
wp_enqueue_script('jquery');
wp_enqueue_script('jcarousel','/wp-content/themes/yourtheme/js/jquery.jcarousel.js',false,false);
}

WordPress includes many scripts out of the box, one of them being jQuery, so there is no need for us to download it. The code snippet tells WordPress – as long as we are not in the admin panel – to load jQuery and the jCarousel script.

Step 6: finishing things up on the front end

Your banners have been created, the files have been moved, and WordPress now knows to use jQuery and jCarousel when a page loads – almost done!

The last thing we need to do is add the code to grab the banners and make them work.

Open up  index.php or home.php (the location you want to place your banners)  in your theme directory and use this snippet:

</pre>
<div id="banners">
<ul>
<ul><!--?php wp_list_bookmarks( 'categorize=0&category=49<&title_li=&before=
	<li-->&after=</ul>
</ul>
<ul>&show_images=1&show_description=0' ); ?></ul>
</div>
<pre>

This snippet will grab links you created earlier and only show the images. Make sure you change category=49 to your category ID.

Lastly, open header.php in your theme directory. Place the code snippet below in between the <head> </head> tags – usually right after you see wp_head();

jQuery(document).ready(function($) {
$('#banners').jcarousel({
scroll: 1,
auto: 4,
wrap: 'last',
animation: 'slow',
buttonNextHTML: null,
buttonPrevHTML: null
});
});

The jQuery that comes with WordPress runs in non conflict mode, which is why do not use the typical document ready call. jCarousel is very configurable, so I suggest you check out all the different options and make sure your settings are set for the functionality you desire.

Step 7: Profit.

That’s it! If you followed all the steps right you should have a rotating banner on your site.

I found this to be a better solution that any of the plugins I found. We didn’t have to do anything crazy, use posts, or write any plugins. Normally I would provide a demo of this in action but I have a feeling the client I did this for would rather not be mentioned.

If you have an questions or problems, feel free to leave a comment.

If you do expereince problems, a few things to double check/tweak:

• view your source to make sure WP is calling jQuery and jCarousel
• check to make sure you have the correct category ID
• modify the CSS if things don’t render correctly