SuggestionDescriptionFactory (track-changes)
@ckeditor/ckeditor5-track-changes/src/suggestiondescriptionfactory
Creates descriptions for suggestions and suggestions chains.
The class manages everything related to generating descriptions for suggestions. Here, you register labels for elements, attributes, or custom callback for non-regular cases.
One or more suggestions that are grouped together (based ond various conditions) create "suggestion chain". In such chain one suggestion may impact other suggestion when it comes to the description of the whole chain. For example, insertion next to deletion results in "Replaced" description.
Filtering
Methods
-
constructor( schema, locale )
module:track-changes/suggestiondescriptionfactory~SuggestionDescriptionFactory#constructor
-
getDescriptions( suggestions ) → Array<Description>
module:track-changes/suggestiondescriptionfactory~SuggestionDescriptionFactory#getDescriptions
Returns descriptions for given suggestion chain.
The structure of the descriptions array is as follows (explained on an example):
[ { type: 'insertion', content: '*Insert:* 2 paragraphs' }, { type: 'insertion', content: '*Insert:* image }, { type: 'replace', content: '*Replace:* "Foo" *with* "Bar"' } ]
In above example there are three description instances (or lines). Two new (empty) paragraphs were added, an image was added and then "Foo" text was removed and "Bar" text was added. For example, above structure could be rendered as:
<p><strong>Insert:</strong> 2 paragraphs</p> <p><strong>Insert:</strong> image</p> <p><strong>Replace:</strong> "Foo" <strong>with</strong> "Bar"</p>
Parameters
suggestions : Array<Suggestion>
Returns
Array<Description>
-
getItemLabel( element, quantity ) → string
module:track-changes/suggestiondescriptionfactory~SuggestionDescriptionFactory#getItemLabel
Returns label registered for given element or the element name if there is no label registered for it.
Parameters
element : Element
quantity : number
-
Defaults to
1
Returns
string
-
registerAttributeLabel( attributeName, attributeLabel ) → void
module:track-changes/suggestiondescriptionfactory~SuggestionDescriptionFactory#registerAttributeLabel
For given
attributeName
registers how this attribute will be labeled in a description (for example when it is added or removed).Example usage with internationalization:
const t = editor.locale.t; // Remember that you have to use function named `t`. suggestionDescriptionFactory.registerAttributeLabel( 'bold', t( 'bold' ) );
Parameters
attributeName : string
attributeLabel : string
Returns
void
-
registerDescriptionCallback( callback ) → void
module:track-changes/suggestiondescriptionfactory~SuggestionDescriptionFactory#registerDescriptionCallback
Registers a callback function that returns a custom description for a suggestion.
Registered callback is fired for a suggestion whenever there is a need to generate a description for that suggestion.
The callback takes the suggestion instance as a parameter and should return description object or a falsy value if the suggestion was not handled by the callback.
Example of a description callback for the bold style:
suggestionDescriptionFactory.registerDescriptionCallback( suggestion => { const { data } = suggestion; // Omit suggestions that are not bold style suggestions. if ( !data || data.commandName !== 'bold' ) { return; } const isSet = !!data.commandParams[ 0 ].forceValue; const content = isSet ? '*Set format:* bold' : '*Remove format:* bold'; return { type: 'format', content }; } );
Parameters
callback : DescriptionCallback
Returns
void
-
registerElementLabel( elementNameOrCallback, labelCallback, priority ) → void
module:track-changes/suggestiondescriptionfactory~SuggestionDescriptionFactory#registerElementLabel
For given
elementName
registers how this element will be labeled in a description (for example when it is added or removed).Instead of a string name you may provide a matching function that takes item
Item
as an input and should return boolean value.Provided label callback takes one parameter,
quantity
, and is expected to return the label for the element as a string.A simple use case without using internationalization:
suggestionDescriptionFactory.registerElementLabel( 'paragraph', quantity => quantity == 1 ? 'paragraph' : quantity + ' paragraphs' );
If you want your feature to be localized to other languages, use localization service:
const t = editor.locale.t; // Remember that you have to use function named `t`. suggestionDescriptionFactory.registerElementLabel( 'paragraph', quantity => t( { string: 'paragraph', plural: '%0 paragraphs', id: 'ELEMENT_PARAGRAPH' }, quantity ) );
Parameters
elementNameOrCallback : string | Function
labelCallback : LabelCallback
priority : PriorityString
-
Defaults to
priorities.normal
Returns
void
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.