# Text highlighting

Questions or comments?

## Purpose

The Text highlighting component highlights any text within a pre-defined area that matches case-insensitive search criteria specified through the URL's query string. Supports multi-word strings, including spaces and basic punctuation.

Note: Search criteria using special regex characters such as `"`, `|`, `?`, `+`, `(` or `)` may be partially or fully excluded from the results.

## Use when

- Highlighting search terms on a search results page
- Highlighting key words on a Web page
- Helping the user to find all instances of one or more words on a Web page

## Working example

### Sample search criteria

- avian influenza
- world
- cook
- flu-like symptoms
- Don't Forget...
- causes sickness in birds, it can also infect people.

Query string: `?txthl=avian%20influenza+world+cook+flu-like%20symptoms+Don't%20Forget...+causes%20sickness%20in%20birds,%20it%20can%20also%20infect%20people.`

Highlight example text that meets the search criteria

## How to implement

1. Define your search area. Add the `wb-txthl` class to the tag whose contents you want to search in.
2. Specify the search criteria in a URL query string. Add `txthl=<text_1>+<text_2>+<text_3>` to the query string.
   Note: HTML markup validation requires all spaces in links to be replaced by `%20`.

Note: HTML markup validation requires all spaces in links to be replaced by `%20`.

## Configuration options

Option | Description | How to configure | Values
--- | --- | --- | ---
`txthl` | Query string parameter that specifies the search criteria for the text to highlight. | Add `txthl=<text_1>+<text_2>+<text_3>` to the query string. Note: HTML markup validation requires all spaces in links to be replaced by `%20`. | Strings separated by + characters.

## Events

Document the public events that can be used by implementers or developers.

Event | Trigger | What it does
--- | --- | ---
`wb-init.wb-txthl` | Triggered manually (e.g., `$( ".wb-txthl" ).trigger( "wb-init.wb-txthl" );`). | Used to manually enhance an element with the Text highlighting plugin. Note: The Text highlighting plugin will be initialized automatically unless the element is added after the page has already loaded.
`wb-ready.wb-txthl` (v4.0.5+) | Triggered automatically after the Text highlight plugin initializes. | Used to identify where the Text highlight plugin was initialized (target of the event).
    $( document ).on( "wb-ready.wb-txthl", ".wb-txthl", function( event ) {
    });
    $( ".wb-txthl" ).on( "wb-ready.wb-txthl", function( event ) {
    });
`wb-ready.wb` (v4.0.5+) | Triggered automatically when WET has finished loading and executing. | Used to identify when all WET plugins and polyfills have finished loading and executing.
    $( document ).on( "wb-ready.wb", function( event ) {
    });

## Source code

Text highlighting source code on GitHub

Date modified:
  2014-08-04