Wordpress - How to fix pagination for custom loops?

The Problem

By default, in any given context, WordPress uses the main query to determine pagination. The main query object is stored in the $wp_query global, which is also used to output the main query loop:

if ( have_posts() ) : while ( have_posts() ) : the_post();

When you use a custom query, you create an entirely separate query object:

$custom_query = new WP_Query( $custom_query_args );

And that query is output via an entirely separate loop:

if ( $custom_query->have_posts() ) : 
    while ( $custom_query->have_posts() ) : 
        $custom_query->the_post();

But pagination template tags, including previous_posts_link(), next_posts_link(), posts_nav_link(), and paginate_links(), base their output on the main query object, $wp_query. That main query may or may not be paginated. If the current context is a custom page template, for example, the main $wp_query object will consist of only a single post - that of the ID of the page to which the custom page template is assigned.

If the current context is an archive index of some sort, the main $wp_query may consist of enough posts to cause pagination, which leads to the next part of the problem: for the main $wp_query object, WordPress will pass a paged parameter to the query, based on the paged URL query variable. When the query is fetched, that paged parameter will be used to determine which set of paginated posts to return. If a displayed pagination link is clicked, and the next page loaded, your custom query won't have any way to know that the pagination has changed.

The Solution

Passing Correct Paged Parameter to the Custom Query

Assuming that the custom query uses an args array:

$custom_query_args = array(
    // Custom query parameters go here
);

You will need to pass the correct paged parameter to the array. You can do so by fetching the URL query variable used to determine the current page, via get_query_var():

get_query_var( 'paged' );

You can then append that parameter to your custom query args array:

$custom_query_args['paged'] = get_query_var( 'paged' ) 
    ? get_query_var( 'paged' ) 
    : 1;

Note: If your page is a static front page, be sure to use page instead of paged as a static front page uses page and not paged. This is what you should have for a static front page

$custom_query_args['paged'] = get_query_var( 'page' ) 
    ? get_query_var( 'page' ) 
    : 1;

Now, when the custom query is fetched, the correct set of paginated posts will be returned.

Using Custom Query Object for Pagination Functions

In order for pagination functions to yield the correct output - i.e. previous/next/page links relative to the custom query - WordPress needs to be forced to recognize the custom query. This requires a bit of a "hack": replacing the main $wp_query object with the custom query object, $custom_query:

Hack the main query object

  1. Backup the main query object: $temp_query = $wp_query
  2. Null the main query object: $wp_query = NULL;

  3. Swap the custom query into the main query object: $wp_query = $custom_query;

    $temp_query = $wp_query;
$wp_query   = NULL;
$wp_query   = $custom_query;

This "hack" must be done before calling any pagination functions

Reset the main query object

Once pagination functions have been output, reset the main query object:

$wp_query = NULL;
$wp_query = $temp_query;

Pagination Function Fixes

The previous_posts_link() function will work normally, regardless of pagination. It merely determines the current page, and then outputs the link for page - 1. However, a fix is required for next_posts_link() to output properly. This is because next_posts_link() uses the max_num_pages parameter:

<?php next_posts_link( $label , $max_pages ); ?>

As with other query parameters, by default the function will use max_num_pages for the main $wp_query object. In order to force next_posts_link() to account for the $custom_query object, you will need to pass the max_num_pages to the function. You can fetch this value from the $custom_query object: $custom_query->max_num_pages:

<?php next_posts_link( 'Older Posts' , $custom_query->max_num_pages ); ?>

Putting it all together

The following is a basic construct of a custom query loop with properly functioning pagination functions:

// Define custom query parameters
$custom_query_args = array( /* Parameters go here */ );

// Get current page and append to custom query parameters array
$custom_query_args['paged'] = get_query_var( 'paged' ) ? get_query_var( 'paged' ) : 1;

// Instantiate custom query
$custom_query = new WP_Query( $custom_query_args );

// Pagination fix
$temp_query = $wp_query;
$wp_query   = NULL;
$wp_query   = $custom_query;

// Output custom query loop
if ( $custom_query->have_posts() ) :
    while ( $custom_query->have_posts() ) :
        $custom_query->the_post();
        // Loop output goes here
    endwhile;
endif;
// Reset postdata
wp_reset_postdata();

// Custom query loop pagination
previous_posts_link( 'Older Posts' );
next_posts_link( 'Newer Posts', $custom_query->max_num_pages );

// Reset main query object
$wp_query = NULL;
$wp_query = $temp_query;

Addendum: What About query_posts()?

query_posts() for Secondary Loops

If you're using query_posts() to output a custom loop, rather then instantiating a separate object for the custom query via WP_Query(), then you're _doing_it_wrong(), and will run into several problems (not the least of which will be pagination issues). The first step to resolving those issues will be to convert the improper use of query_posts() to a proper WP_Query() call.

Using query_posts() to Modify the Main Loop

If you merely want to modify the parameters for the main loop query - such as changing the posts per page, or excluding a category - you may be tempted to use query_posts(). But you still shouldn't. When you use query_posts(), you force WordPress to replace the main query object. (WordPress actually makes a second query, and overwrites $wp_query.) The problem, though, is that it does this replacement too late in the process to update the pagination.

The solution is to filter the main query before posts are fetched, via the pre_get_posts hook.

Instead of adding this to the category template file (category.php):

query_posts( array(
    'posts_per_page' => 5
) );

