8
0
Piotrek Koszuliński 6 лет назад
Родитель
Сommit
e3a7c6c233

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

@@ -20,7 +20,7 @@ ClassicEditor
 			feeds: [
 			feeds: [
 				{
 				{
 					marker: '@',
 					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 ) {
 function getFeedItems( queryText ) {
 	// As an example of an asynchronous action, let's return a promise
 	// As an example of an asynchronous action, let's return a promise
 	// that resolves after a 100ms timeout.
 	// 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 => {
 	return new Promise( resolve => {
 		setTimeout( () => {
 		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 );
 		}, 100 );
 	} );
 	} );
 
 
@@ -120,7 +126,7 @@ function customItemRenderer( item ) {
 	const itemElement = document.createElement( 'span' );
 	const itemElement = document.createElement( 'span' );
 
 
 	itemElement.classList.add( 'custom-item' );
 	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 } `;
 	itemElement.textContent = `${ item.name } `;
 
 
 	const usernameElement = document.createElement( 'span' );
 	const usernameElement = document.createElement( 'span' );

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

@@ -20,7 +20,7 @@ ClassicEditor
 			feeds: [
 			feeds: [
 				{
 				{
 					marker: '@',
 					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: [
 			feeds: [
 				{
 				{
 					marker: '@',
 					marker: '@',
-					feed: [ 'Barney', 'Lily', 'Marshall', 'Robin', 'Ted' ],
+					feed: [ '@Barney', '@Lily', '@Marshall', '@Robin', '@Ted' ],
 					minimumCharacters: 1
 					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.
 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
 ```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 = [
 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 ) {
 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.
 		// Include an item in the search results if name or username includes the current user input.
 		return (
 		return (
 			item.name.toLowerCase().includes( searchString ) ||
 			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' );
 	const itemElement = document.createElement( 'span' );
 
 
 	itemElement.classList.add( 'custom-item' );
 	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 } `;
 	itemElement.textContent = `${ item.name } `;
 
 
 	const usernameElement = document.createElement( 'span' );
 	const usernameElement = document.createElement( 'span' );
 
 
 	usernameElement.classList.add( 'custom-item-username' );
 	usernameElement.classList.add( 'custom-item-username' );
-	usernameElement.textContent = `@${ item.username }`;
+	usernameElement.textContent = item.id;
 
 
 	itemElement.appendChild( usernameElement );
 	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 {
 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' } );
 	 *		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' }
 	 *		// { id: '@joe', userId: '1234', _uid: '7a7bc7...', _text: '@John Doe' }
 	 *
 	 *
 	 * @param {module:engine/view/element~Element} viewElement
 	 * @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}
 	 * @returns {module:mention/mention~MentionAttribute}
 	 */
 	 */
 	toMentionAttribute( viewElement, data ) {
 	toMentionAttribute( viewElement, data ) {
@@ -90,7 +90,7 @@ export default class Mention extends Plugin {
  *					feeds: [
  *					feeds: [
  *						{
  *						{
  *							marker: '@',
  *							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.
  *		// Static configuration.
  *		const mentionFeedPeople = {
  *		const mentionFeedPeople = {
  *			marker: '@',
  *			marker: '@',
- *			feed: [ 'Alice', 'Bob', ... ],
+ *			feed: [ '@Alice', '@Bob', ... ],
  *			minimumCharacters: 2
  *			minimumCharacters: 2
  *		};
  *		};
  *
  *
@@ -180,23 +180,23 @@ export default class Mention extends Plugin {
  *							marker: '@',
  *							marker: '@',
  *							feed: [
  *							feed: [
  *								{
  *								{
- *									id: 'Barney',
+ *									id: '@Barney',
  *									fullName: 'Barney Bloom'
  *									fullName: 'Barney Bloom'
  *								},
  *								},
  *								{
  *								{
- *									id: 'Lily',
+ *									id: '@Lily',
  *									fullName: 'Lily Smith'
  *									fullName: 'Lily Smith'
  *								},
  *								},
  *								{
  *								{
- *									id: 'Marshall',
+ *									id: '@Marshall',
  *									fullName: 'Marshall McDonald'
  *									fullName: 'Marshall McDonald'
  *								},
  *								},
  *								{
  *								{
- *									id: 'Robin',
+ *									id: '@Robin',
  *									fullName: 'Robin Hood'
  *									fullName: 'Robin Hood'
  *								},
  *								},
  *								{
  *								{
- *									id: 'Ted',
+ *									id: '@Ted',
  *									fullName: 'Ted Cruze'
  *									fullName: 'Ted Cruze'
  *								},
  *								},
  *								// ...
  *								// ...
@@ -215,15 +215,17 @@ export default class Mention extends Plugin {
  *			.catch( ... );
  *			.catch( ... );
  *
  *
  * @typedef {Object|String} module:mention/mention~MentionFeedItem
  * @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.
  * @property {String} [text] Text used for display in mention auto-complete suggestions list.
  */
  */
 
 
 /**
 /**
  * Represents mention in the model.
  * Represents mention in the model.
  *
  *
+ * See {@link module:mention/mention~Mention#toMentionAttribute `Mention#toMentionAttribute()`}.
+ *
  * @interface module:mention/mention~MentionAttribute
  * @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
  * @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()}.
  * {@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.
  * @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 );
 		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 => {
 		model.change( writer => {