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

CKEDITOR.plugins.mentions.configDefinition

class since 4.10.0 abstract
See source

Abstract class describing the definition of a mentions plugin configuration.

This virtual class illustrates the properties that the developers can use to define and create a mentions configuration definition. The mentions definition object represents an object as a set of properties defining a mentions data feed and its optional parameters.

Simple usage:

var definition = { feed: ['Anna', 'Thomas', 'John'], minChars: 0 };

Filtering

Properties

  • cache : Boolean

    See source

    Indicates if the URL feed responses will be cached.

    The cache is based on the URL request and is shared between all mentions instances (including different editors).

    Defaults to true

  • caseSensitive : Boolean

    See source

    Indicates that a mentions instance is case-sensitive for simple items feed, i.e. an array feed.

    Note: This will take no effect on feeds using a callback or URLs, as in this case the results are expected to be already filtered.

    Defaults to false

  • feed : String | String[] | Function

    See source

    The feed of items to be displayed in the mentions plugin.

    Essential option which should be configured to create a correct mentions configuration definition. There are three different ways to create a data feed:

    • A simple array of text matches as a synchronous data feed.
    • A backend URL string responding with a list of items in the JSON format. This method utilizes an asynchronous data feed.
    • A function allowing to use an asynchronous callback to customize the data source. Gives the freedom to use any data source depending on your implementation.

    An array of text matches

    The easiest way to configure the data feed is to provide an array of text matches. The mentions plugin will use a synchronous data feed and create item IDs by itself. The biggest advantage of this method is its simplicity, although it is limited to a synchronous data feed. Please see two other methods if you require more complex techniques to fetch the text matches.

    var definition = { feed: ['Anna', 'Thomas', 'John'], minChars: 0 };

    By default query matching for an array feed is case insensitive. You can change this behavior by setting the caseSensitive property to true.

    A backend URL string

    You can provide a backend URL string which will be used to fetch text matches from a custom endpoint service. Each time the user types matching text into an editor, your backend service will be queried for text matches. An Ajax URL request should response with an array of matches in the JSON format. A URL response will appear in the mentions dropdown.

    A backend URL string features the special encodedQuery variable replaced with a mentions query. The encodedQuery variable allows you to create a customized URL which can be both RESTful API compliant or any other URL which suits your needs. E.g. for the query @anna and the given URL /users?name={encodedQuery} your endpoint service will be queried with /users?name=anna.

    var definition = { feed: '/users?query={encodedQuery}' };

    To avoid multiple HTTP requests to your endpoint service, each HTTP response is cached by default and shared globally. See the cache property for more details.

    Function feed

    This method is recommended for advanced users who would like to take full control of the data feed. It allows you to provide the data feed as a function that accepts two parameters: options and callback. The provided function will be called every time the user types matching text into an editor.

    The options object contains information about the current query and a marker.

    { query: 'anna', marker: '@' }

    The callback argument should be used to pass an array of text match items into the mentions instance.

    callback( [ { id: 1, name: 'anna' }, { id: 2, name: 'annabelle' } ] );

    Depending on your use case, you can use this code as an example boilerplate to create your own function feed:

    var definition = {
    feed: function( opts, callback ) {
        var xhr = new XMLHttpRequest();

        xhr.onreadystatechange = function() {
            if ( xhr.readyState == 4 ) {
                if ( xhr.status == 200 ) {
                    callback( JSON.parse( this.responseText ) );
                } else {
                    callback( [] );
                }
            }
        }

        xhr.open( 'GET', '/users?name=' + opts.query );
        xhr.send();
    }
};

    Other details

    When using the asynchronous method, i.e. a backend URL string or a function, you should provide correct object structure containing a unique item ID and a name.

    // Example of expected results from the backend API.
// The `firstName` and `lastName` properties are optional.
[
        { id: 1, name: 'anna87', firstName: 'Anna', lastName: 'Doe' },
        { id: 2, name: 'tho-mass', firstName: 'Thomas', lastName: 'Doe' },
        { id: 3, name: 'ozzy', firstName: 'John', lastName: 'Doe' }
]

  • followingSpace : Boolean

    See source

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

  • itemTemplate : String

    See source

    The panel's item template used to render matches in the dropdown.

    You can use data item properties to customize the template.

    A minimal template must be wrapped with a HTML li element containing the data-id="{id}" attribute.

    var itemTemplate = '<li data-id="{id}"><img src="{iconSrc}" alt="{name}">{name}</li>';

  • itemsLimit : Number

    See source

    Indicates the limit of items rendered in the dropdown.

    For falsy values like 0 or null all items will be rendered.

  • marker : String

    See source

    The character that should trigger autocompletion.

    Defaults to '@'

  • minChars : Number

    See source

    The number of characters that should follow the marker character in order to trigger the mentions feature.

    Defaults to 2

  • outputTemplate : String

    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>`;

  • pattern : RegExp

    See source

    The pattern used to match queries.

    The default pattern matches words with the query including the config.marker and config.minChars properties.

    // Match only words starting with "a".
var pattern = /^a+\w*$/;

  • throttle : Number

    See source

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

    Defaults to 200