Docs: Add notes about using AttributeElement's priority and id attributes in mentions

docs/_snippets/examples/chat-with-mentions.js

@@ -146,6 +146,11 @@ function MentionLinks( editor ) {
 				class: 'mention',
 				'data-mention': modelAttributeValue.id,
 				href
+			}, {
+				// Make mention attribute to be wrapped by other attribute elements.
+				priority: 20,
+				// Prevent merging mentions together.
+				id: modelAttributeValue._uid
 			} );
 		},
 		converterPriority: 'high'

docs/_snippets/features/mention-customization.js

@@ -52,7 +52,7 @@ function MentionCustomization( editor ) {
 			value: viewItem => {
 				// The mention feature expects that the mention attribute value
 				// in the model is a plain object with a set of additional attributes.
-				// In order to create a proper object, use the toMentionAttribute() helper method:
+				// In order to create a proper object use the toMentionAttribute() helper method:
 				const mentionAttribute = editor.plugins.get( 'Mention' ).toMentionAttribute( viewItem, {
 					// Add any other properties that you need.
 					link: viewItem.getAttribute( 'href' ),
@@ -79,6 +79,11 @@ function MentionCustomization( editor ) {
 				'data-mention': modelAttributeValue.id,
 				'data-user-id': modelAttributeValue.userId,
 				'href': modelAttributeValue.link
+			}, {
+				// Make mention attribute to be wrapped by other attribute elements.
+				priority: 20,
+				// Prevent merging mentions together.
+				id: modelAttributeValue._uid
 			} );
 		},
 		converterPriority: 'high'

docs/examples/chat-with-mentions.md

@@ -327,6 +327,11 @@ function MentionLinks( editor ) {
 				class: 'mention',
 				'data-mention': modelAttributeValue.id,
 				href
+			}, {
+				// Make mention attribute to be wrapped by other attribute elements.
+				priority: 20,
+				// Prevent merging mentions together.
+				id: modelAttributeValue._uid
 			} );
 		},
 		converterPriority: 'high'

docs/features/mentions.md

@@ -180,7 +180,7 @@ A full, working demo with all possible customizations and its source code is ava
 
 ### Customizing the output
 
-In order to change the markup generated by the editor for mentions, you can overwrite the default converter of the mention feature. To do that, you must specify both {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher upcast} and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast} converters.
+In order to change the markup generated by the editor for mentions, you can overwrite the default converter of the mention feature. To do that, you must specify both {@link module:engine/conversion/upcastdispatcher~UpcastDispatcher upcast} and {@link module:engine/conversion/downcastdispatcher~DowncastDispatcher downcast} converters using {@link module:engine/view/attributeelement~AttributeElement}.
 
 The example below defines a plugin that overrides the default output:
 
@@ -196,6 +196,10 @@ To a link:
 
 The converters must be defined with a `'high'` priority to be executed before the {@link features/link link} feature's converter and before the default converter of the mention feature. A mention is stored in the model as a {@link framework/guides/architecture/editing-engine#text-attributes text attribute} that stores an object (see {@link module:mention/mention~MentionFeedItem}).
 
+To control how the mention element is wrapped by other attribute elements (like bold, italic, etc) set its {@link module:engine/view/attributeelement~AttributeElement#priority}. To replicate default plugin behavior and make mention to be wrapped by other elements set priority to `20`.
+
+By default, attribute elements that are next to each other and have the same value will be rendered as single HTML element. To prevent this the model attribute value object expose a unique id of each inserted mention to the model as `_uid`. To prevent merging subsequent mentions set it as {@link module:engine/view/attributeelement~AttributeElement#id}.
+
 **Note:** The feature prevents copying fragments of existing mentions. If only a part of a mention is selected, it will be copied as plain text. The internal converter with the {@link module:engine/conversion/conversion~ConverterDefinition `'highest'` priority} controls this behaviour; thus, we do not recommend adding mention converters with the `'highest'` priority to avoid collisions and quirky results.
 
 ```js
@@ -254,6 +258,11 @@ function MentionCustomization( editor ) {
 				'data-mention': modelAttributeValue.id,
 				'data-user-id': modelAttributeValue.userId,
 				'href': modelAttributeValue.link
+			}, {
+				// Make mention attribute to be wrapped by other attribute elements.
+				priority: 20,
+				// Prevent merging mentions together.
+				id: modelAttributeValue._uid
 			} );
 		},
 		converterPriority: 'high'
@@ -341,6 +350,11 @@ function MentionCustomization( editor ) {
 				'data-mention': modelAttributeValue.id,
 				'data-user-id': modelAttributeValue.userId,
 				'href': modelAttributeValue.link
+			}, {
+				// Make mention attribute to be wrapped by other attribute elements.
+				priority: 20,
+				// Prevent merging mentions together.
+				id: modelAttributeValue._uid
 			} );
 		},
 		converterPriority: 'high'

tests/manual/mention-custom-view.js

@@ -50,7 +50,10 @@ class CustomMentionAttributeView extends Plugin {
 					class: 'mention',
 					'data-mention': modelAttributeValue.id,
 					'href': modelAttributeValue.link
-				}, { id: modelAttributeValue._uid } );
+				}, {
+					priority: 20,
+					id: modelAttributeValue._uid
+				} );
 			},
 			converterPriority: 'high'
 		} );

tests/mentionediting.js

@@ -197,7 +197,10 @@ describe( 'MentionEditing', () => {
 						class: 'mention',
 						'data-mention': modelAttributeValue.id,
 						'href': modelAttributeValue.link
-					}, { id: modelAttributeValue._uid } );
+					}, {
+						priority: 20,
+						id: modelAttributeValue._uid
+					} );
 				},
 				converterPriority: 'high'
 			} );
@@ -677,7 +680,10 @@ function addCustomMentionConverters( editor ) {
 			return viewWriter.createAttributeElement( 'b', {
 				class: 'mention',
 				'data-mention': modelAttributeValue.id
-			}, { id: modelAttributeValue._uid } );
+			}, {
+				priority: 20,
+				id: modelAttributeValue._uid
+			} );
 		},
 		converterPriority: 'high'
 	} );