From 8afe46f308f4db318a62143e2a3f1bf3dc56506d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Maciej=20Go=C5=82aszewski?= Date: Mon, 27 Apr 2020 09:13:18 +0200 Subject: [PATCH] Docs: Add notes about using AttributeElement's priority and id attributes in mentions. --- docs/_snippets/examples/chat-with-mentions.js | 5 +++++ docs/_snippets/features/mention-customization.js | 7 ++++++- docs/examples/chat-with-mentions.md | 5 +++++ docs/features/mentions.md | 16 +++++++++++++++- tests/manual/mention-custom-view.js | 5 ++++- tests/mentionediting.js | 10 ++++++++-- 6 files changed, 43 insertions(+), 5 deletions(-) diff --git a/docs/_snippets/examples/chat-with-mentions.js b/docs/_snippets/examples/chat-with-mentions.js index caaf190..61c7462 100644 --- a/docs/_snippets/examples/chat-with-mentions.js +++ b/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' diff --git a/docs/_snippets/features/mention-customization.js b/docs/_snippets/features/mention-customization.js index ab15a9c..7032330 100644 --- a/docs/_snippets/features/mention-customization.js +++ b/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' diff --git a/docs/examples/chat-with-mentions.md b/docs/examples/chat-with-mentions.md index 51e1eba..80023f1 100644 --- a/docs/examples/chat-with-mentions.md +++ b/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' diff --git a/docs/features/mentions.md b/docs/features/mentions.md index db8bc5c..0dcd5ba 100644 --- a/docs/features/mentions.md +++ b/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' diff --git a/tests/manual/mention-custom-view.js b/tests/manual/mention-custom-view.js index b8048a3..88067a5 100644 --- a/tests/manual/mention-custom-view.js +++ b/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' } ); diff --git a/tests/mentionediting.js b/tests/mentionediting.js index 853bcd8..72e78d7 100644 --- a/tests/mentionediting.js +++ b/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' } );