SearchWP

This Documentation is for SearchWP Version 3

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' );
view raw functions.php hosted with ❤ by GitHub

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();
}
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( '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; ?>
view raw functions.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.

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' );
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_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' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

searchwp_th_partial_matches
Control whether SearchWP should highlight partial matches. Default is false.

<?php
add_filter( 'searchwp_th_partial_matches', '__return_true' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

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' );
view raw functions.php hosted with ❤ by GitHub

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 );
view raw functions.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