jFlow is a powerful jQuery plugin used to generate featured slide areas in websites. They are brilliant for featuring important articles in your blog, but integrating it into WordPress can be tricky. This tutorial will explain how to take the difficulty out of it.

One of the most popular features to add into a WordPress theme (or any other site design) seems to be the featured slider. That is, of course, a javascript or flash run slider that features an image and/or excerpt from a set of posts. I’m going to show you how to use jFlow, one of the best javascript sliders in my opinion, to add a featured post slider into a WordPress theme.

Getting The Scripts

First we need to get our scripts. First we need jQuery, but this all depends on whether or not the theme you are editing/creating already includes jQuery or uses WordPress’ built in version. If you view your page souce & you can’t find a script tag pointing to jQuery you don’t have to worry about it & you can download the latest version of jQuery from here.

Unfortunately the person who maintained jFlow had their blog hacked recently so there is currently only a few scattered websites that you can download jFlow from. However I’m offering the version I have for download. It is the latest version & also includes an edit that pauses the slider on hover. You can download it here. If your browser opens it, just hit ctrl+S and save it.

Starting Off

First thing you need to do is attach jQuery & jFlow. Again depending on whether or not you already have jQuery attached can play havok with jFlow. If you are sure you don’t have jQuery already attached go ahead an attach it and jFlow using the standard method:

<script type="text/javascript" src="<?php bloginfo('stylesheet_directory'); ?>/js/jquery-1.3.2.min.js"></script>
<script type="text/javascript" src="<?php bloginfo('stylesheet_directory'); ?>/js/jquery.flow.1.2.auto.js"></script>

If you already have jQuery attached then it can be tricky to sort out. In my case, as jQuery is already attached to my theme, I have to call all jquery using jQuery() instead of the standard $() mainly because no conflict has been called. It probably shouldn’t interfere, but try as I might I have not been able to get jFlow to work without using the already attached version & it’s no conflict operator. If you have this problem though I would advise replacing all the $‘s with jQuery.

jFlow HTML

First we are going to layout the HTML that jFlow uses to create the slider. Then we’ll add the CSS & then the PHP to make jFlow work dynamically. That way, while it will take longer, it will be easier to follow what is going on. So onto the HTML. Here is the standard jFlow HTML markup:

<div class="jflow-content-slider">
  <div id="slides">
    <div class="slide-wrapper">
      <div class="slide-thumbnail">
	<img src="/path/to/image" />
      </div>
      <div class="slide-description">
        Random Text
      </div>
      <div class="clear"></div>
    </div>
  </div>
  <div class="clear"></div>
  <div id="myController">
    <span class="jFlowPrev">Prev</span>
    <span class="jFlowControl">1</span>
    <span class="jFlowNext">Next</span>
  </div>
</div>

This is the standard HTML markup I have seen used for jFlow. I am going to use a slightly different markup for my example, which you can see later. The only main difference is that there is no slide-description container in the markup I’ve used.

jFlow CSS

I haven’t really found a standard CSS for jFlow, but here is the CSS I am using in my example:

