/**
* @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
* For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
*/
/**
* @module mention/mention
*/
import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
import MentionEditing, { _toMentionAttribute } from './mentionediting';
import MentionUI from './mentionui';
import '../theme/mention.css';
/**
* The mention plugin.
*
* For a detailed overview, check the {@glink features/mentions Mention feature documentation}.
*
* @extends module:core/plugin~Plugin
*/
export default class Mention extends Plugin {
/**
* Creates a mention attribute value from the provided view element and optional data.
*
* editor.plugins.get( 'Mention' ).toMentionAttribute( viewElement, { userId: '1234' } );
*
* // for a viewElement: @John Doe
* // it will return:
* // { id: '@joe', userId: '1234', _uid: '7a7bc7...', _text: '@John Doe' }
*
* @param {module:engine/view/element~Element} viewElement
* @param {String|Object} [data] Additional data to be stored in the mention attribute.
* @returns {module:mention/mention~MentionAttribute}
*/
toMentionAttribute( viewElement, data ) {
return _toMentionAttribute( viewElement, data );
}
/**
* @inheritDoc
*/
static get pluginName() {
return 'Mention';
}
/**
* @inheritDoc
*/
static get requires() {
return [ MentionEditing, MentionUI ];
}
}
/**
* The configuration of the {@link module:mention/mention~Mention} feature.
*
* Read more in {@link module:mention/mention~MentionConfig}.
*
* @member {module:mention/mention~MentionConfig} module:core/editor/editorconfig~EditorConfig#mention
* @type {Array.}
*/
/**
* The configuration of the mention feature.
*
* Read more about {@glink features/mentions#configuration configuring the mention feature}.
*
* ClassicEditor
* .create( editorElement, {
* mention: ... // Media embed feature options.
* } )
* .then( ... )
* .catch( ... );
*
* See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
*
* @interface MentionConfig
*/
/**
* The list of mention feeds supported by the editor.
*
* ClassicEditor
* .create( editorElement, {
* plugins: [ Mention, ... ],
* mention: {
* feeds: [
* {
* marker: '@',
* feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ]
* },
* ...
* ]
* }
* } )
* .then( ... )
* .catch( ... );
*
* You can provide as many mention feeds but they must use different `marker`s.
* For example, you can use `'@'` to autocomplete people and `'#'` to autocomplete tags.
*
* @member {Array.} module:mention/mention~MentionConfig#feeds
*/
/**
* The mention feed descriptor. Used in {@link module:mention/mention~MentionConfig `config.mention`}.
*
* See {@link module:mention/mention~MentionConfig} to learn more.
*
* // Static configuration.
* const mentionFeedPeople = {
* marker: '@',
* feed: [ '@Alice', '@Bob', ... ],
* minimumCharacters: 2
* };
*
* // Simple, synchronous callback.
* const mentionFeedTags = {
* marker: '#',
* feed: searchString => {
* return tags
* // Filter the tags list.
* .filter( tag => {
* return tag.toLowerCase().includes( queryText.toLowerCase() );
* } )
* // Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
* .slice( 0, 10 );
* }
* };
*
* const tags = [ 'wysiwyg', 'rte', 'rich-text-edior', 'collaboration', 'real-time', ... ];
*
* // Asynchronous callback.
* const mentionFeedPlaceholders = {
* marker: '$',
* feed: searchString => {
* return getMatchingPlaceholders( searchString );
* }
* };
*
* function getMatchingPlaceholders( searchString ) {
* return new Promise( resolve => {
* doSomeXHRQuery( result => {
* // console.log( result );
* // -> [ '$name', '$surname', '$postal', ... ]
*
* resolve( result );
* } );
* } );
* }
*
* @typedef {Object} module:mention/mention~MentionFeed
* @property {String} [marker] The character which triggers autocompletion for mention. It must be a single character.
* @property {Array.|Function} feed The autocomplete items. Provide an array for
* a static configuration (the mention feature will show matching items automatically) or a function which returns an array of
* matching items (directly, or via a promise).
* @property {Number} [minimumCharacters=0] Specifies after how many characters the autocomplete panel should be shown.
* @property {Function} [itemRenderer] Function that renders a {@link module:mention/mention~MentionFeedItem}
* to the autocomplete panel.
*/
/**
* The mention feed item. It may be defined as a string or a plain object.
*
* When defining a feed item as a plain object, the `id` property is obligatory. The additional properties
* can be used when customizing the mention feature bahavior
* (see {@glink features/mentions#customizing-the-autocomplete-list "Customizing the autocomplete list"}
* and {@glink features/mentions#customizing-the-output "Customizing the output"} sections).
*
* ClassicEditor
* .create( editorElement, {
* plugins: [ Mention, ... ],
* mention: {
* feeds: [
* // Feed items as objects.
* {
* marker: '@',
* feed: [
* {
* id: '@Barney',
* fullName: 'Barney Bloom'
* },
* {
* id: '@Lily',
* fullName: 'Lily Smith'
* },
* {
* id: '@Marshall',
* fullName: 'Marshall McDonald'
* },
* {
* id: '@Robin',
* fullName: 'Robin Hood'
* },
* {
* id: '@Ted',
* fullName: 'Ted Cruze'
* },
* // ...
* ]
* },
*
* // Feed items as plain strings.
* {
* marker: '#',
* feed: [ 'wysiwyg', 'rte', 'rich-text-edior', 'collaboration', 'real-time', ... ]
* },
* ]
* }
* } )
* .then( ... )
* .catch( ... );
*
* @typedef {Object|String} module:mention/mention~MentionFeedItem
* @property {String} id Unique id of the mention. It must start with the marker character.
* @property {String} [text] Text inserted into the editor when creating a mention.
*/
/**
* Represents mention in the model.
*
* See {@link module:mention/mention~Mention#toMentionAttribute `Mention#toMentionAttribute()`}.
*
* @interface module:mention/mention~MentionAttribute
* @property {String} id Id of a mention – identifies the mention item in mention feed.
* @property {String} _uid Internal mention view item id. Should be passed as an `option.id` when using
* {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement writer.createAttributeElement()}.
* @property {String} _text Helper property that holds text of inserted mention. Used for detecting broken mention in the editing area.
*/