Related Posts by Taxonomy

Quickly increase your readers’ engagement by adding related posts in the sidebar or after post content with a widget or shortcode.

Posts with the most terms in common will display at the top!

This plugin is capable of finding related posts in multiple taxonomies and post types. Include or exclude terms from the search for related posts. Change the look and feel by using your own templates in your (child) theme.

Plugin features:

• Widget and Shortcode
• Post thumbnails, links, excerpts or full posts.
• Small Footprint. Doesn’t slow down your site!
• Search for related posts in single or multiple taxonomies and post types.
• Exclude or include terms and posts.
• Limit the search of related posts by date or number.
• Limit the search of related posts by post meta.
• Automatic display of related posts after the post content.
• Use your own Html templates for display of the related posts.
• Use the WordPress REST API to get related posts. (opt-in feature)
• Use a persistent cache to get the related posts. (opt-in feature)
• Use plugin functions in your theme templates to display related posts yourself.
• Optimize the query for related posts
• Use Filters to change the default behavior of the plugin.
• Highly Adjustable!
• Follows WordPress coding standards and plugin best practices.

Download the plugin from the WordPress plugin repository: Related Posts by Taxonomy Plugin

For support visit the WordPress forums.

Visit the github repository for the development version.

The plugin documentation

Use the links below to navigate to a specific section in the documentation:

• How to install the plugin
• Widget
• Shortcode
• Adding related posts after the post content
• Post thumbnails (featured image)
• Functions
• Filters
• Templates
• Plugin Recipes
• Widget usage outside the loop
  • Custom queries with WP_Query()
• wp rest api
• query optimizations
• Cache

Note: It’s recommended you create a child theme whenever the documentation provides a way to modify the plugin by adding code to theme template files.

How to install the plugin

1. Unzip the related-posts-by-taxonomy.zip folder.
2. Upload the related-posts-by-taxonomy folder to your /wp-content/plugins directory.
3. Activate Related Posts by Taxonomy.
4. That’s it, now you are ready to use the widget and shortcode.

Widget

The widget allows you to display related posts in the widgetized areas of your theme. Usually you can add widgets in the sidebar or footer, however these widget-ready areas can also be in the header, below content, and basically any other area in your theme. You can find the widget by going to the Appearance » Widgets admin page.

The display settings

You can choose from four different display formats:

1. links: display a list of related post links
2. posts: display a list of full posts
3. excerpts: display a list of excerpts
4. thumbnails: display a list of post thumbnails (version 0.2)

To override (edit) the templates used to display these formats see: Templates

For more information about the post ID and the widget outside the loop see Usage outside the loop.

To filter the widget see the widget filters.

Shortcode

A shortcode is a WordPress-specific code to publish dynamic content using macros, without the need for programming skills. When a shortcode is inserted in a WordPress post or page editor, it is replaced with some other content.

Basic usage

[related_posts_by_tax]

This in your post content will be replaced with a list of related posts.

Shortcodes can also be used with additional attributes as the following example shows:

[related_posts_by_tax format="thumbnails" image_size="medium"]

This will be replaced by medium sized related thumbnails.

Note: To add the related posts automatically after the post content it’s recommended you use this method instead of the shortcode.

attributes:

• post_id
• taxonomies
• post_types
• posts_per_page
• fields
• order
• orderby
• before_shortcode
• after_shortcode
• title
• before_title
• after_title
• show_date
• include_terms
• include_parents
• include_children
• exclude_terms
• exclude_posts
• format
• image_size
• columns
• caption
• link_caption
• limit_posts
• limit_year
• limit_month
• meta_key
• meta_value
• meta_compare
• meta_type
• public_only
• include_self
• post_class

All default attribute values can be filtered in your (child) theme’s functions.php file. This allows you to set your own defaults and more. See this Filter.

post_id

(int) Display related posts for a specific post ID. There is no default.

[related_posts_by_tax post_id="23"]

taxonomies

(string) Taxonomy name or a comma-separated list of taxonomy names. Default is empty string (Use all taxonomies to find related posts).

[related_posts_by_tax taxonomies="category,post_tag"]

post_types

(string) Post type name or a comma-separated list of post type names to search related posts in. Default none. The post type of the current post is used to get related posts for. If no post type is found it defaults to the ‘post’ post type.

[related_posts_by_tax post_types="post,movie"]

posts_per_page

(int) How many related posts to display. To display all related posts use -1. Default is 5.

[related_posts_by_tax posts_per_page="10"]

fields

(string) This affects what fields are returned by the related posts query. If you set it to ‘ids’ the query is smaller and faster than the default. Please read the ID query documentation before setting it to ‘ids’. Default empty string (return all fields)

[related_posts_by_tax fields="ids"]

order

(string) Start searching for related posts from latest post date, oldest post date or randomly.

• ‘DESC’ – from latest post date (show posts with most common terms first)(default).
• ‘ASC’ – from oldest post date (show posts with most common terms first).
• ‘RAND’ – random (show posts with terms in common randomly).

[related_posts_by_tax order="ASC"]

orderby

(string) Order by post date or by date modified.

• ‘post_date’ – order by date (and show posts with most common terms first)(default).
• ‘post_modified’ – order by last modified date (and show posts with most common terms first).

[related_posts_by_tax orderby="post_modified"]

before_shortcode

(string) Text or Html to place before the shortcode.
Default is <div class="rpbt_shortcode">.

after_shortcode

(string) Text or Html to place after the shortcode.
Default is </div>.

[related_posts_by_tax before_shortcode='<div>' after_shortcode='</div>' ]

title

(string) The title displayed above the related posts. Default is ‘Related Posts’. The title is removed if left empty.

[related_posts_by_tax title="My Related Posts"]

before_title

(string) Text or Html to place before the title. Default is <h3>.

after_title

(string) Text or Html to place after the title. The default is </h3>.

[related_posts_by_tax before_title='<h3 class="rpbt_title">' after_title="</h3>"]

show_date

(boolean) Show the post date after post titles. Default is ‘false’.

[related_posts_by_tax show_date="true"]

include_terms

(string) Search for related posts by term IDs. Use a comma separated list of term IDs. The posts are ordered by most terms in common. Default is an empty string (Query for related posts with the current post terms).

[related_posts_by_tax include_terms="20,23,14"]

include_parents

(boolean) Include parent terms in the query for related posts. Default false

[related_posts_by_tax include_parents="true"]

include_children

(boolean) Include child terms in the query for related posts. Default false

[related_posts_by_tax include_children="true"]

exclude_terms

(string) Exclude a comma separated list of term IDs. Default is an empty string (don’t exclude terms).

[related_posts_by_tax exclude_terms="20,23,14"]

If you get unexpected results see the plugin’s logic for excluding terms.

exclude_posts

(string) Exclude a comma separated list of post IDs. Default is an empty string (don’t exclude posts).

[related_posts_by_tax exclude_posts="83,102,44"]

format

(string) Display related posts as links, full posts, excerpts or post thumbnails.

• ‘links’ (default):
  • display a list of related post links.
  • template used for display: related-posts-links.php.
• ‘posts’:
  • display post title and full post.
  • template used for display: related-posts-posts.php.
• ‘excerpts’:
  • display post title and excerpt.
  • template used for display: related-posts-excerpts.php.
• ‘thumbnails’:
  • display post thumbnails and post title as caption (same as the gallery shortcode).
  • template used for display: related-posts-thumbnails.php.

To override (edit) the templates used for display see Templates

[related_posts_by_tax format="thumbnails"]

image_size

(string) Image size used for the format thumbnails (see above). Choose from the default image sizes thumbnail, medium, large, post-thumbnail and the image sizes set by the current theme. Default is ‘thumbnail’

[related_posts_by_tax image_size="medium" format="thumbnails"]

columns

(string) Set the number of image columns for the format thumbnails (see above). Default is 3

[related_posts_by_tax columns="2" format="thumbnails"]

caption

(string) Caption text for the post thumbnail. Choose from post_title, post_excerpt attachment_caption, attachment_alt, or a custom string. Default is ‘post_title’

[related_posts_by_tax caption="post_excerpt" format="thumbnails"]

link_caption

(bool) Link the caption to the related post. Default is ‘false’

[related_posts_by_tax link_caption="true" format="thumbnails"]

limit_posts

(string) Limit the search for related posts to the latest published posts only. Default is ‘-1’ (search in all posts). Example: search for related posts in the last 100 posts.

