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

CKEDITOR.plugins.autocomplete

class since 4.10.0
See source

The main class implementing a generic Autocomplete feature in the editor. It acts as a controller that works with the model and view classes.

It is possible to maintain multiple autocomplete instances for a single editor at a time. In order to create an autocomplete instance use its constructor.

Filtering

Properties

  • readonly

    commitKeystrokes : Number[]

    See source

    The autocomplete keystrokes used to finish autocompletion with the selected view item. The property is using the CKEDITOR.config.autocomplete_commitKeystrokes configuration option as default keystrokes. You can change this property to set individual keystrokes for the plugin instance.

  • readonly

    editor : editor

    See source

    The editor instance that autocomplete is attached to.

  • since 4.20.0 readonly

    followingSpace : Boolean

    See source

    Indicates if a following space should be added after inserted match into an editor.

  • readonly

    model : model

    See source

    The autocomplete model instance.

  • readonly

    outputTemplate : template

    See source

    Template of markup to be inserted as the autocomplete item gets committed.

    You can use item properties to customize the template.

    var outputTemplate = `<a href="/tracker/{ticket}">#{ticket} ({name})</a>`;

    Defaults to null

  • readonly

    textWatcher : textWatcher

    See source

    The autocomplete text watcher instance.

  • throttle : Number

    See source

    Indicates throttle threshold expressed in milliseconds, reducing text checks frequency.

    Defaults to 20

  • readonly

    view : view

    See source

    The autocomplete view instance.

  • private

    _listeners : Array

    See source

    Listeners registered by this autocomplete instance.

    Defaults to []

Methods

  • constructor( editor, config ) → autocomplete

    See source

    Creates a new instance of autocomplete and attaches it to the editor.

    In order to initialize the autocomplete feature it is enough to instantiate this class with two required callbacks:

    Creating an autocomplete instance

    Depending on your use case, put this code in the CKEDITOR.pluginDefinition.init callback of your plugin or, for example, in the CKEDITOR.editor.instanceReady event listener. Ensure that you loaded the Text Match plugin.

    var itemsArray = [ { id: 1, name: '@Andrew' }, { id: 2, name: '@Kate' } ];

// Called when the user types in the editor or moves the caret.
// The range represents the caret position.
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 );
}

// Returns the position of the matching text.
// It matches with a word starting from the '@' character
 // up to the caret position.
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 };
}

// Returns (through its callback) the suggestions for the current query.
function dataCallback( matchInfo, callback ) {
    // Simple search.
    // Filter the entire items array so only the items that start
    // with the query remain.
    var suggestions = itemsArray.filter( function( item ) {
        return item.name.toLowerCase().indexOf( matchInfo.query.toLowerCase() ) == 0;
    } );

    // Note: The callback function can also be executed asynchronously
    // so dataCallback can do XHR requests or use any other asynchronous API.
    callback( suggestions );
}

