Related

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:

Screen Shot 2017-04-14 at 10.10.33 AM - SearchWP — 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 */<code></code>

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();

view raw single.php hosted with ❤ by GitHub

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 );

view raw functions.php hosted with ❤ by GitHub

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?
	);

view raw functions.php hosted with ❤ by GitHub

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:

searchwp-related - SearchWP — 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' ];
	} );

view raw functions.php hosted with ❤ by GitHub

Setup & Integration

Customizing output: the template loader

Template Options

Programmatically retrieve Related content

Customizing input: defining Related content

Create a Better WordPress Search Experience Today