How I got jQuery Quicksand working with WordPress

Updated

Introduction

I have had way more interest in this than I was planning on having, and there’s been quite a lot of confusion too, so I’m going to rewrite this post… and hopefully make it easier to follow.

In this tutorial I am going to try and explain how to implement the very cool Quicksand JS Library into a WordPress theme. At the end of the tutorial, I have included the whole theme that I am running on this site, so you can just skip to the end and jump straight in if you prefer.

If you’re like me and sometimes want to know what is going on a little more, then here is a break down of how things work.

edit: I’m also going to comment the code this time round!

The Structure

1. Grid of posts
2. Navigation made up of categories
3. Javascript listener that will load the grid with new posts using ajax.
4. PHP script that gets the requested posts and returns them to the ajax call.

Essentially, we could build the theme from four files (plus the plugin files), these would be as follows:
1. index.php (html markup)
2. loop-quicksand.php (wordpress loop with our current posts)
3. scripts.js (listener and ajax call)
4. request.php (the php file that renders the new grid)

Further Information about the files

index.php

This simply loads up the latest posts just like a normal wordpress theme, and structures them into a UL grid. The code for this file is very simple:

// Start the grid HTML
echo '
';

// Render the grid with the current posts
get_template_part( 'loop', 'quicksand' );

// Close the UL
echo '

';

As you can see, we use a standard WordPress function to call the Quicksand loop rather than the default WordPress loop.

loop-quicksand.php

If you look at the standard WordPress loop, you will see that it is simply a While loop that structures the posts into HTML for the theme. Our custom loop file is not far from the original WordPress loop, it simply structures the HTML so that we can manipulate it with Quicksand. So here’s the code I use on my theme:

// Loop through the posts and create the grid
while (have_posts()) : the_post();
    echo '
';
    echo '
'.the_title().'

';
    echo '

';
endwhile;

We don’t include the UL in this part as we want to populate the grid with different items, and ideally, we would like to reuse this custom WordPress loop that we have made.

You will notice that on the LI items of the grid, I use an attribute called “data-id”. This is a unique ID reference that is required by the Quicksand plugin. So I simply load the post ID in this with the prefix “post-”.

One more thing to note is that I run a custom function called “return_grid_class()”, this requests the category nicename and returns it as a string. For reference purposes, the function I use is as follows:

	function return_grid_class(){
	  global $post;
	  $class = "";
	  $categories = get_the_category($post->ID);
	  foreach($categories as $obj){
		if($obj->category_nicename){
		  $class .= $obj->category_nicename.' ';
		}
	  }
	}
	return $class;

Sometimes you’re posts might be in multiple categories, so this functions builds up a string made up of the category nicename’s before returning it.

scripts.js

The functionality of this file is to repopulate the grid with new posts when a user clicks on the categories from the menu. I guess this is the cool bit really as it contains the ajax call. Here’s the code:

// Init jQuery
$(function() {
  // Setup listener on all the links in the menu
  $('#categories a').click(function(ev){

  // Prevent the default behaviour of the link
  ev.preventDefault();

  // Request the new posts from request.php
  $.post( 'http://[enter the absolute URL to your request file]/request.php',
    { category: $(this).html() }, function(data){ init_quicksand( "#content", data ); }
  );
});
});

Let’s look at what is actually going on here:
1. As listener is setup for the click event (ev) on a category link
2. The normal html ev is disabled
3. A JS ajax call is made to our request file (request.php)
4. The data passed to the request file is the category. We get this from the HTML of the link that has been clicked.
5. Finally, the returned data is passed to the init_quicksand function and the magic happens.

request.php

When the AJAX call requests the new posts, it looks to a PHP file for the data. This file is called request.php and looks like this:

  // Start the grid HTML
  echo '
';

  // Include the WordPress core files
  define('WP_USE_THEMES', false);
  include '../../../../../wp-blog-header.php';

  // Run query_posts to get the posts requested from the ajax call. The category
  // name will be in the $_POST array. Set posts_per_page to -1 so that there is
  // no limit on how many posts are shown.
  if( $_POST['category'] == "All" ){
    query_posts( array ( 'posts_per_page' => -1 ) );
  } else {
    query_posts( array ( 'category_name' => $_POST['category'], 'posts_per_page' => -1 ) );
  }

  // Run the loop to out the HTML with the latest posts
  get_template_part( 'loop', 'quicksand' );

  // Finally, reset the query once we are finished and close the UL
  wp_reset_query();
  echo '

';

The output of this file is passed back to the scripts.js and then processed through the init_quicksand function, so all we have to do is basically build a new grid of posts. The output from this file should look the same as the output from index.php. With this in mind, if you look back at index.php you will notice that we call the get_template_part() function to get the grid of posts. In the request file, we do the same, only before we do the call, we build up the wordpress $post array with new posts from the requested category… phew.

Downloads

Coming soon.

Credits

Quicksand and all credits go to Razorjack so please visit the site and spread the word!

http://razorjack.net/quicksand/

Thanks for reading!