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'
  } );