Related Posts Recipes

This page is part of the plugin documentation for the Related Posts by Taxonomy plugin.

Here you’ll find some custom ways of using this plugin.

Setting your own defaults for the shortcode.

By setting your own defaults you don’t need to type in shortcode attributes anymore. For example, you allways want to show related medium thumbnails with the shortcode. Normally you would need to type this for the shortcode every time you use it:

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

As you see we used the attributes “format” and “image_size”. Lets add the defaults for these attributes ourselves by using this filter.
Put this code in your (child) theme’s functions.php.

add_filter( 'related_posts_by_taxonomy_shortcode_defaults', 'my_related_post_shortcode_defaults' );
function my_related_post_shortcode_defaults( $defaults ) {
    $defaults['format']     = 'thumbnails';
    $defaults['image_size'] = 'medium';
    return $defaults;

After using this in your your theme all you need to type for the shortcode is this.


Now the thumbnails will display instead of the default “links” format. See more examples for the usage of the filter.

Get better random posts.

By default if you use the ‘RAND’ order attribute this plugin will get the related posts and randomize the results. This can lead to seeing the same 5 randomized related posts on every related posts page. By using this in your (child) theme’s functions.php the posts are randomized from a larger group of related posts (set by the ‘posts_per_page’ attribute).

add_filter( 'related_posts_by_taxonomy', 'related_posts_by_taxonomy_randomize', 10, 4 );

function related_posts_by_taxonomy_randomize( $related_posts, $post_id, $taxonomies, $args ) {

	// Randomize the related posts.
	shuffle( $related_posts );

	// Get the first five randomized posts.
	// change 5 to how many related posts you want to show
	$related_posts = array_slice( (array) $related_posts, 0, 5 );

	return $related_posts;

Make sure you don’t set the ‘order’ value to ‘RAND’ but instead set the ‘posts_per_page’ attribute to an amount larger than 5 (or whatever amount you want to show) to randomize the found posts.

Sort posts alphabetically

With this in your (child) theme’s functions.php the posts will be sorted alphabetically.

add_filter( 'related_posts_by_taxonomy', 'related_posts_by_taxonomy_orderby_title', 10, 4 );

function related_posts_by_taxonomy_orderby_title( $results, $post_id, $taxonomies, $args ) {
	usort( $results, 'km_rpbt_sort_by_title' );
	return $results;

function km_rpbt_sort_by_title( $a, $b ) {
	return strcasecmp( $a->post_title, $b->post_title );

Styling the shortcode and widget.

All styling for the widget and shortcode is provided by your theme. Add your own styles to your (child) theme’s stylesheet to style them differently.

Styling the thumbnails
To style the thumbnails see the the thumbnails section.

Styling the shortcode
Since 1.0 the shortcode title is a '<h3>' heading and the shortcode itself is wrapped in a div with a class “rpbt_shortcode”. You can change the '<h3>' heading tags with the before_title and after_title attributes. Or set a default for it.

Style the shortcode like this in your (child) theme’s stylesheet:

// shortcode container
.rpbt_shortcode {
	/* your styles here */

// title
.rpbt_shortcode h3 {
	/* your styles here */

Including and excluding terms.

The logic behind including and excluding terms is a bit tricky. Read below how the plugin fetches related posts when including or excluding terms.

Including terms
You can include terms with the include_terms parameter.

By default the plugin gets the current post terms and searches for related posts with the included terms if the current post has the included terms. If you need to list posts with the included terms, even if the current post doesn’t have any of the included terms, you can use the related parameter.

Example for the shortcode showing posts with terms 23 and 27 even if the current post doesn’t have those terms.

[related_posts_by_tax include_terms="23,27" related="false"]

Excluding terms
You can exclude terms with the exclude_terms parameter.

By default the plugin gets the current post terms and removes the exclude terms from the terms found. Then it searches for related posts within the remaining terms and orders them by relatedness. The found posts however can still have one or more of the excluded terms. It’s a mind bender🙂

If you need to totally exclude posts that have the excluded terms you’ll need the following code snippet in your (child) theme’s functions.php. It adds the posts that have the exclude_terms ids assigned to the exclude_posts argument.

// Exclude terms with the widget.
add_filter( 'related_posts_by_taxonomy_widget_args', 'related_posts_exclude_terms_widget' );

function related_posts_exclude_terms_widget( $args ) {
	// Example to exclude terms with ids 23 and 27 for the widget

	// change the term ids you want to exclude here
	$args['exclude_terms'] = array( 23, 27 );

	// Add excluded post ids to the exclude_posts argument.
	$args = related_posts_exclude_terms_strict( $args );

	// return $args with excluded terms and excluded posts.
	return $args;

// For the shortcode
// use exclude_terms in the shortcode to exclude terms
add_filter( 'related_posts_by_taxonomy_shortcode_atts', 'related_posts_exclude_terms_strict' );

 * This function queries for all posts that have terms from the exclude_terms parameter.
 * And adds the ids to the exclude_posts parameter.
function related_posts_exclude_terms_strict( $args ) {
	global $wpdb;

	if ( empty( $args['exclude_terms'] )  ) {
		return $args;

	$exclude_terms = $args['exclude_terms'];

	// Make exclude_terms an array if it's a string.
	if ( !is_array( $args['exclude_terms'] ) ) {
		$exclude_terms = explode( ',', (string) $args['exclude_terms'] );

	// Sanitize the excluded terms.
	$exclude_terms = array_filter( array_map( 'intval', $exclude_terms ) );
	$exclude_terms = array_values( array_unique( $exclude_terms ) );

	if ( empty( $exclude_terms ) ) {
		return $args;

	// esc ids for use in query
	$exclude_terms = array_map( 'esc_sql', $exclude_terms );

	$term_ids_sql = "tt.term_id IN (" . implode( ', ', $exclude_terms ) . ")";

	$query = "
        SELECT p.ID FROM $wpdb->posts p
        LEFT JOIN $wpdb->term_relationships t ON (p.ID = t.object_id)
        WHERE EXISTS (
            SELECT tt.term_taxonomy_id FROM $wpdb->term_taxonomy tt
            WHERE tt.term_taxonomy_id = t.term_taxonomy_id
            AND {$term_ids_sql}
        ) GROUP BY p.ID

	// Get posts (ids) with the excluded terms assigned.
	$results = $wpdb->get_col( $query );

	if ( !empty( $results ) ) {
		// Add excluded posts to the arguments.
		$args['exclude_posts'] = $results;

	// Return arguments.
	return $args;

Use a post thumbnail fallback image

By default only posts with post thumbnails are found if you use the format thumbnails. But what if you wanted to search for all posts and use a fallback image if a post doesn’t have a post thumbnail.

Use the code below in your (child) theme’s functions.php to use a new “images” format in the widget and shortcode.
Screen Shot 2015-06-07 at 16.27.59

This is how you use it in the shortcode.

[related_posts_by_tax format="images"]

The code below will display images in this order:

  • If there is a post thumbnail, it will show it like it already does.
  • If there is no post thumbnail, it shows the first attached image if there is one.
  • Optional, If no attached image is found, you can set your own fallback image in the code below where it says Use your own fallback image here.
// Adds the 'Post Images' format to the widget
// after the plugin's defaults are set (priority 11).
add_action( 'wp_loaded', 'rpbt_add_post_images_format_widget', 11 );

function rpbt_add_post_images_format_widget() {

	if ( !class_exists( 'Related_Posts_By_Taxonomy_Defaults' ) ) {

	$defaults = Related_Posts_By_Taxonomy_Defaults::get_instance();

	// Add the new format.
	$defaults->formats['images'] = __( 'Post Images' );

// Sets the format to thumbnails if the Post Images format is used.
// Adds filters to remove the sql used to only find posts with post thumbnails.
add_filter( 'related_posts_by_taxonomy_shortcode_atts', 'rpbt_post_images_format' );
add_filter( 'related_posts_by_taxonomy_widget_args', 'rpbt_post_images_format' );

function rpbt_post_images_format( $args ) {

	// Check if the new images format is used.
	if ( 'images' === $args['format'] ) {

		// Set format to thumbnails if Post Images format is used.
		$args['format'] = 'thumbnails';

		// Removes the sql to search for posts with post thumbnails only.
		add_filter( 'get_meta_sql', '__return_empty_string', 23 );

		// Removes the filter after related posts are retrieved.
		add_filter( 'related_posts_by_taxonomy', 'rpbt_remove_meta_sql_filter' );

		// Removes the filter if no related posts were found.
		add_action( 'related_posts_by_taxonomy_after_display', 'rpbt_remove_meta_sql_filter' );

	return $args;

// Remove the filter
function rpbt_remove_meta_sql_filter( $results ) {
	remove_filter( 'get_meta_sql', '__return_empty_string', 23 );
	return $results;

// Use a fallback image if a post has no post thumbnail.
add_filter( 'related_posts_by_taxonomy_post_thumbnail_link', 'rpbt_related_post_fallback_image', 10, 4 );

function rpbt_related_post_fallback_image( $image, $attr, $related, $args ) {

	if ( !empty( $image ) ) {
		// Post thumbnail found.
		return $image;

	$image_args = array(
		'numberposts' => 1,
		'order' => 'ASC',
		'post_mime_type' => 'image',
		'post_parent' => $related->ID,
		'post_status' => null,
		'post_type' => 'attachment',

	$attachments = get_children( $image_args );

	if ( !empty( $attachments ) ) {
		// Post attachment image found.
		$attachments = array_values( $attachments );
		$attachment_id = (int) $attachments[0]->ID;

		// Use the first attachment image.
		$image = wp_get_attachment_image( $attachment_id , $args['size'], false, $attr['describedby'] );
	} else {
		 * Use your own fallback image here.
		 * Example of an image uploaded with the media editor.
		 * Change the attachment ID (123) below to your uploaded fallback image ID.
		 * And remove the two foreward slashes at the beginning.
		// $image = wp_get_attachment_image( 123, $args['size'], false, $attr['describedby'] );

	$image = $image ? "<a href='{$attr['permalink']}' title='{$attr['title_attr']}'>{$image}</a>" : '';

	return $image;

Here is a simple fallback image you can use:

See the url how you can change the text and dimensions. Right click and save the image.

Remove captions from post thumbnails

Add this to your (child) theme’s functions.php file.

add_filter('related_posts_by_taxonomy_caption', '__return_empty_string');

See this example to have thumbnail captions link to the related post.

Widget support for post type Page

Add this to your (child) theme’s functions.php file to add a post type Page checkbox to the widget.

// Add the 'page' post type just after the plugin's defaults are set (priority 11).
add_action( 'wp_loaded', 'add_widget_related_post_type_page', 11 );

function add_widget_related_post_type_page() {

	if ( !class_exists( 'Related_Posts_By_Taxonomy_Defaults' ) ) {

	$defaults = Related_Posts_By_Taxonomy_Defaults::get_instance();
	$defaults->post_types['page'] = __( 'Pages' );