relevanssi_highlight_terms()

relevanssi_highlight_terms( string $content, string $query, boolean $convert_entities = false )

Adds highlighting to a string based on a search query.

Source: /lib/excerpts-highlights.php

Parameters

$content
(string) (required) A string where the terms should be highlighted.

$query
(string|array) (required) The search query in string format. Can be a single string, or an array of strings.

$convert_entities
(boolean) (optional) If true, the highlighting happens in post content context. If false, assume this is an excerpt. This affects the way entities are handled (see below).
Default: false

Returns

(string) The content with the highlights applied.

Usage

Takes a string of content and a string of search terms and applies highlighting to the content for the search terms, based on Relevanssi highlighting settings. Following settings affect the highlighting:

  • relevanssi_highlight – The type of highlighting used. The options are:
    • mark for <mark> tags
    • strong for <strong> tags
    • em for <em> tags
    • col for text color using a <span>
    • bgcol for background color using a <span>
    • css for setting specific CSS styles to a <span>
    • class for setting a class to a <span>
    • none for doing nothing
  • relevanssi_txt_col – The text color for the col setting.
  • relevanssi_bg_col – The text color for the bgcol setting.
  • relevanssi_css – The styles for the css setting.
  • relevanssi_class – The class name for the class setting.
  • relevanssi_fuzzy – The highlighting method depends on whether words are partially matched or not. If whole word matching is used, only whole word matches are accepted in highlights.
  • relevanssi_expand_highlights – If this option is enabled, partial-word highlighting matches are expanded to cover the whole word. This is particularly useful when stemming is used.
  • relevanssi_excerpt_allowable_tags – Determines which HTML tags are kept in the content; this affects the way the entities are managed.

This function can be used to add Relevanssi highlighting to any content. For example if your search results page uses the_tags() to display the tags and you want the tags highlighted, you can use this instead of the_tags():

echo relevanssi_highlight_terms( get_the_tag_list( '', ', ' ), get_search_query(), true );

(This is not a very good example, as you could simply use relevanssi_the_tags(), which is an easier way to do the same thing.)

The $in_docs parameter

The way the $in_docs parameter affects this is about the entities. In excerpt context, the content is passed through htmlentities() and the allowed tags are then converted back into actual tags. In full post content, running htmlentities() is likely a disaster, so if the $in_docs flag is set, it is not done.

Set the flag to true if your content has HTML tags you wish to keep intact.

When doing complete posts, it’s generally a good idea to run htmlentities() for content inside <pre> and <code> tags. However, if the content has HTML code inside <pre> or <code> tags, this is again trouble, so for those cases, Relevanssi has filter hooks for disabling this behaviour. You can set relevanssi_entities_inside_pre and relevanssi_entities_inside_code to false to avoid this.

Filter hooks

relevanssi_highlight_tokenize
An action hook that is run before the search terms are tokenized in highlighting.

relevanssi_allow_one_letter_highlights ( boolean : false )
If false, one-letter highlights are not allowed. Set to true if you want single letters to be highlighted.

relevanssi_clean_excerpt ( string $content, string $start_emp_token, string $end_emp_token )
Filters the content before the tokens that mark the highlighting spots are converted into actual tags depending on the options. The extra parameters contain the tokens used, so you can know what kind of tokens are used. You can remove, move or add highlights by manipulating the tokens in the content.