Piotrek Koszuliński 6 lat temu
rodzic
commit
e3a7c6c233

+ 1 - 1
packages/ckeditor5-mention/docs/_snippets/features/custom-mention-colors-variables.js

@@ -20,7 +20,7 @@ ClassicEditor
 			feeds: [
 				{
 					marker: '@',
-					feed: [ 'Barney', 'Lily', 'Marshall', 'Robin', 'Ted' ]
+					feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ]
 				}
 			]
 		}

+ 9 - 3
packages/ckeditor5-mention/docs/_snippets/features/mention-customization.js

@@ -96,10 +96,16 @@ const items = [
 function getFeedItems( queryText ) {
 	// As an example of an asynchronous action, let's return a promise
 	// that resolves after a 100ms timeout.
-	// This can be a server request, or any sort of delayed action.
+	// This can be a server request or any sort of delayed action.
 	return new Promise( resolve => {
 		setTimeout( () => {
-			resolve( items.filter( isItemMatching ) );
+			const itemsToDisplay = items
+				// Filter out the full list of all items to only those matching queryText.
+				.filter( isItemMatching )
+				// Return 10 items max - needed for generic queries when the list may contain hundreds of elements.
+				.slice( 0, 10 );
+
+			resolve( itemsToDisplay );
 		}, 100 );
 	} );
 
@@ -120,7 +126,7 @@ function customItemRenderer( item ) {
 	const itemElement = document.createElement( 'span' );
 
 	itemElement.classList.add( 'custom-item' );
-	itemElement.id = `mention-list-item-id-${ item.userid }`;
+	itemElement.id = `mention-list-item-id-${ item.userId }`;
 	itemElement.textContent = `${ item.name } `;
 
 	const usernameElement = document.createElement( 'span' );

+ 1 - 1
packages/ckeditor5-mention/docs/_snippets/features/mention.js

@@ -20,7 +20,7 @@ ClassicEditor
 			feeds: [
 				{
 					marker: '@',
-					feed: [ 'Barney', 'Lily', 'Marshall', 'Robin', 'Ted' ]
+					feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ]
 				}
 			]
 		}

+ 27 - 9
packages/ckeditor5-mention/docs/features/mention.md

@@ -31,7 +31,7 @@ ClassicEditor
 			feeds: [
 				{
 					marker: '@',
-					feed: [ 'Barney', 'Lily', 'Marshall', 'Robin', 'Ted' ],
+					feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ],
 					minimumCharacters: 1
 				}
 			}
