Use SearchWP to power related content on your site! SearchWP Related was built to work with minimal overhead, while allowing for customization to any degree. Showing related content to visitors is a great way to keep attention on your site! If you’re already using another system for related content, this SearchWP extension will likely save you some overhead by utilizing the content index it already created.
Setup & Integration
Like all SearchWP Extensions, Related is a standalone WordPress plugin that runs alongside SearchWP. Once installed, Related takes no action by default. You can view the settings screen (found within the SearchWP settings screen)
Note: When activating Related on a site with existing content, entry titles will be used as the default keyword list to find related content.
On this screen you can:
- Enable auto-appending of Related content per post type
- Exclude content (comma separated IDs) from Related content per post type
- Limit potential Related content (comma separated IDs) per post type
When auto-append is enabled for a post type, Related content will be automatically output when viewing a single entry of that post type.
Customizing output: the template loader
As is the case with Live Search, Related also uses a template loader to allow for full customization of Related results. There is a default template that looks something like this:
The default Related template will match your theme font and colors (to an extent)
In the Related plugin folder there is another folder named templates containing this default Related template (related.php) used to display Related content.
~/wp-content/plugins/searchwp-related/templates/related.php
The contents of this file are as follows: related.php
Do not edit this file directly. If you install an update to Related, any customizations you make to this file will be overwritten!
Instead, you can utilize the template loader built into Related to add your own custom template within your theme.
To customize the output of Related content, create a new folder within your theme and paste a copy of the default Related template into that folder, keeping the same filename:
~/wp-content/themes/my-theme/searchwp-related/related.php
You can fully customize this template to meet your needs. It’s based on The Loop, and you can do anything within the template you would in any other theme template.
Template Options
While the template used to show Related content is mostly a standard theme template, you can influence how Related behaves by editing the optional comment block at the top of the file:
/**
* SearchWP Engine: default
* Maximum Results: 3
*/
You can customize the SearchWP engine used, and the maximum number of Related entries displayed by editing the applicable line at the top of the template.
You can also customize results templates per post type by appending a hyphen and the post type to the file name. For example, if you were to create a template with this filename:
~/wp-content/themes/my-theme/searchwp-related/related-page.php
It would be used only for Pages. All other post types would use the base template.
Programmatically retrieve Related content
If you want to use the template loader but in a different spot than the auto-append checkbox uses, leave that checkbox unticked and edit your template file to include the following where you want Related output:
| <?php | |
| // This should be within your single.php or other applicable template that has the $post defined | |
| $related = new SearchWP_Related\Template(); | |
| echo $related->get_template(); |
You can also skip the template loader entirely and instead retrieve Related content directly in your theme code. Here’s how you can do that:
| <?php | |
| /* | |
| * Programmatically find Related content from SearchWP Related | |
| */ | |
| // Instantiate SearchWP Related | |
| $searchwp_related = new SearchWP_Related(); | |
| // Use the keywords as defined in the SearchWP Related meta box | |
| $keywords = get_post_meta( get_the_ID(), $searchwp_related->meta_key, true ); | |
| $args = array( | |
| 's' => $keywords, // The stored keywords to use | |
| 'engine' => 'default', // the SearchWP engine to use | |
| 'posts_per_page' => 3, // how many entries to find | |
| ); | |
| // Retrieve Related content for the current post | |
| $related_content = $searchwp_related->get( $args ); | |
| // Returns an array of Post objects for you to loop through | |
| print_r( $related_content ); |
There are a number of arguments you can pass to customize how Related will find related content, here’s a full breakdown of the possible arguments:
| <?php | |
| // Use the saved keywords from the meta box | |
| $keywords = get_post_meta( get_the_ID(), $searchwp_related->meta_key, true ); | |
| $defaults = array( | |
| 'engine' => 'default', // Engine to use | |
| 's' => $keywords, // Terms to search | |
| 'fields' => 'all', // Return post objects, use 'ids' to return IDs | |
| 'posts_per_page' => 3, // How many results to return | |
| 'log' => false, // Log the search? | |
| 'post__in' => array(), // Limit results pool? | |
| 'post__not_in' => array() // Exclude posts from results? | |
| ); |
It’s suggested that you set up some sort of caching (e.g. via Transient) to reduce resource usage.
Customizing input: defining Related content
Related by default will build a keyword list from the title of your entries. Common words are removed so as to increase relevancy of Related results. On every entry edit screen, Related will output a meta box allowing you to customize what keyword(s) are used to determine Related content:
Real time results samples when customizing keyword(s)
A set of three sample results are displayed, allowing you to customize the keyword(s) you’re using if you’d like. This is just a sample, the template loader controls how the results are displayed on the front end, and SearchWP determines which entries to display at runtime.
The Results samples will include all the available engines. If you want to limit the samples displayed to only some engines you can use this filter:
| <?php | |
| // Define the engines to use for the metabox samples. | |
| add_filter( 'searchwp_related_meta_box_sample_engines', function( $engines ) { | |
| return [ 'default', 'products' ]; | |
| } ); |
Changelog
1.5.3
- [New] Added
searchwp_related_meta_box_sample_engineshook to filter the engines displayed in the metabox samples. - [Change] Sample results are now responsive.
1.5.2
- [Fix] JavaScript error if SearchWP "Hide Announcement" option is enabled.
1.5.1
- [Change] Added "Tested up to" tag to indicate the latest WP version compatibility
- [Change] Removed build files to avoid triggering automations on some systems
- [Fix] PHP error when SearchWP plugin is not active
1.5.0
- [New] The settings area is revamped providing more control over the content and visual appearance of the Related block
- [New] New Gutenberg block and Shortcode are added for manual embedding
- [Change] Minimal required SearchWP version for the Related extension is 4.2.6
- [Change] Removed redundant/unused functions and methods
1.4.8
- [Fix] Error in PHP versions prior to 7.3 caused by a function call trailing comma
- [Fix] List of suggestions is not re-rendered on Keywords field change in the post metabox
- [Fix] Deprecation notices on PHP 8.2
1.4.7
- [Fix] Parse error for PHP 7.2 and lower
- [Fix] Compatibility with SearchWP 4.2.0 and above
1.4.6
- [New] Context array added to
searchwp_related_default_keywords - [Fix] PHP Notice
- [Fix] Excluded posts in preview in some cases
1.4.5
- [Fix] Initial preview render
1.4.4
- [Fix] PHP Notice, Error in some cases
- [Update] Updated updater
1.4.3
- [Fix] Prevent logging in SearchWP Metrics when applicable
1.4.2
- [Fix] Fixes Error when using SearchWP 4
1.4.0
- [New] Adds support for SearchWP 4
1.3
- [New] Force specific Related entries for each entry
- [New] Related content is now cached for 12 hours
- [New] Hook to control query cache TTL in seconds
searchwp_related_cache_length - [New] Hook to control whether caching is used
searchwp_related_cache_enabled - [Fix] Auto-append not working in some cases
- [Fix] Pagination not respected in some cases
- [Fix] Default keywords not populated in some cases
- [Fix] Links to documentation
- [Change] Meta box no longer appears on non-public post types by default
- [Change] Additional results found if initial results set is too restricted by SearchWP
- [Update] Translation source
- [Update] Updated updater
1.1.1
- [Change] Fallback keyword set is now defined when Drafts are saved (was previously on Publish)
1.1
- [New] Adds Widget
- [New] New hooks to control meta box placement
searchwp_related_meta_box_contextandsearchwp_related_meta_box_priority
1.0.4
- [Fix] Fixed an issue with overzealous enqueues
1.0.3
- [Fix] Fixed an issue where Related entries were not found in certain circumstances
- [Update] Updated updater
1.0.2
- [Fix] Newly published entries are no longer automatically skipped if no keywords are entered, will use fallbacks by default
- [Fix] Implementation of
searchwp_related_excluded_post_typesfilter is now applied correctly and works
1.0.1
- [Fix] Prevent PHP(<5.5) Fatal error
Can't use function return value in write context
1.0.0
- Initial release
