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

CKEDITOR.plugins.textWatcher

classsince 4.10.0
See source

API exposed by the Text Watcher plugin.

Class implementing the text watcher — a base for features like autocomplete. It fires the matched and unmatched events based on changes in the text and the position of the caret in the editor.

To check whether the text matches some criteria, the text watcher uses a callback function which should return the matching text and a CKEDITOR.dom.range for that text.

Since the text watcher works on the DOM where searching for text is pretty complicated, it is usually recommended to use the CKEDITOR.plugins.textMatch.match function.

Example:

function textTestCallback( range ) {
    // You do not want to autocomplete a non-empty selection.
    if ( !range.collapsed ) {
        return null;
    }

    // Use the text match plugin which does the tricky job of doing
    // a text search in the DOM. The matchCallback function should return
    // a matching fragment of the text.
    return CKEDITOR.plugins.textMatch.match( range, matchCallback );
}

function matchCallback( text, offset ) {
    // Get the text before the caret.
    var left = text.slice( 0, offset ),
        // Will look for an '@' character followed by word characters.
        match = left.match( /@\w*$/ );

    if ( !match ) {
        return null;
    }
    return { start: match.index, end: offset };
}

// Initialize the text watcher.
var textWatcher = new CKEDITOR.plugins.textWatcher( editor, textTestCallback );
// Start listening.
textWatcher.attach();

 // Handle text matching.
textWatcher.on( 'matched', function( evt ) {
    autocomplete.setQuery( evt.data.text );
} );

Filtering

Properties

  • readonly

    callback : Function

    See source

    The callback passed to the CKEDITOR.plugins.textWatcher constructor.

  • readonly

    editor : editor

    See source

    The editor instance which the text watcher watches.

  • readonly

    ignoreNext : Boolean

    See source

    Whether the next check should be ignored. See the consumeNext method.

    Defaults to false

  • readonly

    ignoredKeys : Number[]

    See source

    Keys that should be ignored by the check method.

    Defaults to [16, 17, 18, 91, 35, 36, 37, 38, 39, 40, 33, 34]

  • readonly

    lastMatched : String

    See source

    The last matched text.

  • readonly

    throttle : Number

    See source

    Indicates throttle threshold mitigating text checks.

    Higher levels of the throttle threshold will create a delay for text watcher checks but also improve its performance.

    See the throttle feature for more information.

    Defaults to 0

  • private

    _buffer : Object

    See source

    The throttle buffer used to mitigate text checks.

  • private

    _listeners : Array

    See source

    Listeners registered by this text watcher.

    Defaults to []

Static properties

Methods