# CKEDITOR.plugins.textMatch

class singleton since 4.10.0

A global namespace for methods exposed by the Text Match plugin.

The most important function is match which performs a text search in the DOM.

## Methods

• ### getAdjacentTextNodes( range ) → text[]CKEDITOR.plugins.textMatch#getAdjacentTextNodes

Creates a collection of adjacent text nodes which are between DOM elements, starting from the given range. This function works only for collapsed ranges.

##### Examples
• {} is the range position in the text node (it means that the text node is not split at that position).
• . is a separator for text nodes (it means that the text node is split at that position).

Examples:

Input: <p>he.llo{}</p>
Result: [ 'he', 'llo' ]

Input: <p>{}he.ll<i>o</i></p>
Result:  [ 'he', 'll' ]

Input: <p>he{}<i>ll</i>o.</p>
Result:  [ 'he' ]

Input: <p>he<i>ll</i>{}o.my.friend</p>
Result: [ 'o', 'my', 'friend' ]


#### Parameters

range : range

#### Returns

text[]

An array of text nodes.

• ### getRangeInText( range, start, end ) → rangeCKEDITOR.plugins.textMatch#getRangeInText

Transforms the start and end offsets in the text generated by the getTextAndOffset method into a DOM range.

##### Examples
• {} is the range position in the text node (it means that the text node is not split at that position).
• . is a separator for text nodes (it means that the text node is split at that position).

Examples:

Input: <p>f{}oo.bar</p>, 0, 3
Result: <p>{foo}.bar</p>

Input: <p>f{}oo.bar</p>, 1, 5
Result: <p>f{oo.ba}r</p>


#### Parameters

range : range
start : Number

A start offset.

end : Number

An end offset.

#### Returns

range

Transformed range.

• ### getTextAndOffset( range ) → Object | nullCKEDITOR.plugins.textMatch#getTextAndOffset

Returns a text (as a string) in which the DOM range is located (the function scans for adjacent text nodes) and the offset of the caret in that text.

##### Examples
• {} is the range position in the text node (it means that the text node is not split at that position).
• [] is the range position in the element (it means that the text node is split at that position).
• . is a separator for text nodes (it means that the text node is split at that position).

Examples:

Input: <p>he[]llo</p>
Result: { text: 'hello', offset: 2 }

Input: <p>he.llo{}</p>
Result: { text: 'hello', offset: 5 }

Input: <p>{}he.ll<i>o</i></p>
Result: { text: 'hell', offset: 0 }

Input: <p>he{}<i>ll</i>o</p>
Result: { text: 'he', offset: 2 }

Input: <p>he<i>ll</i>o.m{}y.friend</p>
Result: { text: 'omyfriend', offset: 2 }


#### Parameters

range : range

#### Returns

Object | null
Properties
text : String

The text in which the DOM range is located.

offset : Number

An offset of the caret.

• ### match( range, testCallback ) → Object | nullCKEDITOR.plugins.textMatch#match

Allows to search in the DOM for matching text using a callback which operates on strings instead of text nodes. Returns CKEDITOR.dom.range and the matching text.

var range = editor.getSelection().getRanges()[ 0 ];

CKEDITOR.plugins.textMatch.match( range, function( text, offset ) {
// Let's assume that text is 'Special thanks to #jo.' and offset is 21.
// The offset "21" means that the caret is between '#jo' and '.'.

// Get the text before the caret.
var left = text.slice( 0, offset ),
// Will look for a literal '#' character and at least two word characters.
match = left.match( /#\w{2,}\$/ );

if ( !match ) {
return null;
}

// The matching fragment is the '#jo', which can
// be identified by the following offsets: { start: 18, end: 21 }.
return { start: match.index, end: offset };
} );


#### Parameters

range : range

A collapsed range — the position from which the scanning starts. Usually the caret position.

testCallback : Function

A callback executed to check if the text matches.

Properties
text : String

The full text to check.

rangeOffset : Number

An offset of the range in the text to be checked.

[ return ] : Object

The position of the matching fragment (null if nothing matches).

Properties
start : Number

The offset of the start of the matching fragment.

end : Number

The offset of the end of the matching fragment.

#### Returns

Object | null

An object with information about the matching text or null.

Properties
text : String

The matching text. The text does not reflect the range offsets. The range could contain additional, browser-related characters like CKEDITOR.dom.selection.FILLING_CHAR_SEQUENCE.

range : range

A range in the DOM for the text that matches.