Install YARPP from within WordPress
- Visit the plugins page within your WordPress dashboard and select
Add New
- Search for
YARPP
- Press “Install Now” for the
YARPP plugin
- Activate YARPP from your Plugins page
- Go to the “YARPP” settings page to customize YARPP
- [optional] copy the sample YARPP Custom Template files inside the
yarpp-templates folder into your active theme folder.
Install YARPP Manually
- Upload the
yet-another-related-posts-plugin folder to the /wp-content/plugins/ directory
- Activate YARPP from your Plugins page
- Go to the “YARPP” settings page to customize YARPP
- [optional] copy the sample YARPP Custom Template files inside the
yarpp-templates folder into your active theme folder.
Install YARPP with the WP-CLI
wp plugin install yet-another-related-posts-plugin --activate- Go to the “YARPP” settings page to customize YARPP
- [optional] copy the sample YARPP Custom Template files inside the
yarpp-templates folder into your active theme folder.
The YARPP custom template feature allows you to easily customize look and feel using the same coding conventions and Template Tags as in WordPress themes.
Your YARPP Custom Template file must be in the active theme’s main directory in order to be recognized by YARPP. If your theme did not ship with a YARPP templates, move the files in the yarpp-templates directory which ships with YARPP into your active theme’s main directory. Be sure to move the files (which must be named yarpp-template-….php) to your theme, not the entire directory. There is no limit restriction on custom templates.
After Activation
You should customize your Pool, Algorithm and Automatic Display Options settings from the YARPP settings page. YARPP supports a full range of placement options, including Automatic Display Options (pick where to show YARPP from the YARPP settings page), Block, Shortcode, Widget, YARPP functions() and REST API support. Details below.
Automatic Display Options
Configurable from the YARPP settings page, the Automatic Display Option automatically displays YARPP right below post content. You can configure which posts types to display YARPP on from the YARPP settings page.
If you do not want to show the Related Posts display in its default position (right below the post content), first go to YARPP options and turn off the “Automatic Display Options”.
If you would like to instead display it in your sidebar and you have a widget-aware theme, YARPP provides a Related Posts widget which you can add under “Appearance” > “Widgets.”
If you would like to add Related Posts elsewhere (such as inline related posts), edit your relevant theme file (most likely something like single.php) and add the shortcode code [yarpp] or PHP function yarpp_related(); within The Loop where you want to display the related posts. Make sure you don’t add echo yarpp_related(); or you may end up with duplicates in your related posts section. The YARPP Block is also an option.
Automatic Display in Feed Options
Make sure the “display related posts in feeds” option is turned on if you would like to show related posts in your RSS and Atom feeds. The “display related posts in feeds” option can be used regardless of whether you auto display them on your website (and vice versa).
Block
YARPP ships with full support for Gutenberg Blocks. You can place YARPP’s Block manually wherever you’d like in post content.
Shortcode
You can place YARPP’s related posts manually wherever you’d like in post content or theme files.
To add to post content, use the shortcode:
[yarpp] to show content related to the current post. You may use more than one YARPP shortcode in a given post or template.
All the parameters accepted by yarpp_related() (see below) can also be used in the shortcode. Here are some examples…
If you know the reference Post ID that you want to show content related to, use:
[yarpp reference_id=123] to show content related to post 123
To specify which YARPP template to use, use the “template” attribute like so:
[yarpp template="yarpp-template-photoblog"] - where `yarpp-template-photoblog.php` is the file name of the custom template
[yarpp template="list"] - built-in "List" template
[yarpp template="thumbnails"] - built-in "Thumbnails" template
To specify maximum number of posts to show, use the “limit” attribute like so:
[yarpp template="list" limit=3]
To only show recent posts, use the “recent” attribute (provide it with a number, a space, and then either “day”, “week” or “month”)
[yarpp recent="6 month"]
To show another post type, use the “post_type” parameter.
[yarpp post_type="page"]
If you need to provide multiple values (eg posts and pages, or a list of categorires of posts to exlude), separate them with a comma but no space.
[yarpp post_type="post,page"] - include both posts and pages in results
[yarpp exclude="1,2,3"] - exclude posts with categories with IDs 1,2 and 3
To adjust the weights and taxonomy requirements, provide the value as JSON (using the same structure as for yarpp_related() below). Eg
[yarpp weight='{"body":1}'] - only consider body content
[yarpp weight='{"body":2,"title":2,"tax":{"category":0, "post_tag":0}}'] - give extra weight to bodies and titles, but none to categories
[yarpp require_tax='{"category": 2, "post_tag": 0}'] - require at least one category in common
To order results:
[yarpp order="score DESC"] - high relevance score to low
[yarpp order="rand"] - random
To add YARPP shortcode to your theme files (eg. single.php), use:
<?php echo do_shortcode('[yarpp]'); ?>
<?php echo do_shortcode('[yarpp reference_id=123]'); ?>
If you’re adding the shortcode outside the loop, you must provide the reference_id.
Widget
Related posts can also be displayed as a widget. Go to the Appearance > Widgets options page and add the “Related Posts (YARPP)” widget. Choose to display content from YARPP Basic. The widget will only be displayed on single entry (permalink) pages.
The YARPP widget can be used even if the “auto display” option is turned off.
REST API
Add related posts to your JavaScript driven app!
YARPP adds a REST API endpoint for fetching related posts. The JSON results from the REST API query are the same as you would see if you were visiting a post on your website (the same quantity and order). It is possible to override the quantity at the time of making the REST API request.
[Documentation]
YARPP functions()
Developers can call YARPP’s powerful relatedness algorithm from anywhere in their own code. Some examples and more details are in this WordCamp Birmingham talk.
You may use the functions defined in includes/related_functions.php in your own code, notably:
yarpp_related() – gets the HTML for related posts and displays ityarpp_related_exist() – checks whether any related posts existsyarpp_get_related() – returns the list of related posts (WP_Post objects)
Examples:
Show related posts, using all the settings set on the YARPP settings page:
<?php yarpp_related(); ?>
Each of these functions will default to using the settings set on the YARPP settings page, but can be customized. For example:
yarpp_related(
array(
// Pool options: these determine the "pool" of entities which are considered
'post_type' => array('post', 'page', 'wc_product', ...), // post types to include in results
'show_pass_post' => true, // show password-protected posts
'show_sticky_posts' => true, // show sticky posts
'past_only' => true, // show only posts which were published before the reference post
'exclude' => array(), // a list of term_taxonomy_ids. entities with any of these terms will be excluded from consideration.
'recent' => false, // to limit to entries published recently, set to like '15 day', '20 week', or '12 month' (https://www.mysqltutorial.org/mysql-interval/)
// Relatedness algorithm options: these determine how "relatedness" is computed
// Weights are used to construct the "match score" between candidates and the reference post
'weight' => array(
'body' => 1,
'title' => 2, // larger weights mean this criteria will be weighted more heavily
'tax' => array(
'post_tag' => 1,
... // put any taxonomies you want to consider here with their weights
)
),
// Specify taxonomies and a number here to require that a certain number be shared:
'require_tax' => array(
'post_tag' => 1 // for example, this requires all results to have at least one 'post_tag' in common
),
// The threshold which must be met by the "match score" to be considered related
'threshold' => 5,
// Display options:
'template' => 'thumbnails', // which theme/custom template to use. Built-in ones include "list" and "thumbnails", or the name of a YARPP template file in your active theme folder starting with "yarpp-template-". Example: yarpp-template-videos or yarpp-template-videos.php
'limit' => 5, // maximum number of results
'order' => 'score DESC', // column on "wp_posts" to order by, then a space, and whether to order in ascending ("ASC") or descending ("DESC") order
'promote_yarpp' => true, // boolean indicating whether to add 'Powered by YARPP' below related posts
'generate_missing_thumbnails' => true, // automatically generate missing thumbnail sizes on the fly
'extra_css_class' => 'class_1 class_2', // add CSS classes to YARPP's parent div
),
$reference_ID, // second argument: (optional) the post ID. If not included, will use the current post.
true // third argument: (optional) true to echo the HTML block; false to return it
);
Options which are not specified will default to those specified on the YARPP settings page. Additionally, if you are using a builtin template rather than specifying a custom template file in template, the following arguments can be used to override the various parts of the builtin template: before_title, after_title, before_post, after_post, before_related, after_related, no_results, excerpt_length.
If you need to implement related entries programmatically or to know whether they exist, you can use the functions:
yarpp_get_related( $args, $reference_ID )
Returns an array of post objects, just like the WordPress function get_posts.yarpp_related_exist( $args, $reference_ID )
Returns a boolean for whether any such related entries exist.
For each of these functions, $args takes the same arguments as those detailed for yarpp_related() above, except for the various display and template options.
Note that at this time custom YARPP queries using the functions mentioned here are not cached in the built-in YARPP caching system. Thus, if you notice any performance hits, you may need to write your own code to cache the results.
Example of how to use a custom YARPP query and cache the results for a day:
$result = get_transient('yarpp_custom_results_for_' . $post->ID);
if(! $result){
$result = yarpp_related(['post_type' => 'reply'],null,false);
set_transient('yarpp_custom_results_for_' . $post->ID, $result, DAY_IN_SECONDS);
}
echo $result;
Show at most 4 related WooCommerce products based on their title and especially on their categories, assuming custom YARPP template
yarpp-related-wc-products.php has been added to the active theme folder:
yarpp_related(
array(
'limit' => 4,
'weight' => array(
'title' => 1,
'tax' => array(
'category' => 2
)
),
'post_type' => 'wc_product',
'template' => 'yarpp-related-wc-products.php'
)
);
Check for posts related to post with ID 123, and loop through them in order to do some more custom logic:
$related_posts = yarpp_get_related(array(), 123);
if(! $related_posts){
echo 'No related posts';
} else {
foreach($related_posts as $post){
// $post is a WP_Post object.
echo $post->post_title;
}
}
Show results ordered by score (high relevance to low):
yarpp_related(
array(
'order' => 'score DESC',
)
);
Show results ordered by post publish date (new to old):
yarpp_related(
array(
'order' => 'post_date DESC',
)
);
Show results ordered randomly:
yarpp_related(
array(
'order' => 'rand',
)
);
YARPP Filters
Documentation: https://support.shareaholic.com/hc/en-us/articles/4408775687060