[related_posts_by_tax limit_posts="100"]

limit_year

(string) Limit the search for related posts to posts published in the past year(s). Default is an empty string (no limit). Example: search only in posts published within the last year.

[related_posts_by_tax limit_year="1"]

limit_month

(string) Limit the search for related posts to posts published in the past month(s). Default is an empty string (no limit). Example: search only in posts published within the last 6 months.

[related_posts_by_tax limit_month="6"]

meta_key

(string) Post meta key. See WP_Query for more information. Default empty string (no meta query)

[related_posts_by_tax meta_key="my_meta_key"]

meta_value

(string) Post meta value. Use a comma separated string for array values. See WP_Query for more information. Default empty string (no meta query)

[related_posts_by_tax meta_value="my_meta_value"]

meta_compare

(string) Operator to test the `meta_value`. Possible values are ‘=’, ‘!=’, ‘>’, ‘>=’, ‘<', '<=', 'LIKE', 'NOT LIKE', 'IN', 'NOT IN', 'BETWEEN', 'NOT BETWEEN', 'NOT EXISTS', 'REGEXP', 'NOT REGEXP' or 'RLIKE'. See WP_Query for more information. Default value is '='.

[related_posts_by_tax meta_value="my_meta_value" meta_compare="NOT LIKE"]

meta_type

(string) Post meta type. Possible values are ‘NUMERIC’, ‘BINARY’, ‘CHAR’, ‘DATE’, ‘DATETIME’, ‘DECIMAL’, ‘SIGNED’, ‘TIME’, ‘UNSIGNED’. See WP_Query for more information. Default value is ‘CHAR’.

[related_posts_by_tax meta_key="my_meta_key" meta_value="2" meta_type="NUMERIC"]

public_only

(boolean)(2.3.2) Exclude private posts in the related posts results even if the current user has the capability to see the private posts. Default is ‘false’ (include private posts). Example: exclude private posts.

[related_posts_by_tax public_only="true"]

include_self

(boolean)(2.3.2) Include the current post in the related posts results. Default is ‘false’ (exclude current post). Example: to include the current post.

[related_posts_by_tax include_self="true"]

post_class

(string). Add a class to the related post items. Default is an empty string (don’t add a class). Example: add the “my-class” class.

[related_posts_by_tax post_class="my-class"]

Adding Related Posts After the Post Content

Add related posts automatically after the post content by using a code snippet in your (child) theme’s functions.php file

Example with four related posts after the content on all single post pages.

Note: See below this code snippet how you can change it to suit your needs.

add_filter( 'the_content', 'add_related_posts_after_post_content' );
function add_related_posts_after_post_content( $content ) {

	//check if it's a single post page.
	if ( is_single() ) {

		// check if we're inside the main loop
		if ( in_the_loop() && is_main_query() ) {

			// add your own attributes here (between the brackets [ ... ])
			$shortcode = '[related_posts_by_tax posts_per_page="4"]';

			// add the shortcode after the content
			$content = $content . $shortcode;
		}
	}

	return $content;
}

Adding your own attributes to the code above
Add the attributes to the code snippet above as you would with the shortcode in the post editor. Let’s say you want to have the code snippet above show six medium sized related thumbnails. All you would have to do is change this:

$shortcode = '[related_posts_by_tax posts_per_page="4"]';

to this:

$shortcode = '[related_posts_by_tax posts_per_page="6" format="thumbnails" image_size="medium"]';

See the shortcode attributes you can add to the $shortcode variable.

Widget usage outside the loop

If the widget is used outside the loop (like in a sidebar) and no post ID is provided in the widget’s settings it gets the first post ID for that page request (e.g. on a category archive page it will get the post ID from the first post of that category archive page).

Custom queries with WP_Query()

To let the widget get the first post ID outside the loop on pages that query the main loop with new WP_Query you have to make some alterations after the query:

<?php // example query
$the_query = new WP_Query('cat=3');

// add this right after the query
// use the query object ($the_query) to check if posts are found
$the_query_id = ( isset( $the_query->post->ID ) ) ? $the_query->post->ID : 0;
set_query_var( 'km_rpbt_related_post_id', $the_query_id );
?>