This post is directed mainly to people that are somewhat new to working with and developing WordPress themes. I know when I first started out, tutorials and articles like this one were extremely useful to me. I remember I didn't even know what the hell a "jQuery" was just a few months ago. Now, because of posts like this, I like to think I know how to use jQuery and all of the amazing plugins that are created with it to enhance the power of the themes I develop.

Today, I'll be going through the steps on how to implement one of my favorite jQuery plugins, s3Slider, into a WordPress theme. This can be used for dozens of different things, the most popular being a simple "recent post" carousel at the top of the home page. Basically, I'll be illustrating the steps I took to create the animated post scroller at the top of my latest WordPress theme, Rock Solid.

Step 1 - Download the Files

Alright now, lets get started. To use this jQuery plugin, we'll need two things: the jQuery library and the plugin files. Download each of them here:

Also worth noting is the s3Slider homepage. The creator is very good in noting down examples and a very detailed how-to on implementing the plugin. I suggest you take look for yourself.

Step 2 - Set Up Your Page

Now that you have the files, you have to tell your web page where they are and how to use them. This is done inside of the HEAD tags. Add the following lines of code there:

<script src="js/jquery-1.3.2.min.js" type="text/javascript"></script>
<script src="js/s3Slider.js" type="text/javascript"></script>

Note: This is assuming you have both the jQuery and s3Slider plugin inside of a /js/ folder that is located in your theme folder.

Next, you have to add the function that calls to the s3Slider script and tells your web page where to use the plugin. It's not hard, just copy and paste the following right under what you just did:

$(document).ready(function() {
   $('#s3slider').s3Slider({
      timeOut: 4000
   });
});

You can change the value of "timeOut" to whatever you want. This is the delay in the transition between the various slides measured in milliseconds. This part of the code also tells the s3Slider plugin to activate itself on a div ID'd with "#s3slider". This is very important for the next step.

Step 3 - The HTML and PHP

Alright. At this point, we have our files set up and we have told our web page how to (and where to) use the s3Slider plugin. Now it's time to implement it. Remember, the slider is told to be activated in a div ID'd with the name "s3slider". Here is the code to display the 3 most recent posts. Each post will show 4 things - the title, the author, the date published, and the post image as the background (that was defined through the Custom Fields).

<div id="s3slider">
	<ul id="s3sliderContent">
		<?php
			$my_query = new WP_Query('showposts=3');
			$wp_query->in_the_loop = true;
			while ($my_query->have_posts()) : $my_query->the_post();
		?>
		<li class="s3sliderImage">
			<?php $thereisimage = get_post_meta($post->ID, image, true);
			if($thereisimage){ ?>
				<a href="<?php the_permalink() ?>"><?php image_attachment(image, 512, 200); ?></a>
			<?php }else{ ?>
				<a href="<?php the_permalink() ?>"><img src="<?php bloginfo('template_url');?>/images/default-post-image.gif" alt="Post Image" /></a>
			<?php } ?>
			<span>
				<a class="featured-title block" href="<?php the_permalink() ?>" rel="bookmark" title="<?php the_title(); ?>"><?php the_title(); ?></a>
				<?php the_time('F j, Y'); ?> by <a href="<?php the_author_url(); ?>"><?php the_author();?></a>.
			</span>
		</li>
		<?php endwhile;?>
		<li class="clear s3sliderImage"></li>
		</ul>
</div>

It may look a bit intimidating, but it's really not.

The first php snippet at the top is a WordPress query that tells WordPress to use only 3 posts. It then opens up a while loop with the code that will be applied to each post. Simply speaking, each post will be put inside of an LI tag with a class of s3sliderImage. (It is very important that the word "s3slider" is at the beginning of the class name. The plugin won't function properly if it isn't.)

The hardest part of this step is with this bundle of code right here:

<?php $thereisimage = get_post_meta($post->ID, image, true);
if($thereisimage){ ?>
	<a href="<?php the_permalink() ?>"><?php image_attachment(image, 512, 200); ?></a>
<?php }else{ ?>
	<a href="<?php the_permalink() ?>"><img src="<?php bloginfo('template_url');?>/images/default-post-image.gif" alt="Post Image" /></a>
<?php } ?>

If you don't understand what this code is doing, let me put it simply. When all is said and done, the output of the above code will be extremely similar to:

<a href="#"><img src="images/image.png" alt="Image" /></a>

Basically, what we're doing here is using a variable called "thereisimage" to check if the Custom Field key "image" has a value associated with it. If there is no value, there is no image. Now, we don't just want to display nothing, do we? That's why the "else" is there.

The "else" displays a default image if the post doesn't have one associated with it already. I'm assuming with this code that you have an image called default-post-image.gif in the /images/ folder of your theme folder.

Also worth noting is that one line of code at the end:

<li class="clear s3sliderImage"></li>

It is necessary to have one last LI tag at the end of everything that has a class of "clear" applied to it. If this isn't here, the plugin will fail. Don't worry, in the next step we'll go over all of the CSS.

The rest of the code is self explanatory. In it, we used some of the common WordPress php snippets to call for things like the post permalink, title, author, and date published. Not hard, right?

The last thing to do here is to open up functions.php and paste this in there somewhere:

/*Custom Field Images*/
function image_attachment($key, $width, $height) {
	global $post;
	$custom_field = get_post_meta($post->ID, $key, true);
 
	if($custom_field) {
		echo '<img src="'.$custom_field.'" alt="" width="'.$width.'" height="'.$height.'" />';
	}
	else {
		return;
	}
}

This creates the image_attachment function, which we use to retrieve and apply the image to the post. No need to modify anything here.

Step 4 - The CSS

Alright, if you're still with me so far, you're pretty much there. I'm going to simply copy and paste the code that the plugin creator has up on his website, as he has it well documented, so it's very easy to understand. Just put this somewhere in your CSS file:

#s3slider {
   width: 400px; /* important to be same as image width */
   height: 300px; /* important to be same as image height */
   position: relative; /* important */
   overflow: hidden; /* important */
}
 
#s3sliderContent {
   width: 400px; /* important to be same as image width or wider */
   position: absolute; /* important */
   top: 0; /* important */
   margin-left: 0; /* important */
}
 
.s3sliderImage {
   float: left; /* important */
   position: relative; /* important */
   display: none; /* important */
}
 
.s3sliderImage span {
   position: absolute; /* important */
   left: 0;
   font: 10px/15px Arial, Helvetica, sans-serif;
   padding: 10px 13px;
   width: 374px;
   background-color: #000;
   filter: alpha(opacity=70); /* here you can set the opacity of box with text */
   -moz-opacity: 0.7; /* here you can set the opacity of box with text */
   -khtml-opacity: 0.7; /* here you can set the opacity of box with text */
   opacity: 0.7; /* here you can set the opacity of box with text */
   color: #fff;
   display: none; /* important */
   top: 0;
 
   /*
       if you put
       top: 0; -> the box with text will be shown at the top of the image
       if you put
       bottom: 0; -> the box with text will be shown at the bottom of the image
   */
}
 
.clear {
   clear: both;
}

Congratulations

That's it. At this point, you should have a functioning post carousel working on your theme. Give yourself a pat on the back.

Like I said at the beginning of this post. This jQuery plugin can be used for dozens of things on a WordPress theme. Some things that come to mind are a featured post display, a picture gallery, images of your commentators gravatars. Get creative!

If you liked this post, stay updated. Follow me on Twitter or subscribe to our RSS Feed via email.

Post Tags: , , ,

Related Posts

Like this post? Spread it!