The underused WordPress Pagination Function

15 May 2011 By Articles 1 Comment
15
May

The WordPress Pagination Function is often overlooked when working on post paging, instead we tend to use fancy plug-ins to add this fairly basic functionality to your theme which is is most times an overkill for the functionality we are trying to achieve. There’s usually a lighter, smarter way.

The underused WordPress Pagination Function

The underused WordPress Pagination Function

Understanding WordPress Pagination

While plug-ins are a fine solution for consultants who are staging a complete roll-out, they’re awkward solutions for theme developers who want to sell standalone templates.

WP-PageNavi is one of the most popular WordPress plug-ins; and no doubt it is well developed. It is ideal for those who are uncomfortable digging into WordPress code. But did you know that WordPress has a function built right into core that (with a bit of savvy about its parameters) can generate pagination links for everything from comments to post archives to post pages?

The function in question is paginate_links(). (For those who like to fish around in the source, it’s on line 1954 of general-template.php in the wp-includes folder as of WordPress 3.1. This line number could of changed as of future WordPress updates.) Believe it or not, this underused function has been around since WordPress 2.1. Another function, paginate_comment_links(), is actually a wrapper for this function that is designed specifically for paging comments, and it has been around since WordPress 2.7.

The WordPress paginate_links() pagination function

The function takes an array of parameters that make it versatile enough to use for any kind of paging:

  • base – This is the path for the page number links, not including the pagination-specific part of the URL. The characters %_% will be substituted in that URL for the page-specific part of the URL.
  • format – This is the “page” part of the URL. %#% is substituted for the page number. For example, page/%#% or ?page=%#%.
  • total – The total number of pages available.
  • current – The current page number.
  • show_all – Lists all page links, instead of limiting it to a certain number of links to the left and right of the current page.
  • prev_next – Includes the “Previous” and “Next” links (if applicable), just as you might normally do with the previous_posts_link() function.
  • prev_text and next_text – Text to put inside the “Previous” and “Next” links.
  • end_size – The number of page links to show at the end. Defaults to 1 (e.g. 1 2 3 … 10).
  • mid_size­ – The number of pages to show on either side of the current page. Defaults to 2 (example: 1 … 3 4 5 6 7 … 10).
  • type – Allows you to specify an output style. The default is “plain,” which is just a string of links. Can also be set to list (i.e. ul and li representation of links) and array (i.e. returns an array of page links to be potentially outputted any way you like in code).
  • You can also add query arguments and fragments.

Because the pagination function takes all of the information needed to generate page links, you can use it for pretty much any pagination list, as long as you have some key information, such as the number of pages and the current page. Let’s use this function to generate pagination links for an article archive such as a category or main post index:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
// get total number of pages
global $wp_query;
 
$total = $wp_query->max_num_pages;
 
// only bother with the rest if we have more than 1 page!
if ($total > 1) {
    // get the current page
    if(!$current_page = get_query_var('paged'))
        $current_page = 1;
        // structure of "format" depends on whether we're using pretty permalinks
        $format = empty(get_option('permalink_structure')) ? '&page=%#%' : 'page/%#%/';
        echo paginate_links(array(
        'base' => get_pagenum_link(1) . '%_%',
        'format' => $format,
        'current' => $current_page,
        'total' => $total,
        'mid_size' => 4,
        'type' => 'list'
    ));
}
// get total number of pages
global $wp_query;

$total = $wp_query->max_num_pages;

// only bother with the rest if we have more than 1 page!
if ($total > 1) {
    // get the current page
    if(!$current_page = get_query_var('paged'))
        $current_page = 1;
        // structure of "format" depends on whether we're using pretty permalinks
        $format = empty(get_option('permalink_structure')) ? '&page=%#%' : 'page/%#%/';
        echo paginate_links(array(
        'base' => get_pagenum_link(1) . '%_%',
        'format' => $format,
        'current' => $current_page,
        'total' => $total,
        'mid_size' => 4,
        'type' => 'list'
    ));
}

Here’s the HTML generated code that is generated by the above WordPress pagination function on the first of 10 posts pages:

1
2
3
4
5
6
7
8
9
10
<ul class='page-numbers'>
<li><span class='page-numbers current'>1</span></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/2/'>2</a></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/3/'>3</a></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/4/'>4</a></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/5/'>5</a></li>
<li><span class='page-numbers dots'>...</span></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/10/'>10</a></li>
<li><a class='next page-numbers' href='http://www.wpinsite.com/page/2/'>Next ></a></li>
</ul>
<ul class='page-numbers'>
<li><span class='page-numbers current'>1</span></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/2/'>2</a></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/3/'>3</a></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/4/'>4</a></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/5/'>5</a></li>
<li><span class='page-numbers dots'>...</span></li>
<li><a class='page-numbers' href='http://www.wpinsite.com/page/10/'>10</a></li>
<li><a class='next page-numbers' href='http://www.wpinsite.com/page/2/'>Next ></a></li>
</ul>

Simple function to use in WordPress theme files for pagination but often overlooked.

Be sure to check out our other great WordPress Articles and Plugins
Enjoy this article? If so, we would love to hear your thoughts in the comments below

 

Related Blog Posts

One Response to The underused WordPress Pagination Function

  1. Thanks a lot — this works perfectly! However, I want to remove the last page from the pagination. That is, the last page number shouldn’t be visible.

    Can you please help?

    Reply

Leave a Reply