Build plugins that customize the WordPress Loop and create additional side loops that users can display with a simple shortcode.
- [Narrator] In this tutorial, we look at several ways to customize the WordPress loop using a plugin. The WordPress loop refers to a bit of code that loops through posts and displays them on the front end. Virtually all themes include some sort of looping functionality. Here is an example of the basic logic used by WordPress loops. First, check if any posts exist. Then, loop through the display of posts using template tags and markup. For this tutorial, we'll assume that you're familiar with WordPress loops and want to know how to customize them with your plugins.
To get up to speed with WordPress loops, check out these resources. There are many reasons to customize loops. You may want to limit the types of posts that are displayed or customize the number of posts. Or you may want to add an additional loop that displays a specific set of posts. Here are the three main techniques used for customizing loops. Let's go through each of them and see how they work. The simplest way to add a custom loop, or set of posts, to be more accurate, is to use get_posts.
Here we have the first plugin demo for this video. It contains an example of how to use get_posts to display a custom set of posts. This function is used to create a short code that can be added to any page. Before looking at the code, let's see how it works. We can add the short code to our demo page, or any page that you'd like is fine. Plus we'll add a bit of markup to make things easier to understand on the front end.
And now let's view the page on the front end. Here is the set of posts created by this short code. So with a plugin activated, the user can add the short code to display posts on any page. This short code accepts two attributes, posts_per_page and orderby. The default values for these attributes, when they are not included in the short code, are 5 and date, to display five posts ordered by date.
To see how they work, let's change these attributes to three and random. And now we can revisit the page on the front end. And perfect, the custom loop now displays three random posts. Now let's look at how this custom loop works under the hood. This function creates a basic short code according to the short code API.
First, we want to make sure that we define the global post variable. This is required to display the results of the get_posts function. Next, we extract the short code attributes to variables, using the PHP function extract, along with the WordPress function shortcode_atts. After getting the short code variables, we define the parameters that will be used by the get_posts function.
There are many parameters that can be used to customize the set of posts. Here is the official documentation that describes all of the parameters that we can use with get_posts. Using these parameters, we can get virtually any set of posts ordered in specific ways, containing any number of posts, and much more. So after defining the parameters, we get the posts using get_posts. Notice that we pass our array of parameters directly to the function.
After calling get_posts, this post variable will contain an array of all the queried posts. Next, we begin the output variable with a heading and an opening list tag. Then we loop through the posts using PHP's foreach. Inside of the foreach loop, we set up the post data and then use template tags to get the permalink and post title for each post.
This is where we can customize how the posts are displayed. We can use any markup and template tags for this, and WordPress provides a lot of them. For now, we're keeping it simple with some basic list markup. After the foreach loop, we reset the post data, and then complete the output variable and then return it. Notice we are registering our function as a short code using add_shortcode. This first parameter is the name of the short code, and the second parameter is the name of our function.
So using the get_posts function enables us to get custom sets of posts, but what if we want to customize the posts that are displayed in the main WordPress loop? For that, we can use pre_get_posts. Here, in the next plugin demo, we have a simple example of the pre_get_posts hook. One of the strengths of this technique is that it's consistent and straightforward. In general, here is how it works. First, we check the query to make sure that it meets our criteria. In this example, we are making sure that the query is not for any admin page and that the query is, in fact, for the main WordPress query.
So if both of these conditions prove true, then we can customize the query by using the set method of the WP_query class. For this example, the set method enables us to change the number of posts to one. Let's view the results on the development site. By default, the home page displays the three latest posts, but now with our pre_get_posts function in place, we see that the number of posts changes to one.
Let's look at some other examples. Say we want to customize the main loop so that the post order is reversed. So we change the set parameter to order and the value to ascending. We save our changes. The posts are now displayed in ascending order. See, Hello world! usually is the last post, but now it is the first. One more example. Say we want to exclude posts from two specific categories, so we change the first attribute to cat for category and then exclude whichever categories we would like, let's say nine and 10.
And we save our changes, and now all posts from categories nine and 10 are excluded from the main loop. So far, we've seen two ways to customize the WordPress loop. We can use get_post to create side loops and get custom sets of posts, and we can use the pre_get_post hook to customize the main WordPress query. But what if we need more flexibility? That's easy. WP_query to the rescue. The WP_query class is very flexible and enables us to create custom loops for virtually any set of posts.
Here's the third plugin demo for this video. Here we can see that WP_query is very similar to get_posts, but it can do a lot more. With get_posts, we basically can query a set of posts and display them in a foreach loop, but with WP_query, we can query a set of posts and control all of the code that's used to loop through the posts. So it's possible to include things like pagination, post comments, and conditional tags. This plugin demo uses WP_query to create a custom WordPress loop.
This function is registered as a short code, so the custom loop can be displayed easily on any page. First, let's see how it works. Returning to our demo page, we can replace the previous short code with the WP_query short code. After saving the changes, we can view the page on the front end. Here is the loop of posts displayed by our WP_query short code. With this short code, the user can display a list of posts virtually anywhere.
This short code also accepts a couple of attributes, posts_per_page and orderby. The default values for these attributes when they are not included in the short code are 5 and date, to display five posts ordered by date. To see how they work, let's change these attributes to three and random, then save changes, and then revisit on the front end.
Perfect, our custom loop now displays three random posts. Now let's see how this WP_query function works under the hood. This function creates a basic short code according to the short code API. After defining the short code variables, we define the parameters that define our custom query, which is made here with WP_query.
The results of the query are saved as a variable named posts. After querying the posts, we begin the output variable and then proceed with the loop. Within the loop, we set up each post and add it to the output variable. We have the post title and content, and then, after the loop, we reset the post data, or, if no posts are found for the given query, we output a simple message, which is a common thing to do for most loops.
And lastly, we return the output variable, which now contains all of the markup required to display the custom loop. To make this function a short code, we register it with add_shortcode. First parameter is the name of the short code, and the second parameter is the name of the function. We'll return to this function in the upcoming video on using the Transients API, where we'll see how to cache the output of this function to improve performance. Using the techniques described in this tutorial, it's possible to build plugins that customize the WordPress loop and create additional side loops that users can display with a simple short code.
These techniques are further documented at wordpress.org and are readily available for all of your plugin building needs.
- WordPress APIs
- Action and filter hooks
- Activating and deactivating plugins
- Plugin security
- Creating the directory and files
- Adding menus and the settings page
- Inserting custom functionality
- Testing and debugging WordPress plugins
- Creating widgets
- Managing users and roles
- Adding custom post types and taxonomies
- Working with custom fields and database queries
- Using APIs: Transients, HTTP, and REST