Building a Custom Pagination Plugin for WordPress

Posted on 19th June 2023

One of the most important aspects of any website is pagination. Pagination is what allows users to navigate through your content, whether it be blog posts, products, or even search results. Without pagination, users would be stuck on the first page of your site, and would never be able to see any of your other content.

WordPress is a content management system that is very popular for building websites. WordPress is used by millions of people around the world to build everything from simple blogs to complex eCommerce sites.

One of the great things about WordPress is that it has a huge community of developers who create plugins and themes to extend the functionality of WordPress. There are plugins for almost everything you can think of, and pagination is no exception.

There are a few pagination plugins available for WordPress, but in this tutorial, we are going to build our own custom pagination plugin.

Why Build a Custom Plugin?

There are a few reasons why you might want to build a custom pagination plugin rather than using one of the many existing plugins.

First, by building your own plugin, you will have complete control over the code and the output. This means that you can tailor the plugin to exactly meet your needs.

Second, by building your own plugin, you will gain a better understanding of how WordPress plugins work. This knowledge will be useful if you ever need to build another plugin or make modifications to an existing plugin.

Third, by building your own plugin, you will be able to avoid bloat. Many WordPress plugins are loaded with features that you might never use. By building your own plugin, you can keep the code lean and only include the features that you need.

What We’ll Be Building

In this tutorial, we are going to build a simple pagination plugin that will allow us to paginate our content. Our plugin will have the following features:

The ability to paginate any post type, not just blog posts.

The ability to choose the number of items to display on each page.

The ability to choose the number of pages to show in the pagination links.

The ability to choose whether to display the first and last pages in the pagination links.

The ability to choose whether to display previous and next links in the pagination links.

The ability to choose whether to display the page numbers in the pagination links.

1. Create the Plugin Files

The first thing we need to do is create the plugin files. WordPress plugins are typically stored in a directory called /wp-content/plugins/.

Create a new directory called /wp-content/plugins/custom-pagination/.

Inside the /custom-pagination/ directory, create a new file called custom-pagination.php. This will be the main plugin file.

In the /custom-pagination/ directory, create a new directory called /css/. This will be where we store our CSS files.

In the /custom-pagination/ directory, create a new directory called /js/. This will be where we store our JavaScript files.

In the /custom-pagination/ directory, create a new directory called /images/. This will be where we store our image files.

Your plugin directory structure should look like this:

/wp-content/

/plugins/

/custom-pagination/

custom-pagination.php

/css/

/js/

/images/

2. Create the Plugin Header

The next thing we need to do is add some information to the top of our main plugin file, custom-pagination.php. This information is known as the plugin header and is used by WordPress to display information about the plugin on the plugin administration page.

The plugin header must be placed at the top of the main plugin file and must be within PHP tags.

The plugin header consists of a number of name/value pairs, each on their own line. The name and value are separated by a colon. The name is always in all lowercase letters with no spaces. The value can be anything you want.

The minimum information that you need to include in the plugin header is the Plugin Name.

Here is an example of a plugin header:

Let’s break down each line of the plugin header:

Plugin Name: This is the name of your plugin. The name should be descriptive and unique.

Plugin URI: This is the URL of your plugin website.

Description: This is a short description of your plugin.

Version: This is the version number of your plugin. It is a good idea to start with 1.0 and then increment the version number as you release new versions of your plugin.

Author: This is the name of the plugin author.

Author URI: This is the URL of the plugin author’s website.

License: This is the license that your plugin is released under. A common license is the GNU General Public License (GPL).

For our plugin, we are going to use the following plugin header:

3. Register the Plugin Settings

The next thing we need to do is register our plugin settings. Plugin settings are stored in the WordPress database and are used to store the plugin configuration options.

We are going to register four plugin settings:

cp_post_type: This setting will be used to store the post type that we want to paginate.

cp_items_per_page: This setting will be used to store the number of items to display on each page.

cp_pages_to_show: This setting will be used to store the number of pages to show in the pagination links.

cp_show_first_last: This setting will be used to store whether to display the first and last pages in the pagination links.

We are going to register our plugin settings using the WordPress function register_setting().

The register_setting() function takes two arguments:

The first argument is the name of the setting. This should be unique to your plugin.

The second argument is the name of the function that will be used to sanitize the setting. Sanitizing the setting means that we will validate and/or clean the setting before it is stored in the database. We will create the sanitization function later in this tutorial.

We will register our plugin settings in the custom-pagination.php file. Add the following code to the top of the file, below the plugin header:

Let’s break down the register_setting() function calls:

register_setting( ‘cp_settings’, ‘cp_post_type’, ‘cp_sanitize_post_type’ );

The first argument is the name of the group of settings. This should be unique to your plugin. We are using ‘cp_settings’.

The second argument is the name of the setting. This should be unique to your plugin. We are using ‘cp_post_type’.

The third argument is the name of the function that will be used to sanitize the setting. We are using ‘cp_sanitize_post_type’. We will create this function later in this