Mentions plugin

[mlewand]

Are you reporting a feature request or a bug?

Feature request

Provide detailed reproduction steps (if any)

It has been requested for some time to ship a Mentions/Autocomplete feature for CKEditor 4.

The idea is that as you type part of certain text, CKEditor displays a panel suggesting you some suggested values, so that you don't have to write it on your own, but use autocomplete instead.

It should support both synchronous and asynchronous entires lists (feeds).

Multiple Feeds

The feature should also support multiple feeds at the same time.

For instance, you're using @ to mention users, while # to mention ticket numbers.

Differences from the Autocomplete plugin

While Mentions feature is built on top of the Autocomplete feature, it's purpose is to expose as stupid simple and minimal API. It should be ready basically by providing list of users (entries) and be ready to use.

Autocomplete in contrast provides much more possibilities to control what's and how being matched, but at a cost of more complex API.

Preview

Users interested in seeing how the feature looks today can preview it on our Mentions feature branch preview.

Browser Support

Same as for the Autocomplete plugin.

Related Issues

• Autocomplete plugin

[mlewand]

While thinking about a SDK sample for mentions I played a bit with emojis, just to figure out that it's demoing more autocomplete feature (the generic feature). I'll leave it here for a reference: https://codepen.io/mlewand/pen/WMmWyr

[mlewand]

It's important that we keep configuration as simple as possible. For instance we have already autocomplete plugin, which can provide mentions capability, but it requires a lot of code to actually instantiate it and it provides some low level data (ranges) which are not needed for the mentions plugin.

[mlewand]

I've been thinking about ways to configure the mentions plugin. As mentioned above, it should be operable by setting config alone, there should be no need to add CKEditor instanceReady listeners to execute code, or anything like that.

I have come with few use cases, and a config schemma that fits them all.

Simple case

Dev simply provides a simple list of user names, mentions plugin will use synchronous data feed.

config.mentions = {
	// User names.
	feed: [ 'andrew', 'bobby', 'james', 'julian', 'kate' ],
	marker: `@`,
	minChars: 0
};

Complex case

Dev uses mentions plugin for three different feeds, two of which use the same marker.

• user names (denoted with @)
• group names (denoted with @)
• ticket numbers (denoted with #)

config.mentions = [ {
	// User names.
	feed: [ 'andrew', 'bobby', 'james', 'julian', 'kate' ],
	marker: `@`
}, {
	// Groups.
	feed: [ 'admins', 'mods', 'users' ],
	marker: '@',
	// Entries have a group HTML class, so that it could feature a customized icon that differs it from users in the dropdown.
	template: '<li data-id="{id}" class="group"><a href="#">{name}</a></li>'
}, {
	// Ticket references.
	feed: [ '1234', '1235', '1236' ],
	marker: '#'
} ];

Asynchronous

In this case dev is requesting backend URL to get the list of users.

Assuming that GET query to /user-controller/get-list would return a content like:

[ {
	"id": 1,
	"name": "andrew81",
	"firstName": "Andrew",
	"lastName": "Doe"
}, {
	"id": 2,
	"name": "bob__",
	"firstName": "Bob",
	"lastName": "Doe"
}, {
	"id": 3,
	"name": "jane88",
	"firstName": "Jane",
	"lastName": "Doe"
} ]

config.mentions = {
	// User names.
	feed: '/user-controller/get-list/{encodedQuery}',
	template: '<li data-id="{id}" class="group"><a href="#">{firstName} {lastName} ({name})</a></li>'-
};

Or a more "explicit" version:

config.mentions = {
	// User names.
	feed: function( query, callback ) {
		callMyBackend( function( results ) {
			callback( results );
		} );
	},
	template: '<li data-id="{id}" class="group"><a href="#">{firstName} {lastName} ({name})</a></li>'-
};

Summary

To sum it up, config mentions object should support following properties:

• feed - String[]/String/Function - Feed of items to be displayed in mentions plugin.
  • String[] - Array of entries that should appear in the mentions - this is the simples possible way to configure the plugin.
  • Function - This is for asynchronous (ofc would work for sync too) feeds. Devs gets a complete control over the process.
  • String - URL to be requested for a JSON of matches that should appear in a dropdown. Note that it features encodedQuery variable that will be replaced with URL encoded query of current mention query.
• template - String - Template used to render matches in a dropdown. Optional, defaults to the default template in Autocomplete plugin (though it might be a subject of change).
• marker - String - A character that should trigger autocompletion. Optional, defaults to @.
• minChars - Number - A number of character that should follow the marker char in order to trigger mention feature. Optional, defaults to 2.

[jacekbogdanski]

Currently mentions are case sensitive for the feed passed as an array (simple case).
E.g. with feed ['Anna', 'Thomas', 'John'] typing @a will not show autocomplete view.
I think we should change matching feed to case insensitive by default which is more common and add additional option like caseSensitive for case sensitive matching.