Contextual Related Posts v3.0.0

I have released Contextual Related Posts v3.0.0 and is now available for download from within your WordPress admin area. This is one of the largest updates of Contextual Related Posts including a massive change to the core of the plugin.

After upgrading, I strongly suggest visiting the settings page, rechecking them and then resaving the settings. If you’re using custom code that filters the SQL query that is created by older versions of the plugin, then you will need to migrate your code in order to get this to continue working with v3.0.0.

Introducing CRP_Query

Prior to v3.0.0, Contextual Related Posts constructed its own custom query in order to pull related posts from the database. While this has worked well, it did not have the flexibility and power of WP_Query that I’ve long wanted.

This version introduces CRP_Query which brings WP_Query with all the custom features of CRP_Query. Additionally, I’ve brought back get_crp_posts() which had been previously deprecated which allows you to quickly retrieve the related posts using CRP_Query.

Existing users should not see major changes as get_crp() continues to use the same HTML code and functions but replaces get_crp_posts_id() with get_crp_posts().

For more advanced users, you can now use CRP_Query just as you would WP_Query. e.g. this gist below shows what a standard loop would look like.

This change also means that most of the filters within get_crp_posts_id() have now been deprecated as they are no longer used by the core plugin. I will deprecate this function in a future version and it will throw up a notice. Refer to the final sub-bullet of Modifications in the detailed changes section below for which filters have been deprecated.

You can now use the WP_Query filters like posts_where, posts_join, etc. to use customise the SQL query. I recommend checking for the custom parameter crp_query to makes sure that you are filtering a CRP_Query clause.