Add the following to functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Test for category archive index
    // and ensure that the query is the main query
    // and not a secondary query (such as a nav menu
    // or recent posts widget output, etc.
    if ( is_category() && $query->is_main_query() ) {
        // Modify posts per page
        $query->set( 'posts_per_page', 5 ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

Instead of adding this to the blog posts index template file (home.php):

query_posts( array(
    'cat' => '-5'
) );

Add the following to functions.php:

function wpse120407_pre_get_posts( $query ) {
    // Test for main blog posts index
    // and ensure that the query is the main query
    // and not a secondary query (such as a nav menu
    // or recent posts widget output, etc.
    if ( is_home() && $query->is_main_query() ) {
        // Exclude category ID 5
        $query->set( 'category__not_in', array( 5 ) ); 
    }
}
add_action( 'pre_get_posts', 'wpse120407_pre_get_posts' );

That way, WordPress will use the already-modified $wp_query object when determining pagination, with no template modification required.

When to use what function

Research this question and answer and this question and answer to understand how and when to use WP_Query, pre_get_posts, and query_posts().


I use this code for custom loop with pagination:

<?php
if ( get_query_var('paged') ) {
    $paged = get_query_var('paged');
} elseif ( get_query_var('page') ) { // 'page' is used instead of 'paged' on Static Front Page
    $paged = get_query_var('page');
} else {
    $paged = 1;
}

$custom_query_args = array(
    'post_type' => 'post', 
    'posts_per_page' => get_option('posts_per_page'),
    'paged' => $paged,
    'post_status' => 'publish',
    'ignore_sticky_posts' => true,
    //'category_name' => 'custom-cat',
    'order' => 'DESC', // 'ASC'
    'orderby' => 'date' // modified | title | name | ID | rand
);
$custom_query = new WP_Query( $custom_query_args );

if ( $custom_query->have_posts() ) :
    while( $custom_query->have_posts() ) : $custom_query->the_post(); ?>

        <article <?php post_class(); ?>>
            <h3><a href="<?php the_permalink(); ?>"><?php the_title(); ?></a></h3>
            <small><?php the_time('F jS, Y') ?> by <?php the_author_posts_link() ?></small>
            <div><?php the_excerpt(); ?></div>
        </article>

    <?php
    endwhile;
    ?>

    <?php if ($custom_query->max_num_pages > 1) : // custom pagination  ?>
        <?php
        $orig_query = $wp_query; // fix for pagination to work
        $wp_query = $custom_query;
        ?>
        <nav class="prev-next-posts">
            <div class="prev-posts-link">
                <?php echo get_next_posts_link( 'Older Entries', $custom_query->max_num_pages ); ?>
            </div>
            <div class="next-posts-link">
                <?php echo get_previous_posts_link( 'Newer Entries' ); ?>
            </div>
        </nav>
        <?php
        $wp_query = $orig_query; // fix for pagination to work
        ?>
    <?php endif; ?>

<?php
    wp_reset_postdata(); // reset the query 
else:
    echo '<p>'.__('Sorry, no posts matched your criteria.').'</p>';
endif;
?>

Source:

  • WordPress custom loop with pagination

Awesome as always Chip. As an addendum to this, consider the situation whereby you are using a global page template attached to a Page for some "intro text" and it's followed by a subquery that you want to be paged.

Using paginate_links() as you mention above, with mostly defaults, (and assuming you have pretty permalinks turned on) your pagination links will default to mysite.ca/page-slug/page/# which is lovely but will throw 404 errors because WordPress doesn't know about that particular URL structure and will actually look for a child page of "page" that's a child of "page-slug".

The trick here is to insert a nifty rewrite rule that only applies to that particular "pseudo archive page" page slug that accepts the /page/#/ structure and rewrites it to a query string that WordPress CAN understand, namely mysite.ca/?pagename=page-slug&paged=#. Note pagename and paged not name and page (which caused me literally HOURS of grief, motivating this answer here!).

Here's the redirect rule:

add_rewrite_rule( "page-slug/page/([0-9]{1,})/?$", 'index.php?pagename=page-slug&paged=$matches[1]', "top" );

As always, when changing rewrite rules, remember to flush your permalinks by visiting Settings > Permalinks in the Admin back-end.

If you have multiple pages that are going to behave this way (for example, when dealing with multiple custom post types), you might want to avoid creating a new rewrite rule for each page slug. We can write a more generic regular expression that works for any page slug you identify.

One approach is below:

function wpse_120407_pseudo_archive_rewrite(){
    // Add the slugs of the pages that are using a Global Template to simulate being an "archive" page
    $pseudo_archive_pages = array(
        "all-movies",
        "all-actors"
    );

    $slug_clause = implode( "|", $pseudo_archive_pages );
    add_rewrite_rule( "($slug_clause)/page/([0-9]{1,})/?$", 'index.php?pagename=$matches[1]&paged=$matches[2]', "top" );
}
add_action( 'init', 'wpse_120407_pseudo_archive_rewrite' );

Disadvantages / Caveats

One disadvantage of this approach that makes me puke in my mouth a little is the hard-coding of the Page slug. If an admin ever changes the page slug of that pseudo-archive page, you're toast - the rewrite rule will no longer match and you'll get the dreaded 404.

I'm not sure I can think of a workaround for this method, but it would be nice if it were the global page template that somehow triggered the rewrite rule. Some day I may revisit this answer if no one else has cracked that particular nut.

Tags:

Pagination

Query

Loop

Recent Posts