Vizou » Adding a jQuery slider to a self-hosted WordPress site

Adding a jQuery slider to a self-hosted WordPress site

24 May 2010

In the search for a jQuery “slider” (made popular by the nice one at http://panic.com) for a client’s WordPress installation, I decided to give EasySlider a try. After QUITE a bit of tinkering I was able to integrate it into the site and there were moments I thought the plugin ought to be entitled NotSoEasySlider, which is a greater reflection on how WordPress made it a bit complicated than on the great work by the author, Alen Grakalic! Along the way, I boned up on how to use the existing jQuery already loaded by WordPress (saving on resources) and a few more tricks to ensure that jQuery loaded properly for the plugin (paths can be frustrating!).

Click on the image to see a demo. The demo is in my own site and is a slightly adapted version (different height, content; doesn’t really go with my site!) than on the client site as their site is not yet live.

Objective

My goal was to have a “featured” area on the home page where weekly specials would be displayed in a continuous horizontal slider, each one a Post in a category titled “featured”. Only the last 3 items would be displayed.

Ingredients

These are the files you’ll need to either create or edit.

js folder (create it in your theme folder; although it could be elsewhere)
easySlider.js (download and put it in the js folder)
slider.php (create this document in your theme folder)
index.php (or whatever page you want to display the slider on)
header.php (in your theme)
style.css (in your theme)

Instructions

Before I start, I want to mention that I’m first and foremost a designer and my years of scanning things that are neatly lined up to the left prevents me from being able to efficiently read (or write) indented code. I’ve tried and tried, but it just doesn’t work for me, so my apologies to you hard-boiled coders! So, here’s what to do if you’re trying to do this kind of implementation :

1. Download the slider code from CSSGlobe at http://cssglobe.com/post/5780/easy-slider-17-numeric-navigation-jquery-slider

2. Creat a folder called js in your client WordPress theme and copy easyslider.js into it. I took the version number off of the script title because I wanted to be able to easily update it without changing the link in the WP header to reflect the newer version.

3. Open header.php in your theme (or create a custom header if this is just for use on one page) and add the following just before wp_head (after your stylesheet and RSS links). This is really, really important to getting it working in WordPress as this code makes sure that WordPress’s jQuery is queued up for use by the javascript function we’re about to add. This way, we don’t have to add ANOTHER link to ANOTHER instance of jQuery (which you would need to link to if your site didn’t already have it activated). I also discovered that WordPress includes the latest, streamlined version of jQuery and uses what is referred to as “no-conflict” mode so that (hopefully) it won’t clash with plugins that try to use a different version. Or something like that. Google it.

<?php wp_enqueue_script("jquery"); ?>

Then comes…

<?php wp_head(); ?>

Followed by the link to the plugin. Please note that I used the full path to avoid additional queries being made by WordPress template tags, but you could do it that way (i.e blog_url and template_url). And notice that the only link is to the easySlider script; I’ve left off the link to jQuery which Alen includes in his instructions (which are not for installation on WordPress) :

<script type="text/javascript" src="http://yourdomain.com/wp-content/themes/yourtheme/js/easySlider.js"></script>

Note that the easySlider instructions tell us to use the following code following the link to the script :

<script type="text/javascript">
$(document).ready(function(){
$("#slider").easySlider({
continuous: true,
controlsFade: false
});
});
</script>

But this wasn’t working for me, so I went looking for the answer. A comment from reader Otto (no link given, but THANKS, Otto!) in response to this fantastic article by Chris Coyier in the CSS-Tricks forum about properly loading jQuery suggested employing this different structure, which is what I did, and it worked like a charm! Apparently it prevents conflict with certain plugins that use the $ variable.

jQuery(document).ready(function($){
// your $ code here
});
So here's what I did  after reading that :

<script type="text/javascript">
jQuery(document).ready(function($){
$("#slider").easySlider({
continuous: true,
controlsFade: false
});
});
</script>

The easySlider plugin has a ton of options, including automatic scrolling, continuous (endless carousel), option to fade out next/previous controls when they’re not useful, numeric slide navigation and more. I opted for continuous and didn’t want the disappearing controls since I created a design that lets users click on arrows to go forward or backward (or just forward or backward, endlessly!).

4. Visually speaking, in my client’s theme the slider is positioned across the top of two righthand sidebars, so I had to mess with the original CSS to adjust to a different width as well as a li containing more than a simple image of exactly the right size! I added it to the appropriate template in their theme with this :

<?php include(TEMPLATEPATH."/slider.php");?>

5. The CSS is without a doubt the hardest part of all this. A tip I can offer is that you need to understand up front that Alen has configured the javascript to handle layout and navigation using unordered lists (ul, li) so EACH SLIDE is a single li. This is easy if your list item will always be a single image or a few lines of text. I couldn’t do it the easy way, of course; I wanted each li to be a complete post with a link to the post. I started out by trying to do this using the handy Simple Image Grabber plugin and the_excerpt and got frustrated by problems with the math that manages the “continuous” option. It didn’t like my floating two line items next to each other to fill the (actually double) space in a single “slide”. Finally, I opted for a WP query that grabbed 6 posts from the appropriate category and put the entire content, including image, into a single line item as intended. If I was any good at javascript I’d probably figure out how to change the selectors and customize the easySlider script but I’d already spent an entire day trying to get this working, so I’ll leave that ’til another day!

Here’s what the CSS looks like for the demo version here on my site (you’ll likely be messing with the #slider li width and height and the padding around the post text). The text for the buttons (which I’ve included in the demo but not in my client’s site) is in the easySlider.js itself.

#featured {
width: 450px;
height: 290px;
background: #fff url(images/featured.jpg) no-repeat -8px -12px;
border: 1px solid #ccc;
overflow: hidden;
margin-top: 10px;
}

#slider {
}

#slider img {
float: left;
margin: 0 10px 0 0;
padding: 5px;
width: 150px;
height: auto;
}

.slide-title {
color: #fff;
font-weight: bold;
line-height: 100%;
display: block;
text-align: center;
margin-bottom: 35px;
}

#slider p {
padding: 0 15px;
}

#slider ul,
#slider li {
list-style: none;
overflow: hidden;
margin: 0;
}

#slider li {
width: 440px;
height: 290px;
padding: 5px 0px;
overflow: hidden;
}

#prevBtn,
#nextBtn {
display: block;
width: 80px;
position: absolute;
top: 92px;
font-size: 0.8em;
}

#prevBtn {
left: 53px;
}

#nextBtn {
left:418px;
}

#prevBtn a,
#nextBtn a {
color: #fff;
display: block;
width: 80px;
height: 32px;
padding-top: 5px;
text-transform: uppercase;
}