@@ -65,12 +65,30 @@ When using a callback you can return a `Promise` that resolves with the list of
 The callback receives the query text which should be used to filter item suggestions. It should return a `Promise` and resolve it with an array of items that match to the feed text.
 
 ```js
+ClassicEditor
+	.create( document.querySelector( '#editor' ), {
+		// This feature is not available in any of the builds.
+		// See the "Installation" section.
+		plugins: [ Mention, ... ],
+
+		mention: {
+			feeds: [
+				{
+					marker: '@',
+					feed: getFeedItems
+				}
+			}
+		}
+	} )
+	.then( ... )
+	.catch( ... );
+
 const items = [
-	{ id: '1', name: 'Barney Stinson', username: 'swarley', link: 'https://www.imdb.com/title/tt0460649/characters/nm0000439' },
-	{ id: '2', name: 'Lily Aldrin', username: 'lilypad', link: 'https://www.imdb.com/title/tt0460649/characters/nm0004989' },
-	{ id: '3', name: 'Marshall Eriksen', username: 'marshmallow', link: 'https://www.imdb.com/title/tt0460649/characters/nm0781981' },
-	{ id: '4', name: 'Robin Scherbatsky', username: 'rsparkles', link: 'https://www.imdb.com/title/tt0460649/characters/nm1130627' },
-	{ id: '5', name: 'Ted Mosby', username: 'tdog', link: 'https://www.imdb.com/title/tt0460649/characters/nm1102140' }
+	{ id: '@swarley', userId: '1', name: 'Barney Stinson', link: 'https://www.imdb.com/title/tt0460649/characters/nm0000439' },
+	{ id: '@lilypad', userId: '2', name: 'Lily Aldrin', link: 'https://www.imdb.com/title/tt0460649/characters/nm0004989' },
+	{ id: '@marshmallow', userId: '3', name: 'Marshall Eriksen', link: 'https://www.imdb.com/title/tt0460649/characters/nm0781981' },
+	{ id: '@rsparkles', userId: '4', name: 'Robin Scherbatsky', link: 'https://www.imdb.com/title/tt0460649/characters/nm1130627' },
+	{ id: '@tdog', userId: '5', name: 'Ted Mosby', link: 'https://www.imdb.com/title/tt0460649/characters/nm1102140' }
 ];
 
 function getFeedItems( queryText ) {
@@ -97,7 +115,7 @@ function getFeedItems( queryText ) {
 		// Include an item in the search results if name or username includes the current user input.
 		return (
 			item.name.toLowerCase().includes( searchString ) ||
-			item.username.toLowerCase().includes( searchString )
+			item.id.toLowerCase().includes( searchString )
 		);
 	}
 }
@@ -132,13 +150,13 @@ function customItemRenderer( item ) {
 	const itemElement = document.createElement( 'span' );
 
 	itemElement.classList.add( 'custom-item' );
-	itemElement.id = `mention-list-item-id-${ item.id }`;
+	itemElement.id = `mention-list-item-id-${ item.userId }`;
 	itemElement.textContent = `${ item.name } `;
 
 	const usernameElement = document.createElement( 'span' );
 
 	usernameElement.classList.add( 'custom-item-username' );
-	usernameElement.textContent = `@${ item.username }`;
+	usernameElement.textContent = item.id;
 
 	itemElement.appendChild( usernameElement );
 

+ 13 - 11
packages/ckeditor5-mention/src/mention.js

@@ -23,7 +23,7 @@ import '../theme/mention.css';
  */
 export default class Mention extends Plugin {
 	/**
-	 * Creates mention attribute value from provided view element and optional data.
+	 * Creates a mention attribute value from the provided view element and optional data.
 	 *
 	 *		editor.plugins.get( 'Mention' ).toMentionAttribute( viewElement, { userId: '1234' } );
 	 *
@@ -32,7 +32,7 @@ export default class Mention extends Plugin {
 	 *		// { id: '@joe', userId: '1234', _uid: '7a7bc7...', _text: '@John Doe' }
 	 *
 	 * @param {module:engine/view/element~Element} viewElement
-	 * @param {String|Object} [data] Mention data to be extended.
+	 * @param {String|Object} [data] Additional data to be stored in the mention attribute.
 	 * @returns {module:mention/mention~MentionAttribute}
 	 */
 	toMentionAttribute( viewElement, data ) {
@@ -90,7 +90,7 @@ export default class Mention extends Plugin {
  *					feeds: [
  *						{
  *							marker: '@',
- *							feed: [ 'Barney', 'Lily', 'Marshall', 'Robin', 'Ted' ]
+ *							feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ]
  *						},
  *						...
  * 					]
@@ -113,7 +113,7 @@ export default class Mention extends Plugin {
  *		// Static configuration.
  *		const mentionFeedPeople = {
  *			marker: '@',
- *			feed: [ 'Alice', 'Bob', ... ],
+ *			feed: [ '@Alice', '@Bob', ... ],
  *			minimumCharacters: 2
  *		};
  *
@@ -180,23 +180,23 @@ export default class Mention extends Plugin {
  *							marker: '@',
  *							feed: [
  *								{
- *									id: 'Barney',
+ *									id: '@Barney',
  *									fullName: 'Barney Bloom'
  *								},
  *								{
- *									id: 'Lily',
+ *									id: '@Lily',
  *									fullName: 'Lily Smith'
  *								},
  *								{
- *									id: 'Marshall',
+ *									id: '@Marshall',
  *									fullName: 'Marshall McDonald'
  *								},
  *								{
- *									id: 'Robin',
+ *									id: '@Robin',
  *									fullName: 'Robin Hood'
  *								},
  *								{
- *									id: 'Ted',
+ *									id: '@Ted',
  *									fullName: 'Ted Cruze'
  *								},
  *								// ...
@@ -215,15 +215,17 @@ export default class Mention extends Plugin {
  *			.catch( ... );
  *
  * @typedef {Object|String} module:mention/mention~MentionFeedItem
- * @property {String} id Unique id of the mention.
+ * @property {String} id Unique id of the mention. It must start with the marker character.
  * @property {String} [text] Text used for display in mention auto-complete suggestions list.
  */
 
 /**
  * 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} 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.

+ 40 - 4
packages/ckeditor5-mention/src/mentioncommand.js

@@ -85,12 +85,48 @@ export default class MentionCommand extends Command {
 
 		const mention = _addMentionAttributes( { _text: mentionText, id: mentionID }, mentionData );
 
-		if ( mentionID.charAt( 0 ) != options.marker ) {
-			throw new CKEditorError( 'foo' );
+		if ( options.marker.length != 1 ) {
+			/**
+			 * The marker must be one character.
+			 *
+			 * Correct markers: `'@'`, `'#'`.
+			 *
+			 * Incorrect markers: `'$$'`, `'[@'`.
+			 *
+			 * See {@link module:mention/mention~MentionConfig}.
+			 *
+			 * @error markercommand-incorrect-marker
+			 */
+			throw new CKEditorError( 'markercommand-incorrect-marker: The marker must be one character.' );
 		}
 
-		if ( options.marker.length != 1 ) {
-			throw new CKEditorError( 'foo2' );
+		if ( mentionID.charAt( 0 ) != options.marker ) {
+			/**
+			 * The feed item id must start with the marker character.
+			 *
+			 * Correct mention feed setting:
+			 *
+			 *		mentions: [
+			 *			{
+			 *				marker: '@',
+			 *				feed: [ '@Ann', '@Barney', ... ]
+			 *			}
+			 *		]
+			 *
+			 * Incorrect mention feed setting:
+			 *
+			 *		mentions: [
+			 *			{
+			 *				marker: '@',
+			 *				feed: [ 'Ann', 'Barney', ... ]
+			 *			}
+			 *		]
+			 *
+			 * See {@link module:mention/mention~MentionConfig}.
+			 *
+			 * @error markercommand-incorrect-id
+			 */
+			throw new CKEditorError( 'markercommand-incorrect-id: The item id must start with the marker character.' );
 		}
 
 		model.change( writer => {