Report an issue
Class

CKEDITOR.plugins.autocomplete

class since 4.10.0

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

  • commitKeystrokes : Number[]

    readonly

    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.

  • editor : editor

    readonly

    The editor instance that autocomplete is attached to.

  • model : model

    readonly

    The autocomplete model instance.

  • outputTemplate : template

    readonly

    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

  • textWatcher : textWatcher

    readonly

    The autocomplete text watcher instance.

  • throttle : Number

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

    Defaults to 20

  • view : view

    readonly

    The autocomplete view instance.

  • _listeners : Array

    private

    Listeners registered by this autocomplete instance.

    Defaults to []

Methods

  • constructor( editor, config ) → autocomplete

    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
  • attach()

    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()

    Closes the view and sets its state to inactive.

  • commit( [ itemId ] )

    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()

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

  • getHtmlToInsert( item ) → String

    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

    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

    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

    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()

  • modelChangeListener( evt )

    private

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

    Parameters

    evt : eventInfo
  • onItemClick( evt )

    private

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

    Parameters

    evt : eventInfo
  • onKeyDown( evt )

    private

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

    Parameters

    evt : event
  • onSelectedItemId( evt )

    private

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

    Parameters

    evt : eventInfo
  • onTextMatched( evt )

    private

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

    Parameters

    evt : eventInfo
  • onTextUnmatched( evt )

    private

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

    Parameters

    evt : eventInfo
  • viewRepositionListener()

    private

    The function that should be called once the content has changed.