Functions

This page is part of the plugin documentation for the Date Pagination plugin.

There are two kind of functions this plugin provides

Label Functions

There are three functions you can use in your (child) theme’s template files to get the current, next and previous (paginated) date. The last two can be used to add date labels to the WP pagination functions.

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

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

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

They all share the same arguments $date_format and $query.

Note: The $query argument is only needed if you use a custom query (WP_Query) to get paginated posts.

To learn more about PHP date formats see this codex page.

Parameters:

$date_format
(string)(optional) PHP date format
Default date formats:

  • Yearly: 'Y' (e.g. 2017)
  • Monthly: 'F Y' (e.g. November 2016)
  • Daily: 'F j, Y' (e.g. November 24, 2016)
$query
(object)(optional) WP_Query object that is paginated by year, month or day.

Return:
These functions return a date as formatted by the $date_format parameter or an empty string if there is no next or previous (paginated) date.

Examples

These examples show you how to use the Label functions in your theme. For more examples of the label functions see the examples in this page.

Example for pre_get_posts

In this example we assume the date pagination is set to monthly with the pre_get_posts action.

Display the current, previous and next (paginated) date.

<?php
// Check if one of the function exists (plugin is activated).
if( function_exists( 'km_dp_get_current_date_label') ) {
	// Date format 'F Y' ( e.g. November 2016 ).
	echo 'Current Date: ' . km_dp_get_current_date_label( 'F Y' );
	echo 'Next Date: ' . km_dp_get_next_date_label( 'F Y' );
	echo 'Previous Date: ' . km_dp_get_previous_date_label( 'F Y' );
}
?>

Tip: See this example of how you would use the label functions together with the WP pagination functions.

Example for WP_Query

Example to display the current, next and previous (paginated) date with a Custom Query.

<?php
// Example arguments.
$args = array(
	// set the date pagination
	'date_pagination_type' => 'monthly', // 'yearly', 'monthly', 'daily'
	'paged'                => 2, // Get the second page posts
);

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

// Check if one of the function exists (plugin is activated).
if( function_exists( 'km_dp_get_current_date_label') ) {
	// Add $the_query object to the label functions. 

	// Date format 'F Y' ( e.g. November 2016 ).
	echo 'Current Date: ' . km_dp_get_current_date_label( 'F Y', $the_query );
	echo 'Next Date: ' . km_dp_get_next_date_label( 'F Y', $the_query );
	echo 'Previous Date: ' . km_dp_get_previous_date_label( 'F Y', $the_query );
}
?>

Tip: See this example of how you would use the label functions together with the WP pagination functions.

Numerical Pagination Functions

WordPress has three numerical pagination functions to display a list of page numbers. This plugin provides you with the same three functions, but with the ability to display dates instead of page numbers.

<php km_dp_the_posts_pagination( $args = array() ); ?>

<php km_dp_get_the_posts_pagination( $args = array() ); ?>

<php km_dp_paginate_links( $args = array()  ); ?>

They all have the same arguments as their WordPress counterparts.

The plugin’s numerical pagination functions have 2 extra arguments 'date_format' and 'date_query' that you can use to display dates.

Note: The 'date_query' argument is only needed if you use a custom query (WP_Query) to get date paginated posts. The 'date_format' is required to display dates instead of numbers. (See the examples below).

To learn more about PHP date formats see this codex page.

Examples

In these examples we’re using the km_dp_the_posts_pagination() function to display the pagination with dates.

Example for pre_get_posts
In this example we assume the date pagination is set to monthly with the pre_get_posts action.

<?php
// Pagination arguments.
$args = array(
	'date_format' => 'M',
	// Use other arguments here
);
 
// Check if function exists (plugin is activated).
if ( function_exists( 'km_dp_the_posts_pagination' ) ) {
	// Display dates with the plugin function.
	km_dp_the_posts_pagination( $args );
} else {
	// Display page numbers with the WordPress function.
	the_posts_pagination( $args );
}
?>

Example for WP_Query
In this example a custom query is used to get date paginated posts.

Note: Be aware that a custom query doesn’t update the main query and pagination. It’s only useful to get paginated posts. Use pre_get_posts instead.

<?php
// Query arguments.
$args = array(
	// set the date pagination
	'date_pagination_type' => 'monthly', // 'yearly', 'monthly', 'daily'
	'paged'                => 2, // Get posts for the second page
	// Use other query arguments here
);

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

// Pagination arguments.
$args = array(
	'date_format' => 'M',
	'date_query'  => $the_query,
	// Use other pagination arguments here
);

// Check if function exists (plugin is activated).
if ( function_exists( 'km_dp_the_posts_pagination' ) ) {	
	// Display dates with the plugin function.
	km_dp_the_posts_pagination( $args );
} else {
	// Display page numbers with the WordPress function.
	the_posts_pagination( $args );
}
?>

Supported WordPress Functions

These are the WordPress pagination functions the Date Pagination plugin supports. Most themes out there already use these functions for their pagination.

For more information about these functions see the theme handbook.

Tip: If your theme is using none of these functions to paginate pages, see if it’s works when setting the date pagination with the pre_get_posts action. Otherwise you’ll have to add them to the theme yourself.