Highlighting Results
When term highlighting is enabled on the Advanced tab of the SearchWP settings screen, search terms in the title and default excerpt of results will be wrapped in a mark
tag with a class of searchwp-highlight
, like so:
<mark class="searchwp-highlight">soccer</mark>
Web browsers have a default styling for the mark
tag, but you can override these styles in any way you see fit.
Better excerpts
By default, enabling this feature will not change excerpts, but highlighting will take place when a search term is found. SearchWP can retrieve a better excerpt that contains the submitted search term and in doing so override the default excerpt with something that has the highlighted term.
This functionality takes into consideration Custom Fields and Shortcode output! It will also consider the post content itself much like native excerpt functionality if necessary.
To have SearchWP find a better excerpt on search results pages you can add the following to your theme’s functions.php
:
<?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' ); |
This snippet will modify the content returned by calls to the_excerpt()
so as to include highlights.
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(); | |
} |
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( 'SearchWPHighlighter' ) ) { | |
$highlighter = new SearchWPHighlighter(); | |
} | |
?> | |
<?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; ?> |
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.
Hooks
There are a number of hooks to customize the behavior of highlighting in SearchWP:
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' ); |
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' ); |
searchwp_minimum_word_length
Modify the minimum word length for highlights. Default is SearchWP’s minimum word length.
<?php | |
// Only highlight terms that are 5 characters or longer. | |
function searchwp_minimum_word_length( $length ) { | |
return 5; | |
} | |
add_filter( 'searchwp_minimum_word_length', 'my_searchwp_minimum_word_length' ); |
searchwp_th_use_span
Use a <span/>
instead of a <mark/>
.
<?php | |
// Tell SearchWP to use a span instead of mark when highlighting. | |
add_filter( 'searchwp_th_use_span', '__return_true' ); |
searchwp_th_query
Modify the search query prior to highlighting.
<?php | |
function searchwp_th_query( $terms ) { | |
// TODO: modify $terms in any way you'd like | |
return $terms; | |
} | |
add_filter( 'searchwp_th_query', 'my_searchwp_th_query' ); |
searchwp_th_partial_matches
Control whether SearchWP should highlight partial matches. Default is false
.
<?php | |
add_filter( 'searchwp_th_partial_matches', '__return_true' ); |
searchwp_term_highlight_break_on_first_match
Control whether SearchWP stops highlighting after the first match. Default is true
to retain overall accuracy.
<?php | |
// Prevent SearchWP from highlighting a single match. | |
add_filter( 'searchwp_term_highlight_break_on_first_match', '__return_false' ); |
searchwp_term_highlight_occurrence
Control which occurrence of the search term to highlight. Default is 1
to highlight the first occurrence.
<?php | |
// Use the second occurrence of the search term when finding what to highlight. | |
function my_searchwp_term_highlight_occurrence( $occurrence ) { | |
return 2; | |
} | |
apply_filters( 'searchwp_term_highlight_occurrence', 'my_searchwp_term_highlight_occurrence' ); |
searchwp_th_strip_shortcodes
Control whether SearchWP strips Shortcodes before highlighting. Default is true
.
<?php | |
// Prevent SearchWP from stripping Shortcodes when highlighting. | |
apply_filters( 'searchwp_th_strip_shortcodes', '__reeturn_false' ); |
searchwp_th_do_shortcode
Control whether SearchWP parses Shortcodes before highlighting. Default is true
.
<?php | |
// Prevent SearchWP from parsing Shortcodes prior to highlighting. | |
add_filter( 'searchwp_th_do_shortcode', '__return_false' ); |
searchwp_th_pre_process_content
Process the entry content before it is highlighted.
<?php | |
function my_searchwp_th_pre_process_content( $content ) { | |
// TODO: manipulate $content in any way you'd like. | |
return $content; | |
} | |
add_filter( 'searchwp_th_pre_process_content', 'my_searchwp_th_pre_process_content' ); |
searchwp_th_meta_keys
Customize which meta keys SearchWP uses when reviewing Custom Fields for better excerpts. Note that further processing will restrict applicable meta keys to those added to the engine.
<?php | |
function my_searchwp_th_meta_keys( $meta_keys ) { | |
// TODO: update $meta_keys if necessary. | |
return $meta_keys; | |
} | |
add_filter( 'searchwp_th_meta_keys', 'my_searchwp_th_meta_keys' ); |
searchwp_th_pre_process_meta_value
Process meta values before they’re sent to the highlighter.
<?php | |
function my_searchwp_th_pre_process_meta_value( $meta_value, $meta_key, $post_id ) { | |
// TODO: Customize $meta_value where applicable. | |
return $meta_value; | |
} | |
add_filter( 'searchwp_th_pre_process_meta_value', 'my_searchwp_th_pre_process_meta_value', 10, 3 ); |
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 ); |
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' ); |