Term Highlight

⚠️ Note: This extension is DEPRECATED as of SearchWP version 3.0 and will be removed soon ⚠️

Please see this documentation: https://searchwp.com/docs/settings/highlight/

When active, Term Highlight will automatically scrub the Title and Excerpt returned from searches and wrap search terms with a span, allowing you to highlight them in such a way that matches your site design well.

Term Highlight also includes a function allowing you to retrieve an excerpt from the post_content or from a Custom Field that contains at least one of the search terms. See usage below.

Usage

Installation for this Extension is the same as all other Extensions. Download the zip file from your Account, upload and install as you would any other WordPress plugin. Term Highlight will show up in your Plugins list in the WordPress administration area, and you can activate it.

Once activated, Term Highlight will automatically highlight terms within the Title and Excerpt for native WordPress searches. Highlights are applied by wrapping terms in <span class="searchwp-highlight" />, which you can target in your CSS.

Term Highlight will also automatically override calls to the_excerpt() by replacing that content with an excerpt that contains at least one search term from the main content (e.g. the main content field, not Custom Fields). It will also highlight terms in this content. If you would like to disable or customize this functionality, please see the filters below.

You can take it one step further by utilizing Term Highlight to generate an excerpt from a number of potential sources (including Custom Fields) by automatically filtering calls to the_excerpt() on search results pages like so:

	<?php

	function searchwp_term_highlight_auto_excerpt( $excerpt ) {
	global $post;

	if ( ! is_search() ) {
	return $excerpt;
	}

	// prevent recursion
	remove_filter( 'get_the_excerpt', 'searchwp_term_highlight_auto_excerpt' );

	$global_excerpt = searchwp_term_highlight_get_the_excerpt_global( $post->ID, null, get_search_query() );

	add_filter( 'get_the_excerpt', 'searchwp_term_highlight_auto_excerpt' );

	return wp_kses_post( $global_excerpt );
	}

	add_filter( 'get_the_excerpt', 'searchwp_term_highlight_auto_excerpt' );

view raw functions.php hosted with ❤ by GitHub

If instead you want to manually replace the calls you can use something like this:

	<?php

	/* SearchWP Term Highlight offers an alternative to the_excerpt()
	If you're looking to generate any sort of excerpt based on one of the following:
	- the actual excerpt
	- the generated excerpt from the post content
	- the post content itself
	- string-based custom field values
	this function is for you. It will try to find one of the above (in that order)
	and output something with at least one search term in it (if possible)
	*/

	// echo the excerpt (designed to be used IN PLACE OF the_excerpt
	if( function_exists( 'searchwp_term_highlight_the_excerpt_global' ) ) {
	searchwp_term_highlight_the_excerpt_global();
	}

	// return the excerpt (designed to be used IN PLACE OF get_the_excerpt
	if( function_exists( 'searchwp_term_highlight_get_the_excerpt_global' ) ) {
	$excerpt = searchwp_term_highlight_get_the_excerpt_global();
	}

view raw gistfile1.php hosted with ❤ by GitHub

Supplemental Search Engines

Term Highlight does not automatically highlight terms for Supplemental Search Engine searches! You will need to customize your template by sending your content through the highlighter before outputting it, like so:

	<?php

	// this snippet is based on SearchWP's sample Supplemental Search Engine results template found here:
	// https://searchwp.com/docs/configuration/#supplemental


	// ************************** NOTE **************************
	// this snippet is just a portion of your search results template
	// ************************** NOTE **************************

	// these are the search terms
	$query = isset( $_REQUEST['swpquery'] ) ? sanitize_text_field( $_REQUEST['swpquery'] ) : '';

	$highlighter = false;
	if( class_exists( 'SearchWP_Term_Highlight' ) ) {
	$highlighter = new SearchWP_Term_Highlight();
	}

	?>

	<?php foreach ( $posts as $post ): setup_postdata( $post ); ?>
	<div class="post">
	<h2>
	<a href="<?php echo get_permalink(); ?>">
	<?php
	// highlight the title
	$title = get_the_title();
	if( $highlighter ) {
	$title = $highlighter->apply_highlight( $title, $query );
	}
	echo wp_kses_post( $title );
	?>
	</a>
	</h2>
	<?php
	// output an excerpt
	$excerpt = get_the_excerpt();
	if( $highlighter ) {
	$excerpt = $highlighter->apply_highlight( $excerpt, $query );
	}
	echo wp_kses_post( $excerpt );
	?>
	<div class="custom-field-content">
	<?php
	// output highlighted content from a Custom Field
	$custom_field = get_post_meta( get_the_ID(), 'my_custom_field_key', true );
	if( $highlighter ) {
	$custom_field = $highlighter->apply_highlight( $custom_field, $query );
	}
	echo wp_kses_post( $custom_field );
	?>
	</div>
	</div>
	<?php endforeach; ?>

view raw gistfile1.php hosted with ❤ by GitHub

NOTE: the snippet above is meant to represent the customization you would need to do to the sample Supplemental Search Engine results template replacing the search results output ONLY, it is not an entire page template.

Filters

There are a couple of filters to note when using Term Highlight:

searchwp_th_auto_filter_excerpt
Set whether Term Highlight automatically replaces the_excerpt() with an excerpt containing search terms. Default is true, to disable:

	<?php

	add_filter( 'searchwp_th_auto_filter_excerpt', '__return_false' );

view raw gistfile1.php hosted with ❤ by GitHub

searchwp_th_num_words
Define the number of words Term Highlight will include when building an excerpt that includes at least one search term. Default is 55.

	<?php

	function my_searchwp_th_num_words() {
	// use 75 words instead of the default 55
	return 75;
	}

	add_filter( 'searchwp_th_num_words', 'my_searchwp_th_num_words' );

