Instant jQuery Masonry How-to

To perform the steps listed in this recipe, we will need a text editor, a browser, and a copy of the Masonry plugin. Any text editor will do, but my browser of choice is Google Chrome, as the V8 JavaScript engine that ships with it generally performs better and supports CSS3 transitions (as you'll see later in the book), and as a result we see smoother animations when resizing the browser window. We need to make sure we have a copy of the most recent version of Masonry, which was Version 2.1.08 at the time of writing this book. This version is compatible with the most recent version of jQuery, which is Version 1.9.1. A production copy of Masonry can be found on the GitHub repository at the following address:

https://github.com/desandro/masonry/blob/master/jquery.masonry.min.js

For jQuery, we will be using a content delivery network (CDN) for ease of development. In the code bundle for this book, open the basic single-column HTML file to follow along.

Using jQuery, we select our Masonry container and use the itemSelector option to select the elements that will be affected by Masonry. The size of the columns will be determined by the CSS code.

Using the box model, we set our Masonry items to a width of 90 px (80-px wide, with a 5-px padding all around the item). The margin is our gutter between elements, which is also 5-px wide. With this setup, we can confirm that we have built the basic single-column grid system, with each column being 100-px wide. The end result should look like the following screenshot:

In the code bundle for this book, open the 2-Multicolumn.html file in your preferred text editor to follow along.

Since we are being a little festive with the background colors, we can see that by setting a specific column width, the elements line up nicely across the defined columns (which you can see in the next screenshot). By setting multiple column classes, we can really mix it up and have fun with Masonry when we have lots of content.

In this example, we kept the size of the elements defined by the CSS divisible by the column width we set in Masonry. If you set the column width to a size that isn't a multiple of the base column width, Masonry becomes inefficient because there is wasted space between the column width defined in CSS and the column width defined in Masonry. You can play around with various widths to understand how it works, but this is why it is important to know how CSS and Masonry work together.

In the code bundle for this book, open the 3-images-loaded.html file in your preferred text editor to follow along.

The imagesLoaded plugin works by waiting until all the images have been loaded by the browser and then triggering Masonry. The result should look like the following screenshot:

If you do not use the imagesLoaded plugin, you will notice that the images load on top of each other in the same corner in the browser, as shown in the next screenshot. This is because Masonry was running before the images loaded completely, so it tries to organize a set of empty elements it doesn't know the size of. When imagesLoaded is used with Masonry, the script waits until all of the images have been loaded before triggering Masonry.

There are some other alternatives to using the imagesLoaded plugin. For instance, we can assign each image a width and height property using the inline dimensions. Once these values are assigned to the elements, Masonry determines their spacing. Depending on how the site is being built, it might be tedious to ensure that all those image elements have height and width properties assigned.

The last alternative is to use $(window).load(). While this method isn't particularly efficient, as it can result in a potentially longer wait time, it does work; it waits until all the assets (such as images and media) are loaded into the window before triggering Masonry.

<script>
  $(window).load(function() {
    $('#masonry-container').masonry({
      itemSelector : '.masonry-item',
    });
  });
</script>

In the code bundle for this book, open the 3-images-loaded.html file in your preferred text editor to follow along. There is a lot of additional styling used for various types of elements, so I will only be going over what directly affects the use of Masonry.

Once again, we defined the columnWidth property and created a few CSS classes for the columns; inside the elements, we have various types of media, which were set using imagesLoaded. The result should look similar to the following screenshot:

In the code bundle for this book, open the 3-fluid-layout.html file in your preferred text editor to follow along.

In our CSS styles, we defined the width of the Masonry elements to be 24 percent of the container width [20% width + (x2) 1% margin + (x2) 1% padding]. In the highlighted part of the previous code snippet, we can see that we passed a function to change the width of the column to 25 percent (because the container width is considered to be 100 percent, and we divided it by four).

Multi-columns can be implemented in a fluid layout as long as they are a factor of the fluid container width. For instance, if we have a four-column container, we can set the width of a two-column class to 46 percent with 1 percent each for margins and padding—a total width of 49 percent. Once we decide whether or not to go with a fluid layout, we need to be consistent when using percent versus pixels so as not to mix them up.

In the code bundle for this book, open the 4-jquery-animation.html file in your preferred text editor to follow along.

By setting the isAnimated option to true, Masonry will automatically animate rearrangements using the built-in jQuery support. Now if we manipulate the width of the container by shrinking the browser window, we can see the animation in action.

The following screenshot was taken while the animation was happening:

We can include additional jQuery animation options using the animationOptions option. Some of the options include duration, easing, queue, specialEasing, step, and complete. Additional documentation for these options can be found in the jQuery documentation on the official jQuery website at http://api.jquery.com/animate. Some of these options can also be extended by using additional jQuery plugins.

<script>
  $(function() {
    $('#masonry-container').masonry({
      itemSelector : '.masonry-item',
      isAnimated: true,
      animationOptions: {
        duration: 500,
        easing: 'swing'
      }
    });
  });
</script>

In the code bundle for this book, open the 4-css-animation.html file in your preferred text editor to follow along. Also, if you have not been using Google Chrome or a browser that supports CSS3 transitions until now, be sure to use one while performing the steps listed under this recipe.

Instead of using jQuery, we assigned CSS3 transition properties to the Masonry elements. After Masonry is run, it assigns additional classes and inline styles to the elements; for example, it assigns the masonry class to the container and the masonry-brick class to the individual items.

We assigned the transition-duration property to all items, the container itself and the Masonry items inside it, so that all transitions will last for half of a second. We then assigned the height and width of the container and the left / right / top positions to transition-property. This means that whenever those values change, that is, the size of the container and the position of the Masonry items change, the transition effect will be applied to those changes.

Using CSS3 animations is great—they're efficient and they boost performance if the browser supports them. Luckily, if the browser doesn't support CSS3, we can use Modernizr and go back to using jQuery. Modernizr is a JavaScript library that detects the HTML5 and CSS3 features that are available in a user's browser, which is a great advantage.

To enable Modernizr, we will have to include the Modernizr script into our page and then add the isAnimated option to the Masonry script with the value !Modernizr.csstransitions, as shown in the following code snippet:

<script src="js/modernizr.csstrans.js"></script>
<script>
  $(function() {
    $('#masonry-container').masonry({
      itemSelector : '.masonry-item',
      isAnimated: !Modernizr.csstransitions
    });
  });
</script>

This will detect whether CSS transitions are available in our browser; if not, we will go back to using jQuery animations. In the browser, we can view information about the DOM to see whether the CSS transitions and animations are enabled. In the following screenshot, we can see that CSS transitions are enabled in Firebug for Firefox:

As opposed to that, in the following screenshot we can see that CSS transitions are turned off in Internet Explorer 9; we need to use jQuery to enable transitions:

We will need an installation of WordPress, either local or on a server. In this demonstration, we will be using the version of WordPress that was most recent at the time of writing (WordPress 3.6) and modifying the Twenty Thirteen theme. Demo content has already been added, including categories, so we will be targeting the content of a specific category to apply Masonry to. The demo content being used in this example can be found under WordPress's theme-unit-testing page, located at the following URL:

http://codex.wordpress.org/Theme_Unit_Test

We did multiple things in this recipe, in the simplest way. To start with, we created a lot of demo content within the same category with an ID of 9. In content.php, we added the masonry-item class to each article if it was tagged in category 9 and if the current page had articles listed from that category. We did this by passing the class name into post_class(), which adds the masonry-item class to any existing classes that are applied to that article.

In category.php, we did pretty much the same thing. We added the masonry-container class to the content element, where posts appear if the category archive page is based on category 9. We also moved the header outside of the content area since it is not part of implementing Masonry and would break our page. Now we have a container and items we can apply Masonry to.

We created a JavaScript file that contains our Masonry script and we included the script by using WordPress's wp_enqueue_script() function, directing the source to the JavaScript folder in the theme; we then placed it in the footer with the other scripts by setting the last parameter set to true. To ensure that we are not running Masonry on every page, we put in another check to only load Masonry when on the category 9 archive page. When using the add_action() function, we set the last parameter to 20 to ensure that it loads after jQuery and that the core of Masonry has been loaded. After everything is completed, the result should look like the following screenshot:

We didn't need to load jQuery or Masonry because both are built into WordPress, making it really nice and easy. If we did need to, in WordPress, we would use the same wp_enqueue_script() method that we used earlier.

As with WordPress, we need a local or server installation of Drupal 7. At the time of writing this book, the version of Drupal used was Drupal 7.20, with the default Bartik theme. We need to download five modules: cTools, Libraries, jQuery Update, Masonry, and Views. We also need to download the Masonry plugin, and if we need demo content, we can download the Devel module. Once the modules are downloaded, place them in the /sites/all/modules directory.

After downloading, we will enable all of these modules, including the submodules Views UI and Masonry Views, and set jQuery Update to Version 1.7. Libraries and Masonry directories will not have been created yet, so create a folder named libraries in /sites/all, and then create a folder named masonry inside /sites/all/libraries. We will put the Masonry plugin in the /sites/all/libraries/masonry directory. Also, create some demo articles using Devel if no other content is available.

The Masonry module is essentially a Views plugin with Masonry built in. Views is a query builder that posts content in a container based on the provided settings. This makes it easy to set up a page or view with Masonry while having the ability to change the settings through a GUI. If we go back and look at the Masonry grid settings, we can see that we can select or deselect Masonry options such as turning on animations and adding extra gutter space.

We needed the other modules as Masonry is dependent upon them. Most importantly, we needed jQuery Update to upgrade the core Drupal version of jQuery to a version compatible with Masonry.

Using the default Bartik theme doesn't allow us to have a responsive mobile site. Switching our theme with a mobile-friendly version gives us the ability to enable animations and have a resizable grid. Some popular options include using the Bootstrap or Zurb Foundation's frameworks. To install, download Bootstrap from http://www.drupal.org and follow the instructions listed on the project page. Once the theme has been successfully enabled and set to default, we can watch Masonry animate while the browser window is resized.

In the code bundle for this book, open the 5-add-reload.html file in your preferred text editor to follow along. For this exercise, we will be using a small jQuery plugin called Placeholder.js to generate random text when adding new elements. Placeholder.js can be found at the following URL:

https://github.com/decabear/placeholderjs/blob/master/placeholder.min.js

For the first section, you can see that we're just running the ordinary Masonry script to set the Masonry items into the grid. We then assign a click event to the button we created and next bind an event handler that creates a new <div> class with the masonry-item placeholder class that get loaded with a random amount of text using Placeholder.js. Once the Masonry item is created, we use the jQuery append event to add the element to the end of the Masonry container; we then use the Masonry append method to apply the proper position to the appended item, which can be seen in the following screenshot:

Appending is great for adding content such as comments to the bottom of a page, but sometimes we need to add content to the top of the page. It is more than likely that this is a blog post or some other kind of time-sensitive material. We can easily switch the jQuery append method with the prepend method, which will insert our created content before all the other Masonry items. Note that we used the Masonry append method when appending an item (adding it to the end). If we use the jQuery prepend method instead of the Masonry append method, we need to use reload. This is because we don't know beforehand the size of the element that is being loaded in; so we reload all the elements to recalculate the alignment of the elements in the Masonry grid correctly. The result will look like the following screenshot:

In the code bundle for this book, open the 3-cornerstamp.html file in your preferred text editor to follow along.

After specifying which element is the corner stamp, Masonry will keep the element in the corner while moving all other items around it. There are a couple of things that will break the corner stamp, which you need to take note of. The code for the corner stamp elements cannot have the class used to identify Masonry elements, in our case masonry-item, which is why we identify it separately. In this example, we put the corner stamp in the top-right corner by floating the element to the right, which can be seen in the following screenshot:

If we want to put the corner stamp in the top-left corner, we can easily change the float property of the cornerstamp class from right to left.

In the code bundle for this book, open the 5-rtl.html file in your preferred text editor to follow along.

This is a fairly simple process. By default, when Masonry is setting the positions of items in the layout, it always starts from the left. For example, the inline style will look like this: style="position: absolute; top: 0px; left: 300px;". When isRTL is set to true, the positioning starts from the right instead. This is a very simple technique, yet very effective. The result should look like the following screenshot: