A better, and easier, grid loop

Don’t feel like coding? I built a plugin that does this for you.
See the Genesis Grid Loop plugin.

Note: This technique can be used by all WordPress themes. I’m proposing it as a replacement for the Genesis-specific grid loop, so aspects of this post might be Genesis-specific.

A popular request is to list posts in multiple columns. I do it on my blog, and do it often on my clients’ sites.

Genesis developed a Grid Loop, which you can utilize inside your Genesis themes for this effect, and is how this blog does it. While very useful, it can be difficult to set up. I believe this is because they combined two separate functions: what content to display (your query) and how to display it.

By breaking those two functions we can use another feature of Genesis, the column classes, to build grid loops easier. You can also copy that CSS to any WordPress theme and make it work too.

For this example I’ll be using a Gallery theme I recently built. On the archive pages, it displays posts in three columns. See the screenshot above, or click here) for an example.

Step 1: Multiple columns using post_class

The post_class filter lets us customize the classes applied to each post in the loop. Since I want this to only apply to archive pages, I’m placing it in archive.php.

/**
 * Archive Post Class
 * @since 1.0.0
 *
 * Breaks the posts into three columns
 * @link http://www.billerickson.net/code/grid-loop-using-post-class
 *
 * @param array $classes
 * @return array
 */
function be_archive_post_class( $classes ) {
	global $wp_query;
	if( ! $wp_query->is_main_query() )
		return $classes;
		
	$classes[] = 'one-third';
	if( 0 == $wp_query->current_post % 3 )
		$classes[] = 'first';
	return $classes;
}
add_filter( 'post_class', 'be_archive_post_class' );

The first line adds a class of ‘one-third’ to all posts. Then I grab the current post counter out of $wp_query, and if this is the first post ( 0 == $wp_query->current_post ) or if the remainder of the current post divided by 3 is zero (this tells us the current post is the first in a row), apply a class of “first” as well.

That’s it! You now have your content broken into multiple columns. If you want two columns, use ‘one-half’ and divide the current post by 2. If you want four columns, use ‘one-fourth’ and divide the current post by 4.

Step 2: Customize the Query

When I view the archive page now, it’s in three columns but it’s only displaying 10 posts. The last post sits by itself in its own row. I’m going to modify the main query to show 27 posts per page. You could use any number you want, just make sure it’s a multiple of columns. For more information on customizing the main query, see this post.

/**
 * Archive Query
 *
 * Sets all archives to 27 per page
 * @link http://www.billerickson.net/customize-the-wordpress-query/
 *
 * @param object $query
 */
function be_archive_query( $query ) {
	if( $query->is_main_query() && $query->is_archive() ) {
		$query->set( 'posts_per_page', 27 );
	}
}
add_filter( 'pre_get_posts', 'be_archive_query' );

This code must go in functions.php, since the main query runs before it reaches archive.php (it checks the query to figure out what template to load).

Even easier sitewide

If you’re using this for all listings of posts (home, archive, search…), it is even easier to set up. Put the post_class filter in functions.php so it runs sitewide, and add a conditional to check if it isn’t singular:

/**
 * Archive Post Class
 *
 * Breaks the posts into three columns
 * @link http://www.billerickson.net/code/grid-loop-using-post-class
 *
 * @param array $classes
 * @return array
 */
function be_archive_post_class( $classes ) {

	// Don't run on single posts or pages
	if( is_singular() )
		return $classes;

	$classes[] = 'one-third';
	global $wp_query;
	if( 0 == $wp_query->current_post || 0 == $wp_query->current_post % 3 )
		$classes[] = 'first';
	return $classes;
}
add_filter( 'post_class', 'be_archive_post_class' );

And instead of the function to customize the number of posts, go to Settings > Reading and tweak it there.

Advanced Example

The code snippet below (added to functions.php), modifies the blog’s homepage and archive pages to display 5 features and 6 teasers (in three columns) on the first page. On inner pages, it displays 0 features and 12 teasers (in three columns). It also updates the post image to use image sizes specifically created for features and teasers.

The first function, be_grid_loop_pagination(), is where we control the grid loop. Under the comment that says “Sections of site that should use grid loop”, you can modify that list to specify where you want the grid loop displayed. Right now it is running when is_home() or is_archive() is true. The second part, under the comment that says “Specify pagination”, is where you specify how many features and teasers to show on the homepage and subsequent pages.

The second function, be_grid_loop_query_args(), doesn’t require any customization from you. It uses the pagination information you added to the previous function to tell WordPress how many posts show up on each page.

The third function, be_grid_loop_post_classes(), applies relevant classes to each post. It’s adding a class of ‘feature’ to each feature post, and column classes to the teasers. The only thing that you’d need to change is the teasers sections if you want something other than three columns. Here’s what you’d need to change if you wanted two columns.

The fourth function, be_grid_image_sizes(), specifies the two image sizes. Change these to whatever size you’d like. If you don’t want images, you can leave out this function and the last one, be_grid_loop_image(). Also note that you need to have “Include Featured Image” checked in Genesis > Theme Settings > Content Archives.

The fifth function, be_grid_loop_image(), overrides the image size set in Genesis > Theme Settings > Content Archives with the image sizes we created in the previous function. No changes need to be made to this function.

The sixth function, be_fix_posts_nav() does as its name implies. The post navigation (Older/Newer, numerical links to posts pages…) uses $wp_query->max_num_pages to know how many pages there are, and this is based on the current page’s posts_per_page. So if you have less posts on your homepage than inner pages, the post navigation on the homepage will be off (this is noticeable if you’re using numerical links). This code changes the max_num_pages based on the grid args.

/**
 * Grid Loop Pagination
 * Returns false if not grid loop.
 * Returns an array describing pagination if is grid loop
 *
 * @author Bill Erickson
 * @link http://www.billerickson.net/a-better-and-easier-grid-loop/
 *
 * @param object $query
 * @return bool is grid loop (true) or not (false)
 */
function be_grid_loop_pagination( $query = false ) {

	// If no query is specified, grab the main query
	global $wp_query;
	if( !isset( $query ) || empty( $query ) || !is_object( $query ) )
		$query = $wp_query;
		
	// Sections of site that should use grid loop	
	if( ! ( $query->is_home() || $query->is_archive() ) )
		return false;
		
	// Specify pagination
	return array(
		'features_on_front' => 5,
		'teasers_on_front' => 6,
		'features_inside' => 0,
		'teasers_inside' => 12,
	);
}

/**
 * Grid Loop Query Arguments
 *
 * @author Bill Erickson
 * @link http://www.billerickson.net/a-better-and-easier-grid-loop/
 *
 * @param object $query
 * @return null
 */
function be_grid_loop_query_args( $query ) {
	$grid_args = be_grid_loop_pagination( $query );
	if( $query->is_main_query() && !is_admin() && $grid_args ) {

		// First Page
		$page = $query->query_vars['paged'];
		if( ! $page ) {
			$query->set( 'posts_per_page', ( $grid_args['features_on_front'] + $grid_args['teasers_on_front'] ) );
			
		// Other Pages
		} else {
			$query->set( 'posts_per_page', ( $grid_args['features_inside'] + $grid_args['teasers_inside'] ) );
			$query->set( 'offset', ( $grid_args['features_on_front'] + $grid_args['teasers_on_front'] ) + ( $grid_args['features_inside'] + $grid_args['teasers_inside'] ) * ( $page - 2 ) );
			// Offset is posts on first page + posts on internal pages * ( current page - 2 )
		}

	}
}
add_action( 'pre_get_posts', 'be_grid_loop_query_args' );

/**
 * Grid Loop Post Classes
 *
 * @author Bill Erickson
 * @link http://www.billerickson.net/a-better-and-easier-grid-loop/
 *
 * @param array $classes
 * @return array $classes
 */
function be_grid_loop_post_classes( $classes ) {
	global $wp_query;
	
	// Only run on main query
	if( ! $wp_query->is_main_query() )
		return $classes;
	
	// Only run on grid loop
	$grid_args = be_grid_loop_pagination();
	if( ! $grid_args || ! $wp_query->is_main_query() )
		return $classes;
		
	// First Page Classes
	if( ! $wp_query->query_vars['paged'] ) {
	
		// Features
		if( $wp_query->current_post < $grid_args['features_on_front'] ) {
			$classes[] = 'feature';
		
		// Teasers
		} else {
			$classes[] = 'one-third';
			if( 0 == ( $wp_query->current_post - $grid_args['features_on_front'] ) || 0 == ( $wp_query->current_post - $grid_args['features_on_front'] ) % 3 )
				$classes[] = 'first';
		}
		
	// Inner Pages
	} else {

		// Features
		if( $wp_query->current_post < $grid_args['features_inside'] ) {
			$classes[] = 'feature';
		
		// Teasers
		} else {
			$classes[] = 'one-third';
			if( 0 == ( $wp_query->current_post - $grid_args['features_inside'] ) || 0 == ( $wp_query->current_post - $grid_args['features_inside'] ) % 3 )
				$classes[] = 'first';
		}
	
	}
	
	return $classes;
}
add_filter( 'post_class', 'be_grid_loop_post_classes' );

/**
 * Grid Image Sizes 
 *
 */
function be_grid_image_sizes() {
	add_image_size( 'be_grid', 175, 120, true );
	add_image_size( 'be_feature', 570, 333, true );
}
add_action( 'genesis_setup', 'be_grid_image_sizes', 20 );

/**
 * Grid Loop Featured Image
 *
 * @param string image size
 * @return string
 */
function be_grid_loop_image( $image_size ) {
	global $wp_query;
	$grid_args = be_grid_loop_pagination();
	if( ! $grid_args )
		return $image_size;
		
	// Feature
	if( ( ! $wp_query->query_vars['paged'] && $wp_query->current_post < $grid_args['features_on_front'] ) || ( $wp_query->query_vars['paged'] && $wp_query->current_post < $grid_args['features_inside'] ) )
		$image_size = 'be_feature';
		
	if( ( ! $wp_query->query_vars['paged'] && $wp_query->current_post > ( $grid_args['features_on_front'] - 1 ) ) || ( $wp_query->query_vars['paged'] && $wp_query->current_post > ( $grid_args['features_inside'] - 1 ) ) )
		$image_size = 'be_grid';
		
	return $image_size;
}
add_filter( 'genesis_pre_get_option_image_size', 'be_grid_loop_image' );

/**
 * Fix Posts Nav
 *
 * The posts navigation uses the current posts-per-page to 
 * calculate how many pages there are. If your homepage
 * displays a different number than inner pages, there
 * will be more pages listed on the homepage. This fixes it.
 *
 */
function be_fix_posts_nav() {
	
	if( get_query_var( 'paged' ) )
		return;
		
	global $wp_query;
	$grid_args = be_grid_loop_pagination();
	if( ! $grid_args )
		return;

	$max = ceil ( ( $wp_query->found_posts - $grid_args['features_on_front'] - $grid_args['teasers_on_front'] ) / ( $grid_args['features_inside'] + $grid_args['teasers_inside'] ) ) + 1;
	$wp_query->max_num_pages = $max;
	
}
add_filter( 'genesis_after_endwhile', 'be_fix_posts_nav', 5 );

Bill Erickson

Bill Erickson is the co-founder and lead developer at CultivateWP, a WordPress agency focusing on high performance sites for web publishers.

About Me
Ready to upgrade your website?

I build custom WordPress websites that look great and are easy to manage.

Let's Talk

Reader Interactions

Comments are closed. Continue the conversation with me on Twitter: @billerickson

