Filters

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

Filters can be used to change (override) the default settings or behavior of the plugin. For example, the widget doesn’t show all options available (like exclude terms etc), you can change the default values with a filter if needed. Use conditional tags if you want to change the settings only on specific pages. These filters are code snippets that go in your (child) theme’s functions.php file.

Note: The filters below in red are not yet documented here.

General Filters

This filter is run after the related posts are retrieved from the database by this function (used by the widget and shortcode). It allows you to alter the related posts array before the posts are displayed.

add_filter( 'related_posts_by_taxonomy', 'my_related_posts_by_taxonomy_filter',10, 4 );
function my_related_posts_by_taxonomy_filter( $results, $post_id, $taxonomies, $args ) {
	// do stuff with the $results (array with related posts objects)
	return $results;
}

This filter lets you override the template used to display the related posts. For more information about this filter see Templates

Widget Filters

This filter is run before the widget retrieves the related posts from the database. It allows you to globally change the settings for all related posts widgets. See the shortcode attributes for all settings and their defaults. The only settings that can’t be filtered for the widget are ‘title’, ‘after_title’ and ‘before_title’ (because these are set by your theme).

Note: If you want to set new defaults for newly added widgets in the widgets admin page, or set new defaults but allow the related posts widgets to override them, use the WordPress core filters widget_form_callback and widget_display_callback

Example.
Exclude term ids 23 and 57 when searching for related posts by the widget, and return 10 related posts on the home page. Use this example in your (child) theme’s functions.php file.

add_filter( 'related_posts_by_taxonomy_widget_args', 'my_widget_filter', 10, 2 );
function my_widget_filter( $args, $instance ) {

	$args['exclude_terms'] = array( 23, 57 );
	
	if( is_home() ) {
		$args['posts_per_page'] = 10;
	}
	
	return $args;
}

This filter allows you to display the widget even if no related posts were found. You can change the default message “No related posts found” with your own Templates. Use this example in your (child) theme’s functions.php file to always display the widged.

// this will display the widget even if no results where found
add_filter( 'related_posts_by_taxonomy_widget_hide_empty', '__return_false' );

Shortcode Filters

This filter is run before the shortcode retrieves the related posts from the database. It allows you to set new defaults for the shortcode attributes. See the shortcode attributes for what defaults can be set.

Note: Shortcode attibutes used in the post editor override the settings used by this filter.

Examples

Change the default title ‘Related Posts’ to ‘My Related Posts by Taxonomies’ and make it a <h4> heading. Use this example in your (child) theme’s functions.php file.

add_filter( 'related_posts_by_taxonomy_shortcode_defaults', 'related_shortcode_title' );
function related_shortcode_title( $defaults ) {
	$defaults['before_title'] = '<h4 class="rpbt_title">';
	$defaults['title'] = 'My Related Posts by Taxonomies';
	$defaults['after_title'] = '</h4>';

	return $defaults;
}

Another example with all attributes and their defaults.

add_filter( 'related_posts_by_taxonomy_shortcode_defaults', 'related_shortcode_defaults' );
function related_shortcode_defaults( $defaults ) {

	$defaults['post_id']          = '';           // post ID, default empty string
	$defaults['taxonomies']       = 'all';        // Multiple: array('catecory', 'post_tag', 'genre')
	$defaults['post_types']       = '';           // Post type name. Multiple: array('post', 'movie')
	$defaults['posts_per_page']   = 5;
	$defaults['order']            = 'DESC';       // 'DESC' or 'ASC'
	$defaults['orderby']          = 'post_date';  // 'post_date' or 'post_modified'
	$defaults['before_shortcode'] = '<div class="rpbt_shortcode">'; // Text or Html
	$defaults['after_shortcode']  = '</div>';     // Text or Html
	$defaults['title']            = __( 'Related Posts', 'related-posts-by-taxonomy' );
	$defaults['before_title']     = '<h3>';       // Text or Html
	$defaults['after_title']      = '</h3>';      // Text or Html
	$defaults['exclude_terms']    = '';           // ID. Multiple: array(4,6,7)
	$defaults['include_terms']    = '';           // ID. Multiple: array(4,6,7)
	$defaults['related']          = true;         // bool true or false (since 0.4) 
	$defaults['exclude_posts']    = '';           // ID. Multiple: array(4,6,7)
	$defaults['format']           = 'links';      // 'links', 'posts', 'excerpts', 'thumbnails'
	$defaults['image_size']       = 'thumbnail';  // image size
	$defaults['columns']          = 3;
	$defaults['caption']          = 'post_title'; // 'post_title', 'post_excerpt' 'attachment_caption', attachment_alt, or a custom string
	$defaults['limit_posts']      = -1;           // -1 is no limit
	$defaults['limit_year']       = '';           // number.
	$defaults['limit_month']      = '';           // number

	return $defaults;
}

This filter is similar to the “related_posts_by_taxonomy_shortcode_defaults” filter (see above). The only difference being that the attributes set with this filter cannot be overwritten by shortcode attributes used in the post editor.

This filter allows you to display the shortcode even if no related posts were found. You can change the default message “No related posts found” with your own Templates. Use this example in your (child) theme’s functions.php file to always display the shortcode.

// this will display the shortcode even if no results where found
add_filter( 'related_posts_by_taxonomy_shortcode_hide_empty', '__return_false' );

This filter (introduced with version 0.2) lets you filter the gallery settings for the related post thumbnail display. The display (output) is the same as the WordPress gallery shortcode. The default settings are:

$defaults = array(
	'itemtag'    => 'dl', // valid html tag
	'icontag'    => 'dt', // valid html tag
	'captiontag' => 'dd', // valid html tag
	'columns'    => 3, // how many colums
	'size'       => 'thumbnail', // 'thumbnail', 'medium', 'large', 'full' and sizes set by your theme
	'caption'    => 'post_title', // 'post_title' or a custom string
);

Note: If your theme has theme support for html5 the ‘itemtag’, ‘icontag’ and ‘captiontag’ values are ‘figure’, ‘div’ and figcaption’.

Create new templates if you need different settings for the widget and shortcode. See the second method in the Template documentation.

Example
Always show two columns and the medium image size (for the widget and shortcode). Use this example in your (child) theme’s functions.php.

add_filter( 'related_posts_by_taxonomy_gallery', 'related_gallery_attributes' );
function related_gallery_attributes( $attributes ) {

	// change default columns output
	$attributes['columns'] = 2;
	
	// change default thumbnail size
	$attributes['size'] = 'medium';

	return $attributes;
}

With this filter you can change the caption text for post thumbnails.

Examples
Example of making the caption a link to the related posts. Use this example in your (child) theme’s functions.php.

add_filter( 'related_posts_by_taxonomy_caption', 'link_related_caption', 10, 2 );
function link_related_caption( $caption, $post ){
	$caption = '<a href=' . get_permalink( $post->ID ) . '>' . $caption . '</a>';
	return $caption;
}

Example of not using a caption. Use this example in your (child) theme’s functions.php.

add_filter('related_posts_by_taxonomy_caption', '__return_empty_string');

related_posts_by_taxonomy_post_thumbnail_link

This filter returns the link with the gallery image. You can use it to set up a fallback image or return an image of your choosing.

Example of setting the thumbnail size to medium on category archives

add_filter( 'related_posts_by_taxonomy_post_thumbnail_link', 'rpbt_related_post_category_image', 10, 4 );

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

	// arguments

	// $image:   The full image link
	// $attr:    array with thumbnail_id, thumbnail image, permalink, etc
	// $related: Related post object
	// $args:    Function arguments passed to km_rpbt_related_posts_by_taxonomy_gallery()

	// The related post id can be found like this
	// $post_id = $related->ID,

	// The thumbnail size can be found with this
	// $size = $args['size']

	if ( is_category() ) {
		// Category archives

		// Get the same image with the size 'medium'.
		$image = wp_get_attachment_image( $attr['thumbnail_id'], 'medium', false, $attr['describedby'] );

		// Create the link for the image
		$image = "<a href='{$attr['permalink']}' title='{$attr['title']}'>{$image}</a>";
	}

	return $image;
}

This is a WordPress filter to remove the default styling WordPress provides for galleries. To remove the styling use this in your (child) theme’s functions.php file.

Note: This removes the inline style for all galleries. (WordPress galleries also). Don’t use this if you only want to make some styling changes to the related posts gallery. See gallery styling.

// Be aware this removes the inline style for all galleries.
 
// You'll have to add your own gallery styles in your (child) theme's stylesheet.
add_filter( 'use_default_gallery_style', '__return_false' );