As the title suggests, this post will show you how to develop a related posts plugin for WordPress. Some fairly complex topics are covered, so if you are a beginner you may want to start with my ‘Hello world‘ tutorial before continuing.
There’s quite a bit of code to cover, so I’d probably set aside an hour and a half or so to get through this comfortably.
Anyway, I guess the first step is to outline exactly what the plugin will do – and (vaguely) how it will do it.
- When a post is loaded, collect & store any relevant information such as title or category.
- Use this information to search the database for related posts, lets say 2 to start with. The amount of posts returned should be flexible.
- It’s possible that the search will return more posts than we need, so there must be some way to sort them so that only the most relevant are used.
- The related posts should be appended to the end of the content section.
End Result:
Step 1 – The plugin folder structure.
Before we go ahead and jump into writing the code, let’s create the plugin directory. You can refer to the image below to see the structure used.
Step 2 – General plugin set-up.
If you wish to conform to WordPress plugin development recommendations there are a couple of files which need to be created. These files will allow WordPress to recognize the plugin, giving the user the option to enable it from the admin panel.
First up is the ‘readme’ file. Create a file named ‘readme.txt’ in the root folder of your plugin. In the example provided above, ‘weeb-related-posts’ is the root folder & from this point onwards, this folder will be referred to as the root folder. The ‘readme’ file should contain the following text.
=== Weeb Related Posts === Contributors: John Richardson Website: http://weebtutorials.com Tags: Related posts tutorial. Requires at least: 2.7 Stable tag: 1.0
The ‘readme’ file is only required if you aim to host your plugin on the WordPress website. It is used to provide WordPress with information about your plugin. Nonetheless, I find it is good practice to include it anyway as it only takes a minute to create, and may be useful at a later date.
Next we need to create the main plugin file. It should have a name derived from the name of the plugin, in our case it is called ‘weeb-related-posts.php’. This file should be placed in the root folder, alongside the ‘readme’ file. Initially this file should be populated with header information which allows WordPress to recognize the plugin. We will be adding more to this file as we progress through the tutorial.
<?php
/*
Plugin Name: Weeb related posts
Plugin URI: http://weebtutorials.com
Description: A simple related posts plugin made for demonstration purposes.
Version: 1.0
Author: John Richardson
Author URI: http://weebtutorials.com
License: GPL2
Copyright 2013 John Richardson (email : johnrich85@hotmail.com)
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License, version 2, as
published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
*/With these files created, the initial set-up phase is complete. If you log-in to the admin panel you should have the option to enable the plugin, do so now.
Step 3 – Pre-coding phase.
I know, I know, you just want to start writing code – we’re almost there, don’t worry!
It’s always a good idea to spend a little time considering how the script will work and how we can break down or separate our code base. Based on the requirements (outlined at the start of the tutorial) and the theory that classes should have a single area of responsibility, I suggest that we break the code down into two separate classes.
- Class 1 – Retrieves information about the posts, formats & stores.
- Class 2 – Uses the information stored in Class 1 to retrieve related posts from the database.
We now have a plan of attack, albeit a vague one. Anyway, let’s get on with it.
Step 4 – Coding phase 1.
Before we start writing the classes there is a couple of things we should do. First of all, let’s define a couple of constants. These should go in the main plugin file, and should be added beneath the header information.
//Defining Constants
define( 'WEEB_RELATED_POSTS_PLUGIN_DIR', plugin_dir_path( __FILE__ ).'/' );
define( 'WEEB_RELATED_POSTS_WEB_PATH', plugins_url("weeb-related-posts") ."/");The first constant holds the directory path to the plugin folder and the second holds the web path to the plugin folder. These will be used throughout the tutorial to include classes/other PHP files and to add media to webpages respectively.
The next step includes taking advantage of WordPress hooks with the aim of manipulating page content. The code should be added to the main plugin file, beneath the constants we defined in the previous step.
//Hooks function to 'the_content' filter.
add_filter('the_content','related_posts');
//Callback function for the above.
function related_posts($content)
{
//Gives us access to the global post object.
global $post;
//Checking if on post page.
if ( is_single() ) {
//RELATED POSTS CODE GOES HERE
return $content;
}
else {
//else on blog page / home page etc, just return content as usual.
return $content;
}
}The ‘add_filter’ function can be used to hook into parts of the WordPress execution process. In this instance, we are executing the ‘related_posts’ function when ‘the_content’ action takes place. In case you were wondering what ‘the_content’ does, it provides an access point to the content of a page (after it has been retrieved from the database, and before it has been added to the page).
If you look at the ‘related_posts’ function, you will notice it has a single parameter, ‘$content’. When using this filter, this parameter is compulsory and is used to transfer the page content to the function. Another noteworthy point is that the function must always return the page content. And as an example of this, you’ll notice that the conditional (‘if’) statement returns the content in both possible outcomes.
That brings me on to the next point nicely – the purpose of the conditional statement. If you are familiar with WordPress development, you will probably know that ‘is_single()’ returns true if the user is on a ‘post’ page. So, the code is checking if the user is on a post page. If so, the related posts logic will be executed (when we write it), and if not the content is simply returned in its original state.
Step 5 – Getting the required information from the post.
At this stage we are going to write our first class which will be used to retrieve, format and store information about the current post. Eventually this class will be used by an additional class to locate related posts, but we will get to that later.
So, what information do we need to retrieve from the current post? Well, to fulfil our aim of locating related posts we will need to define what constitutes a relation. Can a post in the same category be considered a relation, or does it also need to have the same tags or a similar title? A quick brainstorming session produced the following list of potentially useful information:
- Post title
- Post Categories
- Post tags
Ideally, I’d like to check all 3 of the above against the database – this should be enough to solidly identify a relation. So, these are the bits of information that will be stored in the class.
Browse to the ‘Includes > Classes’ directory and create a new file called ‘weeb_relatable_properties.php’. Add the following code to the file.
class weeb_relatable_properties {
//Class properties.
protected $keywords;
protected $tags;
protected $categories;
protected $post;
/**
* Constructor
*
* @param object $post
*
*/
public function __construct($post) {
$this->post = $post;
}
}Hopefully this doesn’t require too much explanation. We have simply created a new class, defined some class properties & defined the constructor (executed automatically when class is instantiated). The class properties will be used to store the information discussed earlier. It’s probably worth noting that the ‘$keywords’ property will be used to hold the post title. I chose to name it ‘keywords’, rather than ‘title’ due to the fact that we will be breaking down the title into a bunch of keywords, rather than using it in its entirety.
The next step is to create a bunch of get/set methods, which will return a property value, or set a property value respectively. Let’s start with the categories property. The code below, along with the other get/set methods (yet to come), should be added to the ‘weeb_relatable_properties’ class, below the ‘__construct()’ method.
/**
* setCategories
*
* Gets array of categories and stores in class property.
*/
public function setCategories() {
$this->categories = wp_get_post_categories($this->post->ID);
}
/**
* getCategories
*
* Returns list of categories.
*
* @return array
*/
public function getCategories() {
if ( isset($this->categories) ) {
return $this->categories;
}
else {
return false;
}
}Nothing much to explain here. The ‘set’ method is simply making use of the ‘wp_get_post_categories’ function, passing in the ID from the post property as a parameter. The end result is an array of categories. This array is saved to the ‘categories’ property for use later in the tutorial.
The ‘get’ function simply returns the value if it is set, or returns false if not. As the getters will pretty much all be the same, from this point onwards I wont bother explaining them!
Next up, the get/set methods for the post tags.
/**
*
* Gets post tags and stores in array.
*
*/
public function setTags() {
$tags = wp_get_post_tags($this->post->ID, array("fields" => "ids"));
if ($tags) {
$this->tags = $tags;
}
else {
$this->tags = array();
}
}
/**
*
* If tags is set, returns @array tags.
*
* @return mixed
*/
public function getTags() {
if ( isset($this->tags) ) {
return $this->tags;
}
else {
return false;
}
}Again, the ‘set’ method is simply making use of a core WordPress function to return an array of tags. You may notice a second parameter has been passed to the function this time around. This is used to filter the results; in this case we only require the Id’s. You can also use the second parameter to set the order of the results, or to define which field should be used to order the results. If you ever find yourself stuck on the purpose of a WordPress function, always remember to checkout the documentation – it’s pretty comprehensive in most cases.
The below code handles setting the keyword property.
/**
*
* Breaks post title down into a bunch of keywords & stores in array.
*
*/
public function setKeywords() {
//Some words we don't really want to search by, it's not a comprehensive
//list, but it is a start.
$commonWords = array('a','able','about','above','abroad','according','accordingly','across','actually','adj','after','afterwards','again','against','ago','ahead','ain\'t','all','allow','allows','almost','alone','along','alongside','already','also','although','always','am','amid','amidst','among','amongst','an','and','another','any','anybody','anyhow','anyone','anything','anyway','anyways','anywhere','apart','appear','appreciate','appropriate','are','aren\'t','around','as','a\'s','aside','ask','asking','associated','at','available','away','awfully','b','back','backward','backwards','be','became','because','become','becomes','becoming','been','before','beforehand','begin','behind','being','believe','below','beside','besides','best','better','between','beyond','both','brief','but','by','c','came','can','cannot','cant','can\'t','caption','cause','causes','certain','certainly','changes','clearly','c\'mon','co','co.','com','come','comes','concerning','consequently','consider','considering','contain','containing','contains','corresponding','could','couldn\'t','course','c\'s','currently','d','dare','daren\'t','definitely','described','despite','did','didn\'t','different','directly','do','does','doesn\'t','doing','done','don\'t','down','downwards','during','e','each','edu','eg','eight','eighty','either','else','elsewhere','end','ending','enough','entirely','especially','et','etc','even','ever','evermore','every','everybody','everyone','everything','everywhere','ex','exactly','example','except','f','fairly','far','farther','few','fewer','fifth','first','five','followed','following','follows','for','forever','former','formerly','forth','forward','found','four','from','further','furthermore','g','get','gets','getting','given','gives','go','goes','going','gone','got','gotten','greetings','h','had','hadn\'t','half','happens','hardly','has','hasn\'t','have','haven\'t','having','he','he\'d','he\'ll','hello','help','hence','her','here','hereafter','hereby','herein','here\'s','hereupon','hers','herself','he\'s','hi','him','himself','his','hither','hopefully','how','howbeit','however','hundred','i','i\'d','ie','if','ignored','i\'ll','i\'m','immediate','in','inasmuch','inc','inc.','indeed','indicate','indicated','indicates','inner','inside','insofar','instead', 'interesting','into','inward','is','isn\'t','it','it\'d','it\'ll','its','it\'s','itself','i\'ve','j','just','k','keep','keeps','kept','know','known','knows','l','last','lately','later','latter','latterly','least','less','lest','let','let\'s','like','liked','likely','likewise','little','look','looking','looks','low','lower','ltd','m','made','mainly','make','makes','many','may','maybe','mayn\'t','me','mean','meantime','meanwhile','merely','might','mightn\'t','mine','minus','miss','more','moreover','most','mostly','mr','mrs','much','must','mustn\'t','my','myself','n','name','namely','nd','near','nearly','necessary','need','needn\'t','needs','neither','never','neverf','neverless','nevertheless','new','next','nine','ninety','no','nobody','non','none','nonetheless','noone','no-one','nor','normally','not','nothing','notwithstanding','novel','now','nowhere','o','obviously','of','off','often','oh','ok','okay','old','on','once','one','ones','one\'s','only','onto','opposite','or','other','others','otherwise','ought','oughtn\'t','our','ours','ourselves','out','outside','over','overall','own','p','particular','particularly','past','per','perhaps','placed','please','plus','post','posts','possible','presumably','probably','provided','provides','q','que','quite','qv','r','rather','rd','re','really','reasonably','recent','recently','regarding','regardless','regards','relatively','respectively','right','round','s','said','same','saw','say','saying','says','second','secondly','see','seeing','seem','seemed','seeming','seems','seen','self','selves','sensible','sent','serious','seriously','seven','several','shall','shan\'t','she','she\'d','she\'ll','she\'s','should','shouldn\'t','since','six','so','some','somebody','someday','somehow','someone','something','sometime','sometimes','somewhat','somewhere','soon','sorry','specified','specify','specifying','still','sub','such','sup','sure','t','take','taken','taking','tell','tends','th','than','thank','thanks','thanx','that','that\'ll','thats','that\'s','that\'ve','the','their','theirs','them','themselves','then','thence','there','thereafter','thereby','there\'d','therefore','therein','there\'ll','there\'re','theres','there\'s','thereupon','there\'ve','these','they','they\'d','they\'ll','they\'re','they\'ve','thing','things','think','third','thirty','this','thorough','thoroughly','those','though','three','through','throughout','thru','thus','till','to','together','too','took','toward','towards','tried','tries','truly','try','trying','t\'s','twice','two','u','un','under','underneath','undoing','unfortunately','unless','unlike','unlikely','until','unto','up','upon','upwards','us','use','used','useful','uses','using','usually','v','value','various','versus','very','via','viz','vs','w','want','wants','was','wasn\'t','way','we','we\'d','welcome','well','we\'ll','went','were','we\'re','weren\'t','we\'ve','what','whatever','what\'ll','what\'s','what\'ve','when','whence','whenever','where','whereafter','whereas','whereby','wherein','where\'s','whereupon','wherever','whether','which','whichever','while','whilst','whither','who','who\'d','whoever','whole','who\'ll','whom','whomever','who\'s','whose','why','will','willing','wish','with','within','without','wonder','won\'t','would','wouldn\'t','x','y','yes','yet','you','you\'d','you\'ll','your','you\'re','yours','yourself','yourselves','you\'ve','z','zero');
//Replacing all of the above words with '' - basically removing them from the string.
$title = preg_replace('/\b('.implode('|',$commonWords).')\b/i','',$this->post->post_title);
//Separating title into an array of individual words(Splits at each space)
$keywords = explode(" ", $title);
//Removing duplicate entries.
$keywords = array_unique($keywords);
//Removing empty entries.
$keywords = array_filter($keywords);
//Storing in class property.
$this->keywords = $keywords;
}
/**
*
* Returns an array of keywords.
*
* @return array
*/
public function getKeywords() {
if ( isset($this->keywords) ) {
return $this->keywords;
}
else {
return false;
}
}The setter function is slightly more complex than its predecessors, so let’s run over it line by line:
- The first line is a simple array containing a number of words that will be excluded from the script. The list of words contains adjectives and other such words which can’t be used reliably to identify a related post.
- The next line actually handles removing the words using the ‘preg_replace’ function(which takes 3 parameters). The first parameter is the pattern, this is used to identify specific parts of the string. In this case, the pattern is simply a list of words generated from the array discussed in point one (implode used to convert array to string). If you are wondering about the ‘\b’ operator, this tells the function to perform a ‘word boundary’ search. In other words, only search for whole words (As an example, ‘the’ will not be removed from the word ‘thesis’ when using a word boundary search). The second parameter is what replaces any matches, this can be pretty much anything, but seeing as we want to simply remove the words, they are replaced with an empty string. The third parameter is the string on which to perform the operation.
- The third line is used to convert the newly filtered title into an array of keywords. We will later use these to find related posts ( along with the tag/category information of course).
- The fourth line is pretty simple, duplicate entries are removed.
- Again very simply, just removing empty entries.
- And finally, we assign the keywords to the ‘keywords’ property.
The final method is a simple getter which will return the post id.
/**
*
* Returns the post id.
*
* @return array
*/
public function getID() {
if ( isset($this->post) ) {
return $this->post->ID;
}
else {
return false;
}
}OK – that’s the first class complete. In the next step we will cover instantiating this class.
Step 6 – Instantiating the class.
To instantiate the class, you will need open the main plugin file & edit the ‘related_posts’ function as below.
//Callback function for the above.
function related_posts($content)
{
//Gives us access to the global post object.
global $post;
//Checking if on post page.
if ( is_single() ) {
//Including classes
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/classes/weeb_relatable_properties.php");
//Instantiating object which retrieves post details.
$postProperties = new weeb_relatable_properties($post);
//Storing the required properties.
$postProperties->setCategories();
$postProperties->setKeywords();
$postProperties->setTags();
return $content;
}
else {
//else on blog page / home page etc, just return content as usual.
return $content;
}
}The ‘weeb_relatable_properties’ class has now been instantiated & contains the necessary data in the necessary format. We are almost ready to create the next class, which will handle fetching the related posts. I’m going to skip ahead slightly now, and show you how this class will be instantiated. This might seem a bit counter intuitive at this point, but bear with me.
//Instantiating object which retrieves post details.
$postProperties = new weeb_relatable_properties($post);
//Storing the required properties.
$postProperties->setCategories();
$postProperties->setKeywords();
$postProperties->setTags();
$getRelatedPosts = new weeb_related_posts(2);
//Setting the parameters for WP_query.
$getRelatedPosts->set_query_args(
array(
//Returning posts in these categories only
'category__in' => $postProperties->getCategories(),
//Returning posts with these tags.
'tag__in' => $postProperties->getTags(),
//Exclude these posts - ontains a single post only to start with(the post currently being viewed).
'post__not_in' => array($postProperties->getID()),
//Max number of posts to return.
'posts_per_page'=> $required_posts,
//Custom parameter, used to add additional SQL to query.
'search_prod_title' => $postProperties->getKeywords()
)
);As you can see, the ‘weeb_relatable_properties’ class has been instantiated, along with the ‘weeb_related_posts’ class. Finally the ‘set_query_args’ method is called, making use of the ‘relatable_properties’ class to attain the necessary values. An alternative to this method would have been to simply instantiate the ‘weeb_relatable_properties’ class from within the ‘related_posts’ class – this would reduce the configuration required upon instantiation.
However, it would also mean the class becomes dependent on the ‘relatable_properties’ class. This type of dependency should generally be avoided as it makes your application less modular & makes unit testing difficult – we are not going to cover unit testing in this tutorial, but it’s always a good habit forming exercise to follow best practices. When you have a class that requires external configuration, always ‘inject’ the object using either the constructor, or alternatively, use a setter method. This is known as dependency injection.
Anyway, this leads me on to my next point. Since the instantiation of the ‘weeb_related_posts’ class is quite complex – having to instantiate dependencies, call setter methods etc – it makes sense to abstract this complexity away. This is where the factory pattern comes in handy.
The factory pattern is used to add a layer of abstraction to the process of instantiating and configuring objects. You should consider making use of the factory pattern when the object you are trying to create relies on one, or more, other objects, or has an otherwise complex instantiation process. I’d like to talk more about the pattern, but it’s a little outside the scope of this tutorial – if you are interested though, please check out stack overflow for a good idea of how/when it should be used.
You will find our factory class below. This should be added to the ‘includes/classes’ directory.
class weeb_related_posts_factory {
public static function create($post, $required_posts) {
//Instantiating object which retrieves post details.
$postProperties = new weeb_relatable_properties($post);
//Storing the required properties.
$postProperties->setCategories();
$postProperties->setKeywords();
$postProperties->setTags();
$getRelatedPosts = new weeb_related_posts($required_posts);
//Setting the parameters for WP_query.
$getRelatedPosts->set_query_args(
array(
//Returning posts in these categories only
'category__in' => $postProperties->getCategories(),
//Returning posts with these tags.
'tag__in' => $postProperties->getTags(),
//Exclude these posts - ontains a single post only to start with(the post currently being viewed).
'post__not_in' => array($postProperties->getID()),
//Max number of posts to return.
'posts_per_page'=> $required_posts,
//Custom parameter, used to add additional SQL to query.
'search_prod_title' => $postProperties->getKeywords()
)
);
return $getRelatedPosts;
}
}The class has a single method which accepts two parameters. The first is the wordpress ‘post’ object, which is passed to the ‘relatable’ class. The second is the number of posts which should be returned. You will notice that the ‘create’ function contains all of the instantiation code we discussed previously.
When instantiating the ‘related_posts’ object in our main plugin-file, we can now simply call the ‘create’ method. Let’s go back to the main plugin file, and do so. Edit the ‘related_posts’ function as below:
//Callback function for the above.
function related_posts($content)
{
//Gives us access to the global post object.
global $post;
//Checking if on post page.
if ( is_single() ) {
//Including classes
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/classes/weeb_relatable_properties.php");
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/classes/weeb_related_posts.php");
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/classes/weeb_related_posts_factory.php");
//Other includes
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/weeb_functions.php");
//Using a factory to abstract away the process of instantiating related posts object.
$getRelatedPosts = weeb_related_posts_factory::create($post, 2);
}
else {
//else on blog page / home page etc, just return content as usual.
return $content;
}
}If you attempt to run the code now, you will be presented with an error. That’s because the ‘weeb_related_posts’ class does not exist as of yet. Let’s create that next.
Step 7 – Create the related posts class.
As with the other classes, this should be placed in the ‘includes/classes’ directory. Let’s start with the basics:
class weeb_related_posts {
//Class properties
protected $num_posts;
protected $num_required;
protected $posts;
protected $query_args;
protected $related_query;
public function __construct($num_required = 2) {
$this->num_required = $num_required;
//Adding additional SQL to WP_Query temporarily - used to search title for any of the keywords.
add_filter( 'posts_where', array($this, 'title_filter'), 10, 2 );
}
}The required properties have been defined along with the constructor(which simply accepts a single value and assigns it to the ‘num_required’ property). As you may have guessed, this will be used to determine how many posts should be returned. A default value of 2 has been set for this parameter.
The constructor is also adding a filter to the WordPress ‘posts_where’ query. This will be used to alter the SQL code of the query so that it is possible to add a ‘LIKE’ clause on the title field. You may be wondering why we need to use a filter to query against the title. Well, this is due to the limitations of the ‘Wp_Query’ class, which does not support a post title parameter. Here is a list of parameters if you are interested in what is supported.
Anyway, here is the ‘title_filter’ method:
/**
*
* Filter used to add additional sql to wp_query.
*
* @param $where
* @param $wp_query
* @return string
*/
public function title_filter($where, &$wp_query) {
global $wpdb;
if ( $search_term = $wp_query->get( 'search_prod_title' ) ) {
$count = 0;
foreach ( $wp_query->get( 'search_prod_title' ) as $keyword ) {
if ( $count == 0 ) {
$where .= ' AND (' . $wpdb->posts . '.post_title LIKE \'%' . esc_sql( like_escape( $keyword ) ) . '%\'';
}
else {
$where .= ' OR ' . $wpdb->posts . '.post_title LIKE \'%' . esc_sql( like_escape( $keyword ) ) . '%\'';
}
$count++;
}
$where .= ")";
}
return $where;
}A breakdown of this method:
- Check if the ‘search_prod_title’ parameter is set – this is the array passed in via the ‘set_query_args’ method.
- If it is set, then loop through the array, else return the query as usual.
- On the first iteration, append an ‘AND’ statement. Example: ‘AND’ post_title’ LIKE ‘%wordpress%’
- On the following iterations, append and ‘OR’ statement.
Next we need to define a couple of basic functions which will handle getting/setting values. Add these below the constructor.
/**
*
* Used to assign search parameters to class property.
*
* @param $argsArray Array containing parameters for WP_Query
*/
public function set_query_args($argsArray) {
//Defining arguments for wp_query.
$this->query_args = $argsArray;
}
/**
*
* Returns the number of posts currently stored in $this->posts
*
* @return int
*/
public function getNumPosts() {
return $this->num_posts;
}
/**
*
* Adds an ID to the ignore list so that it will not be returned
* in future queries.
*
* @param $id post id
*/
public function store_ID($id) {
if ( isset($this->query_args['post__not_in']) ) {
$this->query_args['post__not_in'][] = $id;
}
else {
$this->query_args['post__not_in'] = array();
$this->query_args['post__not_in'][] = $id;
}
}You may remember the ‘set_query_args’ function from earlier (called in the factory). The function accepts an array and stores it to a class property. This array will need to contain specific indexes(refer to the factory to see them) as it is passed in to the ‘wp_query‘ class. I believe ‘getNumPosts’ is pretty much self explanatory, no need for explanation I hope.
The third method, ‘store_ID’, is used to keep a record of the posts which have already been identified. For example, if the first query (the most restrictive) identifies a post as being related, it’s ID will be stored & it will be ignored in future queries. The function itself is simple enough, if the array already exists, a new index is created & the id is assigned to it, else the array is created before doing so.
Now, a little explanation may be required before the next step. As mentioned at the start of the tutorial, it’s possible that the query will return more posts than we need. So, to ensure the most relevant results are given priority, the first query will check for any posts that are in the same category, which share a tag and have a similar title. If the required number of posts is not found, then the query will be made less restrictive & then repeated until the required number of posts has been found, or until all options have been exhausted.
To implement this functionality, a recursive function has been used. If you are unfamiliar with the term, a recursive function will call itself over and over until a certain criteria has been met. In our case, it will repetitively call itself until the required number of posts are found, or until it is no longer possible to make the query less restrictive. You can find the function below, add this to the class, just below the constructor.
public function getRelatedPosts() {
//Run query.
$this->related_query = new WP_Query($this->query_args);
while ( $this->related_query->have_posts() ) {
$this->related_query->the_post();
//Store posts to class property.
$post = array();
$post['title'] = get_the_title();
$post['url'] = get_permalink();
$post['image'] = get_the_post_thumbnail(get_the_ID());
//Keeping track of the number of posts matched.
$this->num_posts ++;
//Maximum posts to be returned by next query.
$this->query_args['posts_per_page'] -= $this->num_posts;
//Keeping track of the exact posts matched, so that they are not returned more than once.
$this->store_ID(get_the_ID());
//Storing post details in array.
$this->posts[] = $post;
}
//Check if enough posts returned
if ($this->num_posts < $this->num_required && $this->diminish_search_criteria()) {
return $this->getRelatedPosts();
}
else {
//Remove the filter, no longer needed.
remove_filter('posts_where', array($this, 'title_filter'));
return $this->posts;
}
}The first line of code is creating a new instance of the ‘Wp_Query’ class, passing along the parameters stored in the ‘query_args’ property. Just in case you forgot, here is a reminder of the parameters we passed in earlier:
array(
//Returning posts in these categories only
'category__in' => $postProperties->getCategories(),
//Returning posts with these tags.
'tag__in' => $postProperties->getTags(),
//Exclude these posts - ontains a single post only to start with(the post currently being viewed).
'post__not_in' => array($postProperties->getID()),
//Max number of posts to return.
'posts_per_page'=> $required_posts,
//Custom parameter, used to add additional SQL to query.
'search_prod_title' => $postProperties->getKeywords()
)Breakdown of the While loop:
- The query is executed upon instantiation, making it possible to loop through the results using the ‘have_posts()’ method. On each iteration ‘the_post’ method is exectued which retrieves & sets up the next post in the queue. This makes it possible to retrieve information about the post using methods such as ‘get_the_title()’.
- Using the aforementioned methods, a new array is generated and populated with information about the post.
- Next, the ‘num_posts’ property is incremented, making it possible to keep track of how posts have been matched.
- Similarly, the ‘posts_per_page’ index in the ‘query_args’ array is decremented. This tells WordPress how many posts to return, so if our initial value was 2, and 1 post was found, then then value will be reduced to 1. This means that on the following query, WordPress will return 1 post only, giving us a total of 2 posts.
- The ‘store_ID’ method is called – as explained earlier, this basically tells WordPress to ignore this post in future queries.
- The final line of code (in the while loop) assigns the array containing information about the post to the ‘posts’ property(which is also an array).
Breakdown of the conditional(‘if’) statement:
The ‘if’ statement is used to determine whether or not further recursion is required. To make this decision the following happens:
- If the amount of posts returned thus far is less than the amount required, and it is possible to make the search criteria less restrictive then the function calls itself again.
- If the above is false, then the title filter is removed, and the posts are returned.
We’ve not covered the ‘diminish_search_criteria’ method yet, so let’s take a look at that next.
/**
*
* Makes the search criteria less restrictive on each call. Returns false
* if this is no longer possible - used to halt the recursion in
* 'getRelatedPosts()'
*
* @return bool
*/
public function diminish_search_criteria() {
//No longer restricting results by title
if ( isset($this->query_args['search_prod_title'])) {
unset($this->query_args['search_prod_title']);
return true;
}
//No longer restricting results by category
if ( isset($this->query_args['category__in'])) {
unset($this->query_args['category__in']);
return true;
}
return false;
}This function will return a boolean value – either ‘true’ or ‘false’. The return value is determined by the existence of either the ”search_prod_title’ index, or the ”category__in’ index. If the first index exists, then it is destroyed using the ‘unset’ method, and the returned value is ‘true’. Similarly, if the first index does not exists, but the second does, then the second is destroyed and again the returned value is ‘true’. So, in plain english terms, this is how the search will operate:
- Search for products that match on all 3 columns – post title, category and tag.
- If the above search does not produce the required amount of posts, then search by category and tag only.
- If the above search is also unsuccessful, then search for posts in the same category only.
Once it is no longer possible to make the search criteria less restrictive, then ‘false’ is returned – at which point the recursive function is halted, and the posts are returned.
At this point the class is complete. Browse back to the main plugin file, and update the ‘related_posts’ method so that it resembles the code block below.
//Callback function for the above.
function related_posts($content)
{
//Gives us access to the global post object.
global $post;
//Checking if on post page.
if ( is_single() ) {
//Including classes
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/classes/weeb_relatable_properties.php");
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/classes/weeb_related_posts.php");
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/classes/weeb_related_posts_factory.php");
//Other includes
include(WEEB_RELATED_POSTS_PLUGIN_DIR."includes/weeb_functions.php");
//Using a factory to abstract away the process of instantiating related posts object.
$getRelatedPosts = weeb_related_posts_factory::create($post, 2);
//Fetching the related posts.
$related = $getRelatedPosts->getRelatedPosts();
//Checking for related posts.
if ( count($related) > 0 ) {
//Add the stylesheet.
wp_enqueue_style( 'myPluginStylesheet', plugins_url('css/weeb_related_posts.css', __FILE__) );
//Storing HTML to variable.
$rel_html = weeb_related_posts_get_template(WEEB_RELATED_POSTS_PLUGIN_DIR ."templates/related-posts.php", $related);
//Adding custom content to end of post.
return $content . $rel_html;
}
//no posts, return content as usual.
else {
return $content;
}
}
else {
//else on blog page / home page etc, just return content as usual.
return $content;
}
}After using the factory class to create an instance of the ‘related_posts’ class, the ‘getRelatedPosts’ method is called, and the results are stored in a variable named ‘$related’. If you remember how the method works, then you will know that this variable now contains an array of related posts (2 in this case).
A conditional statement then checks how many entries are in the array and if there is more than 0, the related posts are appended to the content. You will notice that a stylesheet has been added to the page, along with a call to the ‘weeb_related_posts_get_template’ function. Since these do not actually exist yet, the next step will be to create them.
Step 8 – Create the stylesheet.
I’m going to keep it simple with the styling due to the fact that CSS is outside the scope of this tutorial. Create a file named ‘weeb_related_posts.css’ in the ‘css’ directory. Add the below code to it:
#weeb-related-posts, #weeb-related-posts li, #weeb-related-posts h4, #weeb-related-posts a {
margin:0;
padding:0;
text-decoration: none;
}
#weeb-related-title {
margin-bottom:16px;
}
#weeb-related-posts {
list-style:none;
overflow: hidden;
}
#weeb-related-posts li {
float:left;
widtH:48%;
margin-left:4%;
}
#weeb-related-posts li img {
widtH:100%;
height:180px;
}
#weeb-related-posts li:first-child {
margin-left:0;
}This should be enough to position the posts & remove any unwanted styling. Let’s move on to the next step – the ‘weeb_related_posts_get_template’ function.
Before we take a look at the function definition, lets create the template. Add a file named ‘related-posts.php’ to the template directory, the following code should be placed in this file.
<h3 id="weeb-related-title"> You may also like these posts: </h3>
<ul id="weeb-related-posts">
<?php
foreach ( $data as $the_post) {
echo "<li>";
echo "<a href=\"".$the_post['url'] ."\">";
if ( $the_post['image'] ) {
echo $the_post['image'];
}
else {
echo "<img src=\"".WEEB_RELATED_POSTS_WEB_PATH."img/no_image_medium.gif\" alt=\"no-image\" />";
}
echo "<h4> ".$the_post['title']."</h4>";
echo "</a>";
echo "</li>";
}
?>
</ul>At this stage, you may be wondering where the hell the ‘$data’ variable is coming from. This will become clear when you create the ‘weeb_related_posts_get_template’ function below.
Just so you are aware, the function is used to keep our markup separate from our logic, this is generally thought of as a good idea and is pretty much always recommended. Why? Well, it makes maintenance easier for one. If you’ve ever worked on a site that mixes HTML with PHP, you’ll know what I’m talking about! If not, count yourself lucky.
Anyway, below, you can see how the function works – this should be added to a file named ‘weeb_functions.php’, which should be placed in the ‘includes’ directory. Note: The second parameter is named ‘$data’, hopefully the template above should make more sense now!
function weeb_related_posts_get_template( $template, $data )
{
ob_start();
$test = include($template);
$echoed_content = ob_get_clean();
return $echoed_content ;
}If you are not familiar with output buffering, this function may look a little confusing. Here’s how it works:
- If you look at the function you will notice the template passed in via the parameter is imported - using the ‘include’ function. This would normally output the contents of the file straight to the browser. In this case, this is not the desired result. If you think back to the main plugin file, the aim is to retrieve the related posts, generate the HTML and append it to the existing page content. WordPress handles rendering the content later.
- The function ‘ob_start’ is used to start output buffering. This basically prevents the following lines from being immediately sent to the browser, and instead allows you to store the result to a variable, using the ‘ob_get_clean()’ function.
- So, to recap, the function makes use of output buffering to import a template & store the results to a variable.
Develop a related posts plugin: The final Result
If you load up a post now, you should see the related posts are appended to the end of the content section. Obviously, you will need to have some posts which are related to one another for this to be true though – you already knew that, of course.
Hopefully you learnt a thing or two today & will feel confident in your ability to create your own WordPress plugins moving forward. I always find it useful to look back over my code when I finish a task to review what I could have done differently, or to look for any potential improvements. In this case, for example, I believe the plugin could be improved by storing the related posts in the database, so that the complex query used to identify relations does not run each time a post is loaded. This should improve performance a lot – perhaps it’s something worth looking into if you are looking to progress your skills further.
This post took did take a little while to write, so my thought process may have have been a little fragmented – if you spotted any errors, please let me know!
The post Develop a related posts plugin for WordPress. appeared first on Weebtutorials.