*( -_-)

How I got jQuery Quicksand working with WordPress

April 5th, 2010 by



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


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.


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 ''; 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){
    		  $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.


    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
      // 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.


    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.


    Coming soon.


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


    Thanks for reading!

    • http://Website Name (required)

      What does this quick sand plugin do?

    • http://www.facebook.com/people/Tom-Procter/503508163 Tom Procter

      It’s the plugin that I used to create the animation effect between the categories on this site. Just a cool bit of jQuery really…

    • http://Website vox

      hi, thanks for this tutorial, is the only resource i find!

      I follow your tutorial and i get the categories and the post rendered correctly, but when i click the category the jquery function doesn’t trigger and since i have the slug of the category in the href link of the rendered category it goes to a 404 not found.

      you have a lot of code in this tutorial and maybe i´m not putting in in the right file.

      Can you tell me what codes goes in what files?


    • http://www.bloghuts.com/ cryoffalcon

      well i am using quicksand, i want to use tool tips in it, but i am facing problem due to callback code that i am not able to implement, this is the place where quicksand is present and also told about tooltips usage with it, well he has not explained it in detail as expects people to know jquery before using it. http://razorjack.net/quicksand/docs-and-demos.html
      the code which is saying to use is this
      $(“#content”).quicksand($(“#data > li”),
      duration: 1000,
      }, function() { // callback function
      $(‘#content a’).tooltip();

      i don’t know where to place this code and how as i don’t know jquery, and if this code is to be place in tooltips script then where to place in it and how, e-g i might use this one
      then in this code where to put the above code.
      If its not possible with the above tooltip then i am ready to use any tooltip which can display picture in it.
      thanks for reading it and giving me time, please help me as i know for you jquery kings this is not a issue, but is a issue for me who is dumb. lol
      take care.

    • greencode

      Great use of Quicksand on your site. I’ve been wanting to do a portfolio section using Quicksand for a while now but get a little bit lost with all of this! Is there any way that you could also post your grid-ajax-call.php and any other files relevant to this tutorial available for download. So I can run through your tutorial with those files in full view?

    • greencode

      Sorry I also meant to ask for a downloadable “grid-post.php” file. I would totally understand if you weren’t prepared to add these as downloads on your site though. Thanks in advance.

    • http://twitter.com/tomprocter Tom Procter


      I will be releasing my theme for download soon, this will contain all the files you’ll need to have a go yourself. I hope this is ok :)

      Thanks for the nod too, it’s much appreciated!

    • Duke

      Thanks for writing this.. but it is quite confusing.. some stuff it’s not clear at all where to place it, or if we need to replace/customize something in particular.. so yeah, it’s all great but no way to make it work.

    • Anonymous

      I will revise the tutorial soon to try and make it a little easier to follow as soon as possible. Sorry about the confusion :( … (including anyone else that has struggled too, sorry guys!)

    • Duke

      Thank you! That’s pretty awesome of you! :)
      While you are at it, any idea on how to pull off something like this: I need quicksand for WordPress, for my portfolio.
      Now, i have 5 subcategories in my Portfolio category, and the posts inside them are about slightly different stuff, so I previously used tags to give an extra info about them.
      eg. sucategory is “Web Design”, and inside them I have 3 posts: 1 has tag “wordpress”, one has tag “drupal”, one has tag “flash”.
      What I’d really like to do is being able to not just display the posts from all and each the subcategories, but also have 1 additional filter to display only the posts with a specific tag (i can define these filters manually for each subcategory, that’s fine).

    • ns

      Duke— I found this post about using Quicksand with multiple filters: http://blog.adamroderick.com/2010/11/multiple-filters-with-jquery-quicksand/. But I have been struggling to figure out how to add it to Quicksand, and then add Quicksand to WordPress.

      Tom—Unfortunately I, like Duke, can’t follow your post. It would be really helpful if, everywhere you posted code, you named the file it should be a part of. And, where you are explaining separate code chunks within single files, it would be very helpful to show the changes in aggregate at the end of your post. I hope those are reasonable requests, because I’m really excited by the potential of the work you’ve offered!


    • Anonymous

      (Im Duke) I actually managed to make it work :)
      In the end I guess I didn’t really need filters, I might in the future though.
      I have no time whatsoever to write a post about it at this time, but I will as soon as I can and post the link.

    • Arne

      at the moment im just trying to implement this, but really having troubles with it. could you just post a zip with your final files so it is better to understand… that would be great – thanks!

    • Jack

      Hi, I was wondering if you could post your working files for this demo for download. I’ve run into a few issues that I can’t seem to resolve and was hoping if I saw your files it would help.

    • http://www.marevueweb.com/ Louis-Philippe Dea

      Hi Tom, first of all, thanks for this awesome tutorial. Great work!
      I was wondering if it could possible to make this code work with a custom post type using custom taxonomy to filter? Thx!

    • Anonymous

      where are you defining init_quicksand() ?

    • Miha

      I would love to see this kind of tutorial for WP which could filter the custom taxonomies…
      How come there is no plugin for this?

    • Karl M

      Can you post your demo files?

    • Arhangel1989

      hey, can you help me out with this ? i’m trying to do something similar and i have a hard time making it work

    • Aaron Rudd

      I’ve followed the instruction as best I can, several times over and still having issues.

      Could you post your files for download?
      Thanks so much!

    blog comments powered by Disqus