Pagination is a very common feature for almost every website. There are many different ways to implement pagination in WordPress. Here’s a list of few common ways to go about setting up pagination on your website.
- Using a plugin, similar to PageNavi
- Using a third party PHP class
- Write your own code
Plugins are great but they usually come bloated with extra options to accommodate all possible configuration scenarios. Using 3rd-party plugins sounds like a great idea if you are after a lean script.
After spending some time on google, digging around I came across a few outdated tutorials and git repos with 100s lines of code for implementing WordPress pagination. Surely the pagination shouldn’t be that complex to implement in WordPress, I’m starting to have the same feeling here as I did with plugins. Unnecessary code that slows down rapid development.
I guess you want things the way you want it, you have to do them yourself!
First stop, twentysixteen. Let’s investigate how the pagination has been implemented here. After all, twentysixteen theme was developed by veterans in WordPress development, I trust they know the best way to implement pagination.
After opening archive.php I found following lines:
[code lang=”php”]
// Previous/next page navigation.
the_posts_pagination( array(
‘prev_text’ => __( ‘Previous page’, ‘twentysixteen’ ),
‘next_text’ => __( ‘Next page’, ‘twentysixteen’ ),
‘before_page_number’ => ‘<span class="meta-nav screen-reader-text">’ . __( ‘Page’, ‘twentysixteen’ ) . ‘</span>’,
) );
[/code]
Looks great! Only 5 lines. Lets checkout the Codex, the_posts_pagination function in particular to find a way and modify html, after all we want to controle our output.
After looking through available options under Parameters section it became apparent to me that controlling output is very limited, we are only able to modify following parameters:
- mid_size (int) – How many page numbers to display to either side of the current page. Defaults to 1.
- prev_text (string) – Text of the link to the next set of posts. Defaults to “Previous”.
- next_text (string) – Text of the link to the next set of posts. Defaults to “Next”.
- screen_reader_text (string) – Text meant for screen readers. Defaults to “Posts navigation”.
Thats not gonna work us, we want to be able to have full control over our html so that we can apply custom css styling. Let’s see what the_posts_pagination function is made of and may be we can take the code and build our custom function from it.
Lets follow the rabbit down the rabbit whole…
Function the_posts_pagination can be found under wp-includes/link-template.php
function the_posts_pagination( $args = array() ) {
echo get_the_posts_pagination( $args );
}
Ok, we see another function call from within the same file:
[code lang=”php”]
function get_the_posts_pagination( $args = array() ) {
$navigation = ”;
// Don’t print empty markup if there’s only one page.
if ( $GLOBALS[‘wp_query’]->max_num_pages > 1 ) {
$args = wp_parse_args( $args, array(
‘mid_size’ => 1,
‘prev_text’ => _x( ‘Previous’, ‘previous post’ ),
‘next_text’ => _x( ‘Next’, ‘next post’ ),
‘screen_reader_text’ => __( ‘Posts navigation’ ),
) );
// Make sure we get a string back. Plain is the next best thing.
if ( isset( $args[‘type’] ) && ‘array’ == $args[‘type’] ) {
$args[‘type’] = ‘plain’;
}
// Set up paginated links.
$links = paginate_links( $args );
if ( $links ) {
$navigation = _navigation_markup( $links, ‘pagination’, $args[‘screen_reader_text’] );
}
}
return $navigation;
}
[/code]
There’s yet another function that generates the pagination, so lets follow this one level further and see where that takes us, remember we still trying to find the core of the function responsible for generating the pagination within WordPress. We want to take that code and modify it to suit our needs.
[code lang=”php”]
// Set up paginated links.
$links = paginate_links( $args );
[/code]
Let’s visit Codex for more information on paginate_links function. Just looking at the default arguments already makes me feel hopeful! Time to look at the source code and see if there is much fluff in the code.
wp-includes/general-template.php is where the function lives.
After looking through the code I decided not to copy the function but rather rely on its functionality to build my own, simple WordPress pagination class. Now I can easily and swiftly implement WordPress pagination on any website. All I have to do is copy my class in the directory, include the file and lastly initiate a new object of a class. Here is how its done:
[code lang=”php”]
<?php
include(‘inc/vendors/class-wordpress-pagination.php’);
?>
[/code]
[code lang=”php”]
<?php
global $wp_query;
$args = array(
‘base’ => str_replace( 2, ‘%#%’, esc_url( get_pagenum_link( 2 ) ) ), //user integer > 1, otherwise pagination returns initial page, which is /blog/
‘format’ => ‘/page/%#%/’,
‘total’ => $wp_query->max_num_pages,
‘current’ => max( 1, get_query_var(‘paged’) ),
‘show_all’ => false,
‘end_size’ => 1,
‘mid_size’ => 2,
‘prev_next’ => true,
‘prev_text’ => __(‘Previous Page’),
‘next_text’ => __(‘Next Page’),
‘type’ => ‘array’,
‘add_args’ => false,
‘add_fragment’ => ”,
‘before_page_number’ => ”,
‘after_page_number’ => ”
);
$_WPP = new WPP_Class($args);
?>
[/code]
The best thing about using this class is that we are still using default WordPress Core functionality for pagination but with this class you have full control over your html output.
If you have a look at the class you will see how easy and awesome it is to work with. It’s lean and easily configurable.
All output html is managed through function generate_html:
Here the full preview of the pagination, you can also see it in action by going to the blog:
Link to GitHub repository.