// Finally, instantiate the autocomplete class.
new CKEDITOR.plugins.autocomplete( editor, {
    textTestCallback: textTestCallback,
    dataCallback: dataCallback
} );

    Changing the behavior of the autocomplete class by subclassing it

    This plugin will expose a CKEDITOR.plugins.customAutocomplete class which uses a custom view that positions the panel relative to the CKEDITOR.editor.container.

    CKEDITOR.plugins.add( 'customautocomplete', {
    requires: 'autocomplete',

    onLoad: function() {
        var View = CKEDITOR.plugins.autocomplete.view,
            Autocomplete = CKEDITOR.plugins.autocomplete;

        function CustomView( editor ) {
            // Call the parent class constructor.
            View.call( this, editor );
        }
        // Inherit the view methods.
        CustomView.prototype = CKEDITOR.tools.prototypedCopy( View.prototype );

        // Change the positioning of the panel, so it is stretched
        // to 100% of the editor container width and is positioned
        // relative to the editor container.
        CustomView.prototype.updatePosition = function( range ) {
            var caretRect = this.getViewPosition( range ),
                container = this.editor.container;

            this.setPosition( {
                // Position the panel relative to the editor container.
                left: container.$.offsetLeft,
                top: caretRect.top,
                bottom: caretRect.bottom
            } );
            // Stretch the panel to 100% of the editor container width.
            this.element.setStyle( 'width', container.getSize( 'width' ) + 'px' );
        };

        function CustomAutocomplete( editor, configDefinition ) {
            // Call the parent class constructor.
            Autocomplete.call( this, editor, configDefinition );
        }
        // Inherit the autocomplete methods.
        CustomAutocomplete.prototype = CKEDITOR.tools.prototypedCopy( Autocomplete.prototype );

        CustomAutocomplete.prototype.getView = function() {
            return new CustomView( this.editor );
        }

        // Expose the custom autocomplete so it can be used later.
        CKEDITOR.plugins.customAutocomplete = CustomAutocomplete;
    }
} );

    Parameters

    editor : editor

    The editor to watch.

    config : configDefinition

    Configuration object for this autocomplete instance.

    Returns

    autocomplete

  • since 4.16.1

    addAriaAttributesToEditable()

    See source

  • attach()

    See source

    Attaches the autocomplete to the editor.

    • The view is appended to the DOM and the listeners are attached.
    • The text watcher is attached to the editor.
    • The listeners on the model and view events are added.

  • close()

    See source

    Closes the view and sets its state to inactive.

  • commit( [ itemId ] )

    See source

    Commits the currently chosen or given item. HTML is generated for this item using the getHtmlToInsert method and then it is inserted into the editor. The item is inserted into the query's range, so the query text is replaced by the inserted HTML.

    Parameters

    [ itemId ] : Number | String

    If given, then the specified item will be inserted into the editor instead of the currently chosen one.

  • destroy()

    See source

    Destroys the autocomplete instance. View element and event listeners will be removed from the DOM.

  • getHtmlToInsert( item ) → String

    See source

    Returns HTML that should be inserted into the editor when the item is committed.

    See also the commit method.

    Parameters

    item : item

    Returns

    String

    The HTML to insert.

  • getModel( dataCallback ) → model

    See source

    Creates and returns the model instance. This method is used when initializing the autocomplete and can be overwritten in order to return an instance of a different class than the default model.

    Parameters

    dataCallback : Function

    See configDefinition.dataCallback.

    Returns

    model

    The model instance.

  • getTextWatcher( textTestCallback ) → textWatcher

    See source

    Creates and returns the text watcher instance. This method is used while initializing the autocomplete and can be overwritten in order to return an instance of a different class than the default text watcher.

    Parameters

    textTestCallback : Function

    See the CKEDITOR.plugins.autocomplete arguments.

    Returns

    textWatcher

    The text watcher instance.

  • getView() → view

    See source

    Creates and returns the view instance. This method is used while initializing the autocomplete and can be overwritten in order to return an instance of a different class than the default view.

    Returns

    view

    The view instance.

  • open()

    See source

    Opens the panel if there is any data available.

  • since 4.16.1

    removeAriaAttributesFromEditable()

    See source

  • since 4.16.1

    updateAriaActiveDescendantAttributeOnEditable( id )

    See source

    Parameters

    id : Object

  • since 4.16.1

    updateAriaAttributesOnEditable( evt )

    See source

    Parameters

    evt : Object

  • private

    modelChangeListener( evt )

    See source

    The function that should be called once the model data has changed.

    Parameters

    evt : eventInfo

  • private

    onItemClick( evt )

    See source

    The function that should be called once a view item was clicked.

    Parameters

    evt : eventInfo

  • private

    onKeyDown( evt )

    See source

    The function that should be called on every keydown event occurred within the editable element.

    Parameters

    evt : event

  • private

    onSelectedItemId( evt )

    See source

    The function that should be called once an item was selected.

    Parameters

    evt : eventInfo

  • private

    onTextMatched( evt )

    See source

    The function that should be called once a text was matched by the text watcher component.

    Parameters

    evt : eventInfo

  • private

    onTextUnmatched( evt )

    See source

    The function that should be called once a text was unmatched by the text watcher component.

    Parameters

    evt : eventInfo

  • private

    viewRepositionListener()

    See source

    The function that should be called when the view has to be repositioned, e.g on scroll.