view raw gistfile1.php hosted with ❤ by GitHub

searchwp_th_excluded_engines
Tell Term Highlight to skip term highlighting for certain search engines. Default is none.

	<?php

	function my_searchwp_th_excluded_engines( $load_posts, $search_args ) {
	// DO NOT highlight terms when using the 'my_supplemental' search engine
	return array( 'my_supplemental' );
	}

	add_filter( 'searchwp_th_excluded_engines', 'my_searchwp_th_excluded_engines', 10, 2 );

view raw gistfile1.php hosted with ❤ by GitHub

searchwp_th_password_required_message
If a post is password protected, Term Highlight returns a custom string. Default is WordPress core default: There is no excerpt because this is a protected post..

	<?php

	function my_searchwp_th_password_required_message() {
	return __( 'This entry is private.' );
	}

	add_filter( 'searchwp_th_password_required_message', 'my_searchwp_th_password_required_message' );

view raw gistfile1.php hosted with ❤ by GitHub

Changelog

2.1.14

[Fix] Fixes an issue where highlighting was applied when no search term was provided
[Fix] Restricts global excerpt generation according to applicable meta keys only
[Improvement] Better highlighting when terms are flanked with punctuation

2.1.13

[Fix] Now finds proper highlight when only punctuation-flanked stem is found

2.1.12

[Fix] Fixed an issue with excerpts generated from multidimensional array meta values

2.1.11

[Fix] Fixed an issue with loss of capitalization/formatting when highlighting from a meta value

2.1.10

[Improvement] Improve performance of repeated calls to highlighting method per request

2.1.9

[Fix] Fixed an issue where exact phrase matches would output Array

2.1.8

[Fix] Clean up PHP Warning

2.1.7

[Fix] Fixes an issue where partial matches may result in less accurate global excerpts
[Improvement] Improved exact match processing
[Update] Updated updater

2.1.5

[Update] Highlighting no longer auto-applies for searches in the Dashboard

2.1.4

[Fix] Fixed improper variable initialization that may have resulted in an Error (props Vlad)

2.1.3

[Improvement] Better support for serialized data when building global excerpt
[Fix] Prevent global excerpt generation from defaulting to filename

2.1.2

[Fix] Fixed an issue with overly aggressive tokenizing which may have resulted in a loss of formatting
[New] New filter searchwp_term_highlight_occurrence to offset where highlighting begins (default is occurrence 1)
[Fix] Improved handling of whole match check, resolved PHP Warning
[Update] Updated updater

2.1.1

[Fix] Better handling of operations with empty search string
[Fix] Fixed PHP Warning
[Fix] Fixed an issue when finding global excerpts with multiple terms flanked by encoded punctuation

2.1.0

[Improvement] Check for whole matches before parsing individual search terms
[Improvement] Better handling of pattern matches
[Update] Updated updater

2.0.13

[New] New filter searchwp_th_auto_highlight_content to disable automatic highlighting
[Improvement] More priority given to exact search matches
[Improvement] Improved performance of highlighting operation

2.0.12

[Fix] Better highlight restriction when other SearchWP extensions are active
[Fix] Better tokenizing when extracting highlight matches

2.0.11

[Improvement] Apply appropriate filters for better interoperation with other SearchWP Extensions
[Change] More appropriate initialization timing
[Update] Updated updater

2.0.10

[Fix] PHP Warning cleanup

2.0.9

[Fix] PHP Warning cleanup

2.0.7

[Fix] Fixed an issue that forced highlights to be lowercase

2.0.6

[Improvement] Better Shortcode handling
[Improvement] Better UTF-8 support
[Improvement] Better handling of keyword stems
[Fix] Fix an issue where redundant filter calls were in place

2.0.5

[Fix] Fixed a bug that gave too much priority to manually populated Excerpts when the Excerpt did not have a highlight match but the post content did

2.0.4

[Fix] Fixed a bug that ignored a specified Custom Field from which to generate a global excerpt

2.0.3

[New] New filter searchwp_th_partial_matches which enables highlighting of partial term matches

2.0.2

[Fix] Fixed PHP Warning, better short circuit when post ID is not defined

2.0

[Improvement] Support for automatic updates based on your SearchWP license key

1.8.8

[Improvement] Better word matching at boundaries
[New] Added Shortcode handling

1.8.2

[New] Added ability to pass search query down the pipe for global excerpt generation
[New] Added searchwp_th_query filter to allow devs to override what is considered for the term

1.8

[Fix] Fixed an issue where highlighting would not take place if the class weren't instantiated properly

1.7

[Fix] Warning cleanup
[New] Allow specification of Custom Field name when globally generating an excerpt

1.6.2

[New] Added a new function to allow generation of an excerpt based on any string-based Custom Field if the default excerpt doesn't produce a match

1.6.1

[Improvement] Reduced aggressiveness matching conditional

1.6

[Improvement] Better handling of terms to highlight

1.0

- Initial release

Usage

Supplemental Search Engines

Filters

Changelog

2.1.14

2.1.13

2.1.12

2.1.11

2.1.10

2.1.9

2.1.8

2.1.7

2.1.5

2.1.4

2.1.3

2.1.2

2.1.1

2.1.0

2.0.13

2.0.12

2.0.11

2.0.10

2.0.9

2.0.7

2.0.6

2.0.5

2.0.4

2.0.3

2.0.2

2.0

1.8.8

1.8.2

1.8

1.7

1.6.2

1.6.1

1.6

1.0

Create a Better WordPress Search Experience Today