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 Extensions dropdown on 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:
In the Related plugin folder there is another folder named templates containing this default Related template (
related.php) used to display Related content.
The contents of this file are as follows:
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:
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.
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:
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:
|// This should be within your single.php or other applicable template that has the $post defined|
|$related = new SearchWP_Related\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:
|* Programmatically find Related content from SearchWP Related|
|$args = array(|
|'s' => 'coffee', // keywords (space separated) to use when finding Related content|
|'engine' => 'default', // the SearchWP engine to use|
|'posts_per_page' => 3, // how many entries to find|
|// Instantiate SearchWP Related|
|$searchwp_related = new SearchWP_Related();|
|// 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:
|$defaults = array(|
|'engine' => 'default', // Engine to use|
|'s' => '', // 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:
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.
- [Fix] Prevent PHP(<5.5) Fatal error
Can't use function return value in write context
- Initial release