CKEditor Ecosystem Documentation
Search
Home/CKEditor 5/API
Class

SuggestionDescriptionFactory (track-changes)

@ckeditor/ckeditor5-track-changes/src/suggestiondescriptionfactory

class

Creates descriptions for suggestion chains.

One or more suggestions that are next to each other 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 )

    Creates new SuggestionDescriptionFactory instance.

    Parameters

    schema : Schema
    locale : Locale

  • getDescriptions( suggestions ) → Array.<Description>

    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( name, quantity ) → String

    Returns label registered for given element name or the element name if there is no label registered for it.

    Parameters

    name : String
    quantity : Number

    Defaults to 1

    Returns

    String

  • registerDescriptionCallback( callback )

    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 : function

  • registerElementLabel( elementName, label )

    For given elementName registers how this element will be labeled in a description (for example when it is added or removed).

    Provided function 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

    elementName : String
    label : function