.jflow-content-slider { position:relative; padding: 5px; background:#000; width:560px; height:275px; }
#jFlowSlide{ background:#DBF3FD; font-family: Georgia;}
#myController { font-family: Georgia; padding:2px 0;  width:110px; background:#000; position:absolute; height:276px; top:4px; left:0; z-index:1000; }
#myController span.jFlowSelected { background:#ddd; margin-right:0px; }
#slides { float:left; width:560px; }
.slide-wrapper { padding: 0px; }
.slide-thumbnail { width:560px; float:left; }
.slide-thumbnail img {max-width:560px; }
.slide-details { width:0px; float:right; margin-left:10px;}
.slide-details h2 { font-size:1.5em; font-style: italic; font-weight:normal; line-height: 1; margin:0; }
.slide-details .description { margin-top:10px; }
.jFlowControl { color:#FFF; cursor:pointer; padding-left:5px; padding-right:5px; padding-top:4px; padding-bottom:4px; display:block; }
.jFlowControl:hover, .jFlowPrev:hover, .jFlowNext:hover { background: #ddd; }
.jFlowPrev, .jFlowNext { display:none; }

It includes most, if not all, of the elements you can alter using CSS. I say that you can alter because some of them will be altered by inline styles, by jFlow, which cannot be overridden because of the CSS hierarchy.

Integrating PHP Into jFlow’s HTML Markup

Here we go, the interesting bit. This bit can sometimes be difficult to follow it you are just starting out with WordPress, but please bare with it. We are going to have 4 posts show from a category called ‘featured’, we are only going to show an image. We are also going to show a smaller thumb of the images instead of numbers in the controller, the part you click to jump to a certain slide. Anyway here we go:

<div id="slides">
  <?php
  $feature = new WP_Query('category_name=featured&posts_per_page=4');
  $post_cache = array();
  if($feature->have_posts()) :
    while($feature->have_posts()) :
      $feature->the_post();
      $post_cache[] = $feature->post;
  ?>
        <div class="slide-wrapper">
	  <div class="slide-thumbnail">
	    <img src="<?php bloginfo('stylesheet_directory'); ?>/timthumb/timthumb.php?src=<?php the_attached_image('img_size=large&img_tag=false'); ?>&w=560&h=275&zc=1" width="560" height="275" />
	  </div>
	  <div class="clear"></div>
	</div>
  <?php
    endwhile;
  endif;
  ?>
</div>
<div class="clear"></div>

Ok, let’s go throught that a little. First we create a new query. We then create a blank array, this is a part for the thumbnails later. We start a standard loop, just after that we store the current post in the array we created. I only want an image to show so I’m using my plugin the attached image along with timthumb to resize the image. Then we close the loop.

Next we go onto the controller section. As I said before I don’t just want a numbered list, I want to show a small thumbnail version of the image. It’s actually very similar to gamespot.com’s except for the fact that their version is flash. Here is how to do that:

<div id="myController">
  <span class="jFlowPrev">Prev</span>
  <?php
  foreach($post_cache as $post) {
  ?>
    <span class="jFlowControl"><img src="<?php bloginfo('stylesheet_directory'); ?>/timthumb/timthumb.php?src=<?php the_attached_image('img_size=large&img_tag=false'); ?>&w=100&h=60&zc=1" width="100" height="60" /></span>
  <?php
  }
  ?>
  <span class="jFlowNext">Next</span>
</div>

Here is what is happening here. We open the controller div, although I don’t want next & prev we have to leave them or it will break jFlow. How do I get rid of them? Well that is what the display:none; is for in the CSS above. Next we loop through each post in the array we created before & place it back into WordPress’ global $post variable. This will allow the attached image to grab the image. If you wanted to use WordPress functions like the_content(); you would probably have to call setup_postdata($post) just after the foreach loop starts, but be aware that I haven’t tried it.

jFlow Init

Finally we need to write the code to initialize jFlow. It’s looks like this:

//This needs to be between <script></script> tags
$(document).ready(function(){
	$("#myController").jFlow({
		slides: "#slides",
		controller: ".jFlowControl", // must be class, use . sign
		slideWrapper : "#jFlowSlide", // must be id, use # sign
		selectedWrapper: "jFlowSelected",  // just pure text, no sign
		auto: true,		//auto change slide, default true
		width: "560px",
		height: "275px",
		duration: 400,
		prev: ".jFlowPrev", // must be class, use . sign
		next: ".jFlowNext" // must be class, use . sign
	});
});

Please not that duration is NOT the length of time before the silde changes, it is how long it takes for the sliding transition to take. If you want to change the time before the slide changes you have to edit the JS file. On line 149 there is the number 3000 change that to the time you want. Remember that it is in milliseconds.

That should be it, if all has gone well you should end up with something that looks like the example on this page. It’s a little ugly because of the images not being big enough, but you get the idea.

Remember you can change this anyway you want as the basic idea is the same for any type of slider using jFlow. It just requires a bit of experimentation, remember to be brave, keep back ups and you can do pretty much anything with jFlow. let me know if you notice any mistakes, have any problems or need some help. Thanks for reading.