Date Pagination

Paginate your posts by year, month or day.

This WordPress plugin is aimed at developers and provides an easy way to paginate posts by year, month or day in theme templates. It uses the native WordPress pagination functions for display of the pagination links.

Use the new date_pagination_type query argument with a custom query (WP_Query) or with the ‘pre_get_posts‘ action, and this plugin will do the rest. Use three new functions in your (child) theme template files to get the current, next and previous date. See Functions

Plugin support for this plugin from the plugin author will be minimal as this is a plugin made for developers. If you encounter problems see the troubleshooting steps first.

Bug reports, feature requests and other issues can be reported through the GitHub issues system.

Download

**Note** This plugin intentionally doesn’t work in date based archives.

Date pagination with pre_get_posts

Set the date pagination by using the date_pagination_type query argument. Conditional tags let you choose where you want to use date pagination.

Example

Set the pagination to monthly on the home page. Use this example in your (child) theme’s functions.php file.

add_action( 'pre_get_posts', 'monthly_paginated_home_query' );
function monthly_paginated_home_query( $query ) {

	// not a wp-admin page and the query is for the main query
	if ( !is_admin() && $query->is_main_query() ) {

		//  on the home page only
		if ( is_home() ) {

			// set the date pagination to 'monthly'
			$query->set('date_pagination_type', 'monthly'); 

			// set other arguments here
		}
	}
}

Date pagination with WP_Query

See the WP_Query loop example.

Functions

There are three new functions you can use in your (child) theme’s template files.

<php km_dp_get_current_date_label( $format, $query ); ?>

<php km_dp_get_next_date_label( $format, $query ); ?>

<php km_dp_get_previous_date_label( $format, $query ); ?>

Use the functions to get the current, next and previous date. They all share the same arguments $format and $query. The $query argument is only needed if you use a custom query (WP_Query).

Arguments:

$format
(string)(optional) PHP date format
$query
(object)(optional) WP_Query object that is paginated by year, month or day.

Examples

Normal loop with date pagination set by pre_get_posts

Example of using the new functions in a (child) theme template file with monthly pagination set by the pre_get_posts action in your (child) theme’s functions.php file. See the pre_get_post code example above.

<?php if ( have_posts() ) : ?>
	
	<h2>
		<?php
		// Echo current date with format 'F Y' ( e.g. November 2010 ).
		echo 'Current Date: ';
		echo km_dp_get_current_date_label( 'F Y' );
		?>
	</h2>

	<!-- The Loop -->
	<?php while ( have_posts() ) : the_post(); ?>
		<!-- Your loop code here -->
	<?php endwhile; ?>
	<?php

	// default labels
	$next_label = 'Previous Month';
	$prev_label = 'Next Month';

	// Check if functions exists (plugin is activated)
	if ( function_exists( 'km_dp_get_next_date_label' ) ) {
		$next_label = km_dp_get_next_date_label( 'F Y' );
	}

	if ( function_exists( 'km_dp_get_previous_date_label' ) ) {
		$prev_label = km_dp_get_previous_date_label( 'F Y' );
	}
	?>

	<!-- WordPress core pagination functions (see the Codex) -->
	<?php next_posts_link( $next_label ); ?>
	<?php previous_posts_link( $prev_label ); ?>
	
<?php else:  ?>
	<p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

WP_Query loop with date pagination

Example of using the new functions in a (child) theme template file. The monthly pagination is set with the new date_pagination_type query argument.

<?php
// Set the paged variable (see: http://codex.wordpress.org/Pagination ).
$paged = ( get_query_var( 'paged' ) ) ? get_query_var( 'paged' ) : 1;

// Example arguments.
$args = array(

	// set the date pagination to 'monthly'
	'date_pagination_type' => 'monthly', // 'yearly', 'monthly', 'daily'
	'paged'                => $paged,

	// Add your own query arguments here
	'post_type'            => array( 'post' ),
	'ignore_sticky_posts'  => true,
);

// The custom query.
$the_query = new WP_Query( $args );

// Variable $the_query is the query object.
// Don't forget to add the query object to the new functions when using a custom query;
?>

<?php if ( $the_query->have_posts() ) : ?>

	<h2>
		<?php
		// Echo current date with format 'F Y' ( e.g. November 2010 ).

		echo 'Current Date: ';
		echo km_dp_get_current_date_label('F Y', $the_query);
		?>
	</h2>

	<!-- The custom query Loop -->
	<?php while ( $the_query->have_posts() ) : $the_query->the_post(); ?>

		<!-- Your loop code here -->
	<?php endwhile; ?>

	<?php
	// Date Pagination.

	// Default labels.
	$next_label = 'Previous Page';
	$prev_label = 'Next Page';	

	// Check if functions exists (plugin is activated).
	if ( function_exists( 'km_dp_get_next_date_label' ) ) {
		$next_label = km_dp_get_next_date_label( 'F Y', $the_query );
	}	

	if ( function_exists( 'km_dp_get_previous_date_label' ) ) {
		$prev_label = km_dp_get_previous_date_label( 'F Y', $the_query );
	}
	?>

	<!-- WordPress core pagination functions (see the Codex) -->
	<?php
	// Set max_num_pages for next_posts_link() when using a custom query (see the Codex).
	// Get the max_num_pages from the custom query object ($the_query)
	next_posts_link( 'Previous month: ' . $next_label, $the_query->max_num_pages );
	?>
	<?php previous_posts_link( 'Next month: ' . $prev_label ); ?>

	<?php wp_reset_postdata(); ?>