Comments

  1. Stefan Seifert says

    Thanks Bill!

    However I do not understand (php beginner) how this code will be able to create the rows.

    As where is the sense having classes like “thirst” etc. if (as an example) the first three post will not be inserted in a first row. The 4rd-6th in a second row etc.?

    I did some researches on the web but the many answers I found were not so reliable as it seems. Many many buts and ifs out there regarding this issue…

    Any clarification about this?

    I like your page by the way. Nice and clear.

    Best,
    Stefan

  2. Chris Mundy says

    Hi Bill,

    I’ve been using your grid on https://halfofmylife.com for some time and noticed recently it’s throwing an error. I went through and updated the code in the front page php file however at the bottom of the homepage grid it’s still displaying….

    Warning: call_user_func_array() expects parameter 1 to be a valid callback, function ‘minimum_grid_loop_helper’ not found or invalid function name in … /wp-includes/class-wp-hook.php on line 287

    Any suggestions??

    • Bill Erickson says

      Can you share the full code you added to your theme? My code above does not contain a function called minimum_grid_loop_helper().

      • Chris Mundy says

        Hi Bill,

        1. I fixed the error message by removing the code from front-page.php and functions.php

        2. the Minimum group helper I found in front-page.php. This is from the minimum-pro theme from StudioPress.

        //* Genesis grid loop
        function minimum_grid_loop_helper() {

        if ( function_exists( ‘genesis_grid_loop’ ) ) {

        genesis_grid_loop( array(
        ‘features’ => 0,
        ‘feature_image_size’ => 0,
        ‘feature_content_limit’ => 0,
        ‘grid_image_size’ => 0,
        ‘grid_content_limit’ => 250,
        ‘more’ => __( ‘[Read more]’, ‘minimum’ ),
        ) );

        } else {

        genesis_standard_loop();

        }

        }

        //* Run the Genesis loop

        3. I’ve introduced the advanced example from above to functions.php and undertook the modifications for image sizes and featured image sizes. The inner pages with the three columns show the featured image, however, the homepage, doesn’t show the images in the grid and teasers.

        Here’s the settings:

        /**
        * Grid Image Sizes
        *
        */
        function be_grid_image_sizes() {
        add_image_size( ‘be_grid’, 173, 130, true );
        add_image_size( ‘be_feature’, 720, 540, true );
        }
        add_action( ‘genesis_setup’, ‘be_grid_image_sizes’, 20 );

        /**
        * Grid Loop Featured Image
        *
        * @param string image size
        * @return string
        */
        function be_grid_loop_image( $image_size ) {
        global $wp_query;
        $grid_args = be_grid_loop_pagination();
        if( ! $grid_args )
        return $image_size;

        // Feature
        if( ( ! $wp_query->query_vars[‘paged’] && $wp_query->current_post query_vars[‘paged’] && $wp_query->current_post query_vars[‘paged’] && $wp_query->current_post > ( $grid_args[‘features_on_front’] – 1 ) ) || ( $wp_query->query_vars[‘paged’] && $wp_query->current_post > ( $grid_args[‘features_inside’] – 1 ) ) )
        $image_size = ‘be_grid’;

        return $image_size;
        }
        add_filter( ‘genesis_pre_get_option_image_size’, ‘be_grid_loop_image’ );

        4. The old code in functions.php for showing the images on the grid was this:

        //* Mods to homepage grid

        //* Add new image sizes
        add_image_size(‘grid-thumbnail’, 173, 130, TRUE);

        //* Add Search to nav Menu
        add_filter( ‘wp_nav_menu_items’, ‘theme_menu_extras’, 10, 2 );
        /**
        * Filter menu items, appending either a search form or today’s date.
        *
        * @param string $menu HTML string of list items.
        * @param stdClass $args Menu arguments.
        *
        * @return string Amended HTML string of list items.
        */
        function theme_menu_extras( $menu, $args ) {
        //* Change ‘primary’ to ‘secondary’ to add extras to the secondary navigation menu
        if ( ‘secondary’ !== $args->theme_location )
        return $menu;
        //* Uncomment this block to add a search form to the navigation menu

        ob_start();
        get_search_form();
        $search = ob_get_clean();
        $menu .= ” . $search . ”;

        //* Uncomment this block to add the date to the navigation menu
        /*
        $menu .= ” . date_i18n( get_option( ‘date_format’ ) ) . ”;
        */
        return $menu;
        }

        So to sum up, the homepage grid featured images aren’t showing.

        Thanks again,

        Chris