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

Create a Better WordPress Search Experience Today

Never lose visitors to unhelpful search results again. SearchWP makes creating your own smart WordPress search fast and easy.

Get SearchWP Now