<?php else:  ?>
	<p><?php _e( 'Sorry, no posts matched your criteria.' ); ?></p>
<?php endif; ?>

Troubleshooting Steps

The same troubleshooting steps for WordPress pagination functions apply to this plugin.

Troubleshooting steps if you queried the loop with new WP_Query or query_posts.
Did you set the paged parameter?
Is pagination broken on a static front page?
Did you reset the loops if there are multiple loops?
Did you add the $max_pages to the next_posts_link() function?
Did you add the total to the paginate_links() function?

31 thoughts on “Date Pagination

  1. Hi,

    I have been looking for this type of plugin for a long time ….. think the idea of using dates for pagination is the way to go, especially for sites that generate a lot of content.

    I am more a designer, with an appreciation of development … but this is a little bit past my skill set at the moment.
    Are there any plans to release an out of the box plugin? Would really love to get this running on the sites I work with.

    Many thanks in advance
    David

    • Hi David,

      Unfortunately this is as out of the box as it gets. It’s up to a theme where to display pagination, and what functions (or pagination plugins) are used. The plugin can’t know, filter or detect this. For the most part the plugin will be compatible with themes that use the native WordPress pagination functions.

      Where do you encounter problems? On what pages do you want date pagination?

  2. Hey I know this is off topic but I was wondering if you knew of any widgets I could add to my blog that automatically tweet my newest twitter updates.

    I’ve been looking for a plug-in like this for quite some time and
    was hoping maybe you would have some experience with something like this.
    Please let me know if you run into anything.
    I truly enjoy reading your blog and I look forward to your new updates.

  3. Is there any way this plugin can be altered so that the posts within each day can be sorted by a meta value? If I add a normal WP ‘orderby’=>’meta_value_num’ into this current, it spits out the days in order of votes :/

  4. Hi keesiemeijer,
    Good job with your plugin!
    I am working on the blog section of this website
    http://artistresidencecornwall.co.uk/whats-on/
    to get the posts in monthly pagination.
    I am using this plugin http://wordpress.org/support/plugin/the-future-is-now to have the possibility to publish post/events coming in next months.
    Problem is that the first posts on the blog will be future dates.

    Is there a way to use your plugin in order to display posts from the current month, when you land on the blog page?
    I’d really appreciate your help,
    if something sounds confusing I will post the code in codepen or pastebin

    Thanks
    –Simon

  5. Pingback: Default blog section in wordpress paginated monthly - HelpDesk

  6. hello keesiemeijer,

    I’m trying to use this pagination with the option set as daily.

    using the code below though just gives me the current date for each link. They display the correct posts though, they just doesn’t display the correct date.

    thoughts?

    if ( function_exists( 'km_dp_get_next_date_label' ) ) {
        $next_label = km_dp_get_next_date_label( 'F j, Y' );
    }
     
    if ( function_exists( 'km_dp_get_previous_date_label' ) ) {
        $prev_label = km_dp_get_previous_date_label( 'F j, Y' );
    }
    
  7. Great plugin! This is exactly what I’m looking for, however I’m wondering if there was a way I could get each page to show 2 month of posts instead of just one month. A sort of bi-monthly pagination.
    Let me know if you think this is possible and how I could implement it.
    Thanks,

  8. I’m ran into an issue with the plugin the minute I posted my first 2015 post. It caused the previous month to suddenly add images and revisions as posts in the loop. It was really weird.

    I’ve disabled the plugin at the moment, but was wondering if you might have an idea what could be causing the issue.

    Thanks.

  9. I’ve got kind of an odd situation for you. My client is using this plugin to create archives by year, but they want the first year in the archive to be 2014, the next 2013, etc. I can do this by setting “order” to “DESC,” but then the posts themselves show up in descending order as well. Is there any way to have the pages go in descending order, but the posts in ascending? I.E. January would be first, February second, March third, but he pages would go 2014, 2013, 2012?

  10. Hi,
    WordPress database error: [Column ‘ID’ in field list is ambiguous]
    SELECT YEAR(post_date) AS `year`, count(ID) as posts FROM ahf_posts JOIN ahf_icl_translations t ON ahf_posts.ID = t.element_id AND t.element_type = ‘post_event’ JOIN ahf_icl_languages l ON t.language_code=l.code AND l.active=1 WHERE 1=1 AND ahf_posts.post_type = ‘event’ AND (ahf_posts.post_status = ‘publish’ OR ahf_posts.post_status = ‘private’) AND t.language_code=’ur’ GROUP BY YEAR(post_date) ORDER BY ahf_posts.post_date DESC

    i am receiving this error.. i am using wpml plugin…

  11. Hi, I’m trying using your plugin. It works ok on the main language, but it does not show anything for the secondary language. I’m using wpml and your plugin by shortcode in the single post page (single.php) via do_shortcode function. What can I do? Thanks

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s