// Return if it is not a CRP_Query.
if ( true !== $query->get( 'crp_query' ) ) {
    return $where;

New related posts styles

Rounded Thumbnails has been the main inbuilt style within Contextual Related Posts. Advanced users have used custom CSS to make their related posts more beautiful. v3.0.0 adds three new styles which leverages some of the newer CSS functions like column and CSS Grid. Note that these might not work on older browsers and Internet Explorer. I’ll look to add at least another style in a future version of the plugin.


Made famous by Pinterest, this style displays the posts in the masonry layout. You can enable the author, date and excerpt if you would like to. The boxes are not of the same height which is typical of this format and will display in 3, 2 or 1 column depending on the width of the screen.


This layout uses CSS Grid which is currently supported by most major browsers. Similar to Masonry, you can enable the author, date and excerpt. This layout spreads out across the entire width of the available container.

Rounded thumbnails using CSS Grid

This has a similar look at feel as Rounded thumbnails layout but displayed using CSS Grid. This won’t allow you to display the author, date or excerpt but is more responsive than the previous style. Select this if you want a more responsive style but the look of rounded thumbnails.

Lazy loading thumbnails

The plugin will now include the loading="lazy" attribute using wp_img_tag_add_loading_attr which was introduced in WordPress 5.5.

It also uses wp_img_tag_add_srcset_and_sizes_attr to set the srcset and sizes. The previous implementation of srcset and sizes remains but I will eventually deprecate that.

Read more link

Contextual Related Posts generates its own excerpt with a custom function. You can now turn on a read more link by using the filter crp_excerpt_more_link_text to set what you would like to display. There is no option in the settings page yet and I might add this in a future version.

function change_crp_excerpt_more_link_text( $more_link_text ) {
    return "Read more";
add_filter( 'crp_excerpt_more_link_text', 'change_crp_excerpt_more_link_text' );

You can also use crp_excerpt_more_link to customise the entire link tag.

Improved caching

Contextual Related Posts has included its own caching mechanism that can significantly improve the load times of your related posts. One option is to only cache the posts and generate the HTML on-the-fly, while the second option is to cache the complete HTML – my preferred one.

This used to be perpetual and there was no way to include newer posts without clearly the entire cache. Contextual Related Posts v3.0.0 changes that by adding automatic cache expiry. By default this is one month which should long enough for most sites. If you have a very busy site, you can override this by defining CRP_CACHE_TIME in your wp-config.php to set how long the cache should be set for.

Demised Related Posts by Categories and Tags

Related Posts by Categories and Tags has been an add-on plugin that allowed the related posts to be restricted by categories and/or tags of the current posts. With v3.0.0, all the features of this plugin have been imported and the add-on plugin is no longer needed.

In the last release, I added the functionality for the plugin to detect if Contextual Related Posts v3.0.0 was installed and if so, the plugin will try to migrate the settings to Contextual Related Posts. Please visit your settings page if you are an existing user to verify that this has been migrated correctly.

Detailed changes in v3


Release post:

  • Bug fix:
    • Replicate old style of exclusion checking of option set in meta. Using the shortcode, manual or block will ignore the meta option to “Disable Related Posts display”


  • Enhancement:
    • Defining CRP_CACHE_TIME to false will disable expiry
    • Introduced wpml-config.xml file. Title and Custom text for blank output can now be translated with Polylang (and potentially WPML)
  • Bug fix:
    • Exclude on categories did not work
    • Posts would trigger a “SHOW FULL COLUMNS FROM” error if they had ‘ from’ in the title
    • Manual posts did not work properly – all post types and all posts are properly fetched now


  • Bug fix:
    • Certain posts would trigger a “SHOW FULL COLUMNS FROM” error
    • Forced .crp_related figure margin to 0


  • Enhancement/Modifications:
    • include_cat_ids and exclude_categories will also accept custom taxonomy term_taxonomy_ids
    • Thumbnail’s img tag is wrapped in <figure>
    • Remove extra checking for exclude_categories in get_crp
    • Optimise deleting of cache entries when updating a post – post saving should be significantly faster


  • Enhancement/Modifications:
    • Grid style minimum width is now decided by the width of the thumbnail and long words are wrapped
  • Bug fixes:
    • Selecting No style created a 404 error
    • Fixed issue with $attachment_id not being declared in some cases


  • Bug fixes:
    • Fixed issue where Related Posts newer than was set to 0 caused no posts to display
    • Use the original arguments when setting the cache key for CRP_Query
    • Selecting “Blank Output” didn’t work


  • Bug fixes:
    • Fixed issue with help tab that broke some sites


  • Features:
    • New CRP_Query class for fetching related posts. This replaces get_crp_posts_id() which will be deprecated in a future version
    • CRP Thumbnails now include the loading="lazy" attribute added in WordPress 5.5
    • New parameter more_link_text that can be passed to get_crp() which holds the “read more”. Recommended option to customize the more link text using the filter crp_excerpt_more_link_text or the more link element using crp_excerpt_more_link
    • Three new styles: “Masonry” (like Pinterest), “Grid” and “Rounded thumbnails with CSS grid”. Might not work with older browsers
    • Imported settings of Related Posts by Categories and Tags. That plugin is now deprecated with this release.
  • Enhancement/Modifications:
    • If WPML or PolyLang are active, get_crp_posts_id() and CRP_Query will return the translated set of post IDs and external processing is no longer needed
    • Use wp_img_tag_add_srcset_and_sizes_attr() to generate srcset and sizes attributes. The original code to display the srcset and sizes attributes will continue to be used
    • Improved caching with inbuilt expiry. Use CRP_CACHE_TIME in your wp-config.php to set how long the transients should be set for. Default is one month
    • CRP_MAX_WORDS has been reduced to 100
    • Dropped the need for FULLTEXT index on post_content which should save some database space
    • Deprecated the following filters: get_crp_posts_id, crp_posts_now_date, crp_posts_from_date, crp_posts_fields, crp_posts_join, crp_posts_where, crp_posts_groupby, crp_posts_having, crp_posts_orderby, crp_posts_limits, get_crp_posts_id_short_circuit
  • Bug fixes:
    • In the settings page, only built-in taxonomies were being incorrectly displayed
    • If “before list item” is empty, then the output was blanked out
    • Settings help has been fixed

Download Contextual Related Posts

Leave a Reply

Your email address will not be published. Required fields are marked *