CKEditor Ecosystem Documentation
Search
Report an issue
Home/CKEditor 4/API
Class

CKEDITOR.plugins.textMatch

class singleton since 4.10.0
See source

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.

Filtering

Methods

  • getAdjacentTextNodes( range ) → text[]

    See source

    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 ) → range

    See source

    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 | null

    See source

    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 | null

    See source

    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.

    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.