CKEDITOR.plugins.autocomplete

Properties

• readonly

  commitKeystrokes : Number[]CKEDITOR.plugins.autocomplete#commitKeystrokes

  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 : editorCKEDITOR.plugins.autocomplete#editor

  See source

  The editor instance that autocomplete is attached to.

• since 4.20.0 readonly

  followingSpace : BooleanCKEDITOR.plugins.autocomplete#followingSpace

  See source

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

• readonly

  model : modelCKEDITOR.plugins.autocomplete#model

  See source

  The autocomplete model instance.

• readonly

  outputTemplate : templateCKEDITOR.plugins.autocomplete#outputTemplate

  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 : textWatcherCKEDITOR.plugins.autocomplete#textWatcher

  See source

  The autocomplete text watcher instance.

• throttle : NumberCKEDITOR.plugins.autocomplete#throttle

  See source

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

  Defaults to 20

• readonly

  view : viewCKEDITOR.plugins.autocomplete#view

  See source

  The autocomplete view instance.

• private

  _listeners : ArrayCKEDITOR.plugins.autocomplete#_listeners

  See source

  Listeners registered by this autocomplete instance.

  Defaults to []

Methods

• constructor( editor, config ) → autocompleteCKEDITOR.plugins.autocomplete#constructor

  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:

  • config.textTestCallback – A function being called by the text watcher plugin, as new text is being inserted. Its purpose is to determine whether a given range should be matched or not. See CKEDITOR.plugins.textWatcher.constructor for more details. There is also CKEDITOR.plugins.textMatch.match which is a handy helper for that purpose.
  • config.dataCallback – A function that should return (through its callback) suggestion data for the current query string.

  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()CKEDITOR.plugins.autocomplete#addAriaAttributesToEditable

  See source

  attach()CKEDITOR.plugins.autocomplete#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()CKEDITOR.plugins.autocomplete#close

  See source

  Closes the view and sets its state to inactive.

  commit( [ itemId ] )CKEDITOR.plugins.autocomplete#commit

  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()CKEDITOR.plugins.autocomplete#destroy

  See source

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

  getHtmlToInsert( item ) → StringCKEDITOR.plugins.autocomplete#getHtmlToInsert

  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 ) → modelCKEDITOR.plugins.autocomplete#getModel

  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 ) → textWatcherCKEDITOR.plugins.autocomplete#getTextWatcher

  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() → viewCKEDITOR.plugins.autocomplete#getView

  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()CKEDITOR.plugins.autocomplete#open

  See source

  Opens the panel if there is any data available.

  since 4.16.1

  removeAriaAttributesFromEditable()CKEDITOR.plugins.autocomplete#removeAriaAttributesFromEditable

  See source

  since 4.16.1

  updateAriaActiveDescendantAttributeOnEditable( id )CKEDITOR.plugins.autocomplete#updateAriaActiveDescendantAttributeOnEditable

  See source

  Parameters

  id : Object

  since 4.16.1

  updateAriaAttributesOnEditable( evt )CKEDITOR.plugins.autocomplete#updateAriaAttributesOnEditable

  See source

  Parameters

  evt : Object

  private

  modelChangeListener( evt )CKEDITOR.plugins.autocomplete#modelChangeListener

  See source

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

  Parameters

  evt : eventInfo

  private

  onItemClick( evt )CKEDITOR.plugins.autocomplete#onItemClick

  See source

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

  Parameters

  evt : eventInfo

  private

  onKeyDown( evt )CKEDITOR.plugins.autocomplete#onKeyDown

  See source

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

  Parameters

  evt : event

  private

  onSelectedItemId( evt )CKEDITOR.plugins.autocomplete#onSelectedItemId

  See source

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

  Parameters

  evt : eventInfo

  private

  onTextMatched( evt )CKEDITOR.plugins.autocomplete#onTextMatched

  See source

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

  Parameters

  evt : eventInfo

  private

  onTextUnmatched( evt )CKEDITOR.plugins.autocomplete#onTextUnmatched

  See source

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

  Parameters

  evt : eventInfo

  private

  viewRepositionListener()CKEDITOR.plugins.autocomplete#viewRepositionListener

  See source

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