mention.js 7.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232
  1. /**
  2. * @license Copyright (c) 2003-2019, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module mention/mention
  7. */
  8. import Plugin from '@ckeditor/ckeditor5-core/src/plugin';
  9. import MentionEditing, { _toMentionAttribute } from './mentionediting';
  10. import MentionUI from './mentionui';
  11. import '../theme/mention.css';
  12. /**
  13. * The mention plugin.
  14. *
  15. * For a detailed overview, check the {@glink features/mentions Mention feature documentation}.
  16. *
  17. * @extends module:core/plugin~Plugin
  18. */
  19. export default class Mention extends Plugin {
  20. /**
  21. * Creates a mention attribute value from the provided view element and optional data.
  22. *
  23. * editor.plugins.get( 'Mention' ).toMentionAttribute( viewElement, { userId: '1234' } );
  24. *
  25. * // for a viewElement: <span data-mention="@joe">@John Doe</span>
  26. * // it will return:
  27. * // { id: '@joe', userId: '1234', _uid: '7a7bc7...', _text: '@John Doe' }
  28. *
  29. * @param {module:engine/view/element~Element} viewElement
  30. * @param {String|Object} [data] Additional data to be stored in the mention attribute.
  31. * @returns {module:mention/mention~MentionAttribute}
  32. */
  33. toMentionAttribute( viewElement, data ) {
  34. return _toMentionAttribute( viewElement, data );
  35. }
  36. /**
  37. * @inheritDoc
  38. */
  39. static get pluginName() {
  40. return 'Mention';
  41. }
  42. /**
  43. * @inheritDoc
  44. */
  45. static get requires() {
  46. return [ MentionEditing, MentionUI ];
  47. }
  48. }
  49. /**
  50. * The configuration of the {@link module:mention/mention~Mention} feature.
  51. *
  52. * Read more in {@link module:mention/mention~MentionConfig}.
  53. *
  54. * @member {module:mention/mention~MentionConfig} module:core/editor/editorconfig~EditorConfig#mention
  55. * @type {Array.<module/mention~MentionFeed>}
  56. */
  57. /**
  58. * The configuration of the mention feature.
  59. *
  60. * Read more about {@glink features/mentions#configuration configuring the mention feature}.
  61. *
  62. * ClassicEditor
  63. * .create( editorElement, {
  64. * mention: ... // Media embed feature options.
  65. * } )
  66. * .then( ... )
  67. * .catch( ... );
  68. *
  69. * See {@link module:core/editor/editorconfig~EditorConfig all editor options}.
  70. *
  71. * @interface MentionConfig
  72. */
  73. /**
  74. * The list of mention feeds supported by the editor.
  75. *
  76. * ClassicEditor
  77. * .create( editorElement, {
  78. * plugins: [ Mention, ... ],
  79. * mention: {
  80. * feeds: [
  81. * {
  82. * marker: '@',
  83. * feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ]
  84. * },
  85. * ...
  86. * ]
  87. * }
  88. * } )
  89. * .then( ... )
  90. * .catch( ... );
  91. *
  92. * You can provide as many mention feeds but they must use different `marker`s.
  93. * For example, you can use `'@'` to autocomplete people and `'#'` to autocomplete tags.
  94. *
  95. * @member {Array.<module:mention/mention~MentionFeed>} module:mention/mention~MentionConfig#feeds
  96. */
  97. /**
  98. * The mention feed descriptor. Used in {@link module:mention/mention~MentionConfig `config.mention`}.
  99. *
  100. * See {@link module:mention/mention~MentionConfig} to learn more.
  101. *
  102. * // Static configuration.
  103. * const mentionFeedPeople = {
  104. * marker: '@',
  105. * feed: [ '@Alice', '@Bob', ... ],
  106. * minimumCharacters: 2
  107. * };
  108. *
  109. * // Simple, synchronous callback.
  110. * const mentionFeedTags = {
  111. * marker: '#',
  112. * feed: searchString => {
  113. * return tags
  114. * // Filter the tags list.
  115. * .filter( tag => {
  116. * return tag.toLowerCase().includes( queryText.toLowerCase() );
  117. * } )
  118. * // Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
  119. * .slice( 0, 10 );
  120. * }
  121. * };
  122. *
  123. * const tags = [ 'wysiwyg', 'rte', 'rich-text-edior', 'collaboration', 'real-time', ... ];
  124. *
  125. * // Asynchronous callback.
  126. * const mentionFeedPlaceholders = {
  127. * marker: '$',
  128. * feed: searchString => {
  129. * return getMatchingPlaceholders( searchString );
  130. * }
  131. * };
  132. *
  133. * function getMatchingPlaceholders( searchString ) {
  134. * return new Promise( resolve => {
  135. * doSomeXHRQuery( result => {
  136. * // console.log( result );
  137. * // -> [ '$name', '$surname', '$postal', ... ]
  138. *
  139. * resolve( result );
  140. * } );
  141. * } );
  142. * }
  143. *
  144. * @typedef {Object} module:mention/mention~MentionFeed
  145. * @property {String} [marker] The character which triggers autocompletion for mention. It must be a single character.
  146. * @property {Array.<module:mention/mention~MentionFeedItem>|Function} feed The autocomplete items. Provide an array for
  147. * a static configuration (the mention feature will show matching items automatically) or a function which returns an array of
  148. * matching items (directly, or via a promise).
  149. * @property {Number} [minimumCharacters=0] Specifies after how many characters the autocomplete panel should be shown.
  150. * @property {Function} [itemRenderer] Function that renders a {@link module:mention/mention~MentionFeedItem}
  151. * to the autocomplete panel.
  152. */
  153. /**
  154. * The mention feed item. It may be defined as a string or a plain object.
  155. *
  156. * When defining a feed item as a plain object, the `id` property is obligatory. The additional properties
  157. * can be used when customizing the mention feature bahavior
  158. * (see {@glink features/mentions#customizing-the-autocomplete-list "Customizing the autocomplete list"}
  159. * and {@glink features/mentions#customizing-the-output "Customizing the output"} sections).
  160. *
  161. * ClassicEditor
  162. * .create( editorElement, {
  163. * plugins: [ Mention, ... ],
  164. * mention: {
  165. * feeds: [
  166. * // Feed items as objects.
  167. * {
  168. * marker: '@',
  169. * feed: [
  170. * {
  171. * id: '@Barney',
  172. * fullName: 'Barney Bloom'
  173. * },
  174. * {
  175. * id: '@Lily',
  176. * fullName: 'Lily Smith'
  177. * },
  178. * {
  179. * id: '@Marshall',
  180. * fullName: 'Marshall McDonald'
  181. * },
  182. * {
  183. * id: '@Robin',
  184. * fullName: 'Robin Hood'
  185. * },
  186. * {
  187. * id: '@Ted',
  188. * fullName: 'Ted Cruze'
  189. * },
  190. * // ...
  191. * ]
  192. * },
  193. *
  194. * // Feed items as plain strings.
  195. * {
  196. * marker: '#',
  197. * feed: [ 'wysiwyg', 'rte', 'rich-text-edior', 'collaboration', 'real-time', ... ]
  198. * },
  199. * ]
  200. * }
  201. * } )
  202. * .then( ... )
  203. * .catch( ... );
  204. *
  205. * @typedef {Object|String} module:mention/mention~MentionFeedItem
  206. * @property {String} id Unique id of the mention. It must start with the marker character.
  207. * @property {String} [text] Text inserted into the editor when creating a mention.
  208. */
  209. /**
  210. * Represents mention in the model.
  211. *
  212. * See {@link module:mention/mention~Mention#toMentionAttribute `Mention#toMentionAttribute()`}.
  213. *
  214. * @interface module:mention/mention~MentionAttribute
  215. * @property {String} id Id of a mention – identifies the mention item in mention feed.
  216. * @property {String} _uid Internal mention view item id. Should be passed as an `option.id` when using
  217. * {@link module:engine/view/downcastwriter~DowncastWriter#createAttributeElement writer.createAttributeElement()}.
  218. * @property {String} _text Helper property that holds text of inserted mention. Used for detecting broken mention in the editing area.
  219. */