Tutorial: Using jQuery Masonry with WordPress

Need help implementing Masonry? Hire me at Microlancer.

This is a short tutorial on integrating Masonry, the jQuery layout plugin, with your WordPress site. We will try to use that jQuery plugin to show a list of posts in a neatly stacked layout, similar to the one I have down here. Here’s an explanation about Masonry, from it’s home page:

Think of it as the flip side of CSS floats. Whereas floating arranges elements horizontally then vertically, Masonry arranges elements vertically then horizontally according to a grid. The result minimizes vertical gaps between elements of varying height, just like a mason fitting stones in a wall.

Here’s a visual explanation, which I took and edited to fit my layout. Pay attention to the numbers, which shows the order of the elements in your HTML code:

Understanding Masonry’s Behaviors

Using Masonry itself is pretty simple, but if it’s the first time you’re using it there can be some surprising behaviors, especially regarding element spacing. Let’s talk about that first.

Masonry allows for two different cases. First is where all elements have the same width, and you should use this:

$('#container').masonry({ singleMode: true });

The second case is where your elements have differend widths. Use:

$('#container').masonry({ columnWidth: 200 });

Where columnWidth is the width of the grid (in pixel). Masonry will then follow these two rules:

  1. Total element width = CSS width + padding-left + padding-right + border-left-width + border-right-width + margin-left + margin-right
  2. When using columnWidth, then all elements must be placed horizontally at an increment of columnWidth (e.g. for columnWidth: 200, elements will start at 0 or 200 or 400 pixels and so on). This might not be intuitive and does not work like CSS float:

    The first element has a total width of 190px and margin-right is 0. At the same time the second element has 0 margin-left, so you will probably expect both to stick to each other. However, since the columnWidth says 200px, then the second element is pushed further and starts at 200px instead.

    That will not be the case if we only have one width, though. The next element will be placed right next to the previous one according to the margin between both.

WordPress + Masonry

Okay, coding time. We’ll try to recreate my Latest Links area where all elements have the same width. First we enqueue jQuery and call the Masonry JS script in the theme’s header.php file.

<?php wp_enqueue_script('jquery'); ?>
<?php wp_head(); ?>
<script language="javascript" type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery.masonry.min.js"></script>

Make sure that wp_enqueue_script appears before wp_head, and the script call appears after it. Here’s a more detailed article on how to correctly enqueue jQuery in WordPress. My Masonry JS is located in a /js folder, yours might be different.

Next, we decide how the HTML will be structured. Mine’s like this:

<div id="linky"> 
  <div class="boxy"> 
    <!-- post content -->
  <div class="boxy"> 
    <!-- post content -->
</div> <!-- #linky -->

Pretty simple. “Linky” will be the container div that will call the Masonry function, and “boxy” will be the elements that will be stacked together. The CSS is where it’s important, you want to make sure the container width and the total element widths match. For example, if you want to have four columns of elements, each having a width + padding of 190px and a margin-right of 10px, then the container will be 200 x 4 = 800px:

#linky {
  width: 800px;
  #linky .boxy {
  width: 170px;
  padding: 10px;
  margin-right: 10px;
  margin-bottom: 10px;

Below is my PHP to generate the HTML, I’m using WP_Query to specifically fetch the latest 15 posts from my Links category:

<div id="linky">
      $linksPosts = new WP_Query();
  <?php while ($linksPosts->have_posts()) : $linksPosts->the_post(); ?>
  <div class="boxy">
    <div class="read">
    <h4><a href="<?php if(get_post_meta($post->ID, "url", true)) echo get_post_meta($post->ID, "url", true); else the_permalink(); ?>"><?php the_title(); ?></a></h4>
      <?php the_content('Read the rest of this entry &raquo;'); ?>               
  <?php endwhile; ?>

Note that since Masonry saves a lot of space compared to regular floats, you will usually need plenty of elements at once to fill your container (hence 15 in my case).

Now that everything is in place, the last thing to do is to add the Masonry function, preferably right after the script call in header.php:

<script language="javascript" type="text/javascript" src="<?php bloginfo('template_url'); ?>/js/jquery.masonry.min.js"></script>
<script type="text/javascript">
  $('#linky').masonry({ singleMode: true });

And we’re done. Scroll down a little bit (or click here) to see an example; the container and element widths are different from the example CSS above, but you get the general idea.


Need help implementing Masonry? Hire me at Microlancer.

Latest Links More →

Classy Plugins

Eric Mann uses classes in his non object-oriented WordPress code. Here’s why.

Playing Nice with the “the_content” Filter

This great article could be useful if for some reason you have a need to filter the_content in your theme.

Google Goes After Links In WordPress Themes

New post from the Search Engine Roundtable: Someone “…received a response from Google to a reconsideration request that the only way his site will be reincluded in Google is if he removes all or most of the links in those WordPress themes.” The problem is that those links are in the form of sponsored links on footer (a practice I saw a lot in the past, not so much in the present).

I don’t think it will be easy, or even possible, to do what Google requested. If a theme contains an upgrade notification feature it might be possible to do, but even then the users might choose not to upgrade.

Secondly, if this is true, I wonder whether Google differentiates between credit links (“Designed by…”) and sponsored links. I would say they should, but then again I’m not a SEO guy.

Theme Options Gallery

New favorite blog: Theme Options Gallery by Konstantin Kovshenin, discussing “the best (and the worst) theme options screens around”. Loving the in-depth article and discussions already available there.

Dive into Responsive Prototyping with Foundation

Pretty safe to say that if it shows up on A List Apart, it’s going to be the de facto standard. Time to learn some Foundation.

Google HTML/CSS Style Guide

Couple of days ago we got Starbucks’ style guide, and now here’s another by Google. I think the interesting thing is the rule to “\[o\]mit the protocol from embedded resources“. So instead of typing <script src="http://www.google.com/js/gweb/analytics/autotrack.js"></script>, they recommend to type <script src="//www.google.com/js/gweb/analytics/autotrack.js"></script> instead (without the http part). Never heard of that before.

“I Woke Up but My Server Wasn’t There”

Robb Shecter’s WordPress site got popular overnight thanks to Reddit and went down immediately. The interesting aspect is that the site was new and it’s on a relatively high-powered server. The author then found that the theme he used in particular was doing too many (47!) server requests at a time, and the site ran along very well after switching back to Twenty Eleven.

I think it’s an important read for any theme developers out there.

Read the story here

Modern Web Development – Part I: The Webkit Inspector

A superbly detailed article, part one of a series about web development toolchain.

Crayon Syntax Highlighter plugin

I’ve always been on the hunt for that perfect syntax highlighter plugin. Currently I’m using WP-Syntax, which does its job very well. However I’ve just found this plugin called Crayon Syntax Highlighter, which could be a good contender for the best WordPress syntax highlighter plugin out there.

It looks good, and I like the little toolbar on top of the code box, with the small icons. Additionally, it also offers a lot of customization options. Lastly, it seems to support the same pre tags to wrap the code, similar WP-Syntax, so if I do make the switch, my old codes will still be highlighted correctly.

Starbucks Style Guide

The Starbuck website has its own style guide, accessible for public. I think its a neat idea, wouldn’t it be cool if themes have their own style guide? Pretty sure it will be helpful both to users or developers alike, if time consuming to write.

Also, I wonder what they use for the various toggles panel on the top right corner like on this page. It shows background, baseline, boxes, can be used to change windows size as well. Looks like it’s custom coded, imagine how super useful it can be if it’s a jQuery plugin.

NHP Theme Options Framework

I love theme options frameworks. And I want you guys to check this new framework called NHP. It passes my “does its UI look like the rest of WordPress enough?” test (screenshots here), it has tons of field types, and even offer validations, too.

Can’t wait to test and probably use it too in my to-be-released theme hint hint

What Dev4Press thinks WordPress needs…

This post at Dev4Press outlines what MillaN, its author, thinks would be a necessary addition to WordPress.

Based on the comments, it appears that a lot of people agree with this list. Some of the items mentioned can be achieved with plugins (e.g Tax Meta Class to add meta data to taxonomy items, Custom Post Types Relationships for, well, creating custom post type relationships), so expect there to be a bunch of debates about what should and shouldn’t go to the core.

I like his list, but I disagree with his assessment that we don’t need new core themes. We do, especially to bring about the standard for how a theme options should be designed. This is the aspect that desperately needs to be standardized. Different theme companies and individual theme designers have their own idea of how the theme option UI should look, and it’s hurting the users.

Upgrading from WordPress 1.5

I recently spotted this interesting Ask Metafilter thread where user gd779 tries to find a way to upgrade his old, WordPress 1.5 install. One of the answer is pretty detailed:

I think the right approach is going to be:

  1. Do a full backup of your WordPress files
  2. Do a full database backup (mysql dump using phpMyAdmin or similar)

Then, from your 1.5.2 install:

  1. Upgrade to 2.0
  2. Upgrade to 2.5.1
  3. Upgrade to 3.0
  4. Upgrade to 3.3.1

It is quite fascinating thinking about the solution to this. There’s an official Codex page called Updating WordPress, but it doesn’t seem to go that far back in time.

Smashing Special: What’s Going On In The WordPress Economy?

Siobhan McKeown wrote this awesome, birds-eye view of the whole WordPress economy. Make sure to read this two-part article so you know what’s up with WordPress and identify what opportunity lies ahead.

I agree with Matt’s prediction on that article:

I think the next big opportunity is around agencies and consulting—there will be five to six companies as large as Automattic, just providing high-end consulting and services to the large customers who are adopting WordPress en masse.

Start with Part I of the article.

Automatic responsive images for WordPress

The one issue with creating responsive web design is in displaying images, especially getting the most appropriate size in a particular screen size. One solution for it is the Responsive-Enhance jQuery plugin. It works by loading small-sized images by default, then checks the screen size and loads the bigger version if necessary.

According to its creator, Josh Emerson:

This results in a faster perceived page load speed, but a slower actual speed. I’m happy with this solution as I care more about perceived speed than actual speed.

This tutorial by Keir Whitaker takes the whole thing further by teaching us how to apply Responsive-Enhance in WordPress.

The WordCamp Central Site Redesign

The WordCamp Central has been redesigned, now sporting pleasant shades of blue. I particularly like the individual WordCamp page like this one for San Francisco, which features date, location, and archive links to past WordCamps there.

A little peek under the hood shows that the site now uses a Twenty Ten child theme called “WordCamp Central 2012”. The site uses a plugin called WP Event Ticketing for ticketing purposes, and WP Super Cache for speed.