TrackChangesEditing (track-changes)

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

Properties

• observable

  activeMarkers : Array<string>module:track-changes/trackchangesediting~TrackChangesEditing#activeMarkers

  List of names of active (highlighted) markers.

• adapter : null | TrackChangesAdaptermodule:track-changes/trackchangesediting~TrackChangesEditing#adapter

  Parameters

  adapter : null | TrackChangesAdapter

• readonly inherited

  editor : Editormodule:track-changes/trackchangesediting~TrackChangesEditing#editor

  The editor instance.

  Note that most editors implement the ui property. However, editors with an external UI (i.e. Bootstrap-based) or a headless editor may not have this property or throw an error when accessing it.

  Because of above, to make plugins more universal, it is recommended to split features into:

  • The "editing" part that uses the Editor class without ui property.
  • The "UI" part that uses the Editor class and accesses ui property.

• inherited observable

  isEnabled : booleanmodule:track-changes/trackchangesediting~TrackChangesEditing#isEnabled

  Flag indicating whether a plugin is enabled or disabled. A disabled plugin will not transform text.

  Plugin can be simply disabled like that:

  // Disable the plugin so that no toolbars are visible.
  editor.plugins.get( 'TextTransformation' ).isEnabled = false;
  

  You can also use forceDisabled method.

• trackChangesCommand : TrackChangesCommandmodule:track-changes/trackchangesediting~TrackChangesEditing#trackChangesCommand

  Reference to command that turns the track changes mode on and off.

Static properties

• readonly inherited static

  isContextPlugin : falsemodule:track-changes/trackchangesediting~TrackChangesEditing.isContextPlugin

• readonly static

  pluginName : 'TrackChangesEditing'module:track-changes/trackchangesediting~TrackChangesEditing.pluginName

• readonly static

  requires : readonly tuplemodule:track-changes/trackchangesediting~TrackChangesEditing.requires

Methods

• constructor( editor )module:track-changes/trackchangesediting~TrackChangesEditing#constructor

  Parameters

  editor : Editor

• acceptSuggestion( suggestion ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#acceptSuggestion

  Accept all adjacent suggestions.

  Parameters

  suggestion : Suggestion

  Returns

  void

• addSuggestionData( data ) → Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#addSuggestionData

  Adds suggestion data.

  Parameters

  data : SuggestionData

  Returns

  Suggestion

• inherited

  bind( bindProperty1, bindProperty2 ) → DualBindChain<K1, TrackChangesEditing[ K1 ], K2, TrackChangesEditing[ K2 ]>module:track-changes/trackchangesediting~TrackChangesEditing#bind:DUAL_BIND

  Binds observable properties to other objects implementing the Observable interface.

  Read more in the dedicated guide covering the topic of property bindings with some additional examples.

  Consider two objects: a button and an associated command (both Observable).

  A simple property binding could be as follows:

  button.bind( 'isEnabled' ).to( command, 'isEnabled' );
  

  or even shorter:

  button.bind( 'isEnabled' ).to( command );
  

  which works in the following way:

  • button.isEnabled instantly equals command.isEnabled,
  • whenever command.isEnabled changes, button.isEnabled will immediately reflect its value.

  Note: To release the binding, use unbind.

  You can also "rename" the property in the binding by specifying the new name in the to() chain:

  button.bind( 'isEnabled' ).to( command, 'isWorking' );
  

  It is possible to bind more than one property at a time to shorten the code:

  button.bind( 'isEnabled', 'value' ).to( command );
  

  which corresponds to:

  button.bind( 'isEnabled' ).to( command );
  button.bind( 'value' ).to( command );
  

  The binding can include more than one observable, combining multiple data sources in a custom callback:

  button.bind( 'isEnabled' ).to( command, 'isEnabled', ui, 'isVisible',
  	( isCommandEnabled, isUIVisible ) => isCommandEnabled && isUIVisible );
  

  Using a custom callback allows processing the value before passing it to the target property:

  button.bind( 'isEnabled' ).to( command, 'value', value => value === 'heading1' );
  

  It is also possible to bind to the same property in an array of observables. To bind a button to multiple commands (also Observables) so that each and every one of them must be enabled for the button to become enabled, use the following code:

  button.bind( 'isEnabled' ).toMany( [ commandA, commandB, commandC ], 'isEnabled',
  	( isAEnabled, isBEnabled, isCEnabled ) => isAEnabled && isBEnabled && isCEnabled );
  

  Type parameters

  K1

  K2

  Parameters

  bindProperty1 : K1

  Observable property that will be bound to other observable(s).

  bindProperty2 : K2

  Observable property that will be bound to other observable(s).

  Returns

  DualBindChain<K1, TrackChangesEditing[ K1 ], K2, TrackChangesEditing[ K2 ]>

  The bind chain with the to() and toMany() methods.

• inherited

  bind( bindProperties ) → MultiBindChainmodule:track-changes/trackchangesediting~TrackChangesEditing#bind:MANY_BIND

  Binds observable properties to other objects implementing the Observable interface.

  Read more in the dedicated guide covering the topic of property bindings with some additional examples.

  Consider two objects: a button and an associated command (both Observable).

  A simple property binding could be as follows:

  button.bind( 'isEnabled' ).to( command, 'isEnabled' );
  

  or even shorter:

  button.bind( 'isEnabled' ).to( command );
  

  which works in the following way:

  • button.isEnabled instantly equals command.isEnabled,
  • whenever command.isEnabled changes, button.isEnabled will immediately reflect its value.

  Note: To release the binding, use unbind.

  You can also "rename" the property in the binding by specifying the new name in the to() chain:

  button.bind( 'isEnabled' ).to( command, 'isWorking' );
  

  It is possible to bind more than one property at a time to shorten the code:

  button.bind( 'isEnabled', 'value' ).to( command );
  

  which corresponds to:

  button.bind( 'isEnabled' ).to( command );
  button.bind( 'value' ).to( command );
  

  The binding can include more than one observable, combining multiple data sources in a custom callback:

  button.bind( 'isEnabled' ).to( command, 'isEnabled', ui, 'isVisible',
  	( isCommandEnabled, isUIVisible ) => isCommandEnabled && isUIVisible );
  

  Using a custom callback allows processing the value before passing it to the target property:

  button.bind( 'isEnabled' ).to( command, 'value', value => value === 'heading1' );
  

  It is also possible to bind to the same property in an array of observables. To bind a button to multiple commands (also Observables) so that each and every one of them must be enabled for the button to become enabled, use the following code:

  button.bind( 'isEnabled' ).toMany( [ commandA, commandB, commandC ], 'isEnabled',
  	( isAEnabled, isBEnabled, isCEnabled ) => isAEnabled && isBEnabled && isCEnabled );
  

  Parameters

  bindProperties : Array<'off' | 'on' | 'once' | 'listenTo' | 'stopListening' | 'fire' | 'delegate' | 'stopDelegating' | 'set' | 'bind' | 'unbind' | 'decorate' | 'destroy' | 'init' | 'editor' | 'isEnabled' | 'forceDisabled' | 'clearForceDisabled' | 'adapter' | '_adapter' | 'activeMarkers' | '_descriptionFactory' | 'trackChangesCommand' | '_suggestionFactory' | '_isForcedDefaultExecutionBlock' | '_recordAttributeSuggestions' | 'acceptSuggestion' | 'discardSuggestion' | 'getSuggestions' | 'getSuggestion' | 'hasSuggestion' | 'addSuggestionData' | 'enableCommand' | 'forceDefaultExecution' | 'markInsertion' | 'markMultiRangeInsertion' | 'markInlineFormat' | 'markBlockFormat' | 'markMultiRangeBlockFormat' | 'markDeletion' | 'markMultiRangeDeletion' | 'markAttributeChange' | '_registerBlockAttribute' | '_registerInlineAttribute' | '_enableDefaultAttributesIntegration' | '_getAttributeKey' | '_splitMarkerName' | '_findSuggestions' | '_setSuggestionData' | '_isBlockAttribute'>

  Observable properties that will be bound to other observable(s).

  Returns

  MultiBindChain

  The bind chain with the to() and toMany() methods.

• inherited

  bind( bindProperty ) → SingleBindChain<K, TrackChangesEditing[ K ]>module:track-changes/trackchangesediting~TrackChangesEditing#bind:SINGLE_BIND

  Binds observable properties to other objects implementing the Observable interface.

  Read more in the dedicated guide covering the topic of property bindings with some additional examples.

  Consider two objects: a button and an associated command (both Observable).

  A simple property binding could be as follows:

  button.bind( 'isEnabled' ).to( command, 'isEnabled' );
  

  or even shorter:

  button.bind( 'isEnabled' ).to( command );
  

  which works in the following way:

  • button.isEnabled instantly equals command.isEnabled,
  • whenever command.isEnabled changes, button.isEnabled will immediately reflect its value.

  Note: To release the binding, use unbind.

  You can also "rename" the property in the binding by specifying the new name in the to() chain:

  button.bind( 'isEnabled' ).to( command, 'isWorking' );
  

  It is possible to bind more than one property at a time to shorten the code:

  button.bind( 'isEnabled', 'value' ).to( command );
  

  which corresponds to:

  button.bind( 'isEnabled' ).to( command );
  button.bind( 'value' ).to( command );
  

  The binding can include more than one observable, combining multiple data sources in a custom callback:

  button.bind( 'isEnabled' ).to( command, 'isEnabled', ui, 'isVisible',
  	( isCommandEnabled, isUIVisible ) => isCommandEnabled && isUIVisible );
  

  Using a custom callback allows processing the value before passing it to the target property:

  button.bind( 'isEnabled' ).to( command, 'value', value => value === 'heading1' );
  

  It is also possible to bind to the same property in an array of observables. To bind a button to multiple commands (also Observables) so that each and every one of them must be enabled for the button to become enabled, use the following code:

  button.bind( 'isEnabled' ).toMany( [ commandA, commandB, commandC ], 'isEnabled',
  	( isAEnabled, isBEnabled, isCEnabled ) => isAEnabled && isBEnabled && isCEnabled );
  

  Type parameters

  K

  Parameters

  bindProperty : K

  Observable property that will be bound to other observable(s).

  Returns

  SingleBindChain<K, TrackChangesEditing[ K ]>

  The bind chain with the to() and toMany() methods.

• inherited

  clearForceDisabled( id ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#clearForceDisabled

  Clears forced disable previously set through forceDisabled. See forceDisabled.

  Parameters

  id : string

  Unique identifier, equal to the one passed in forceDisabled call.

  Returns

  void

• inherited

  decorate( methodName ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#decorate

  Turns the given methods of this object into event-based ones. This means that the new method will fire an event (named after the method) and the original action will be plugged as a listener to that event.

  Read more in the dedicated guide covering the topic of decorating methods with some additional examples.

  Decorating the method does not change its behavior (it only adds an event), but it allows to modify it later on by listening to the method's event.

  For example, to cancel the method execution the event can be stopped:

  class Foo extends ObservableMixin() {
  	constructor() {
  		super();
  		this.decorate( 'method' );
  	}
  
  	method() {
  		console.log( 'called!' );
  	}
  }
  
  const foo = new Foo();
  foo.on( 'method', ( evt ) => {
  	evt.stop();
  }, { priority: 'high' } );
  
  foo.method(); // Nothing is logged.
  

  Note: The high priority listener has been used to execute this particular callback before the one which calls the original method (which uses the "normal" priority).

  It is also possible to change the returned value:

  foo.on( 'method', ( evt ) => {
  	evt.return = 'Foo!';
  } );
  
  foo.method(); // -> 'Foo'
  

  Finally, it is possible to access and modify the arguments the method is called with:

  method( a, b ) {
  	console.log( `${ a }, ${ b }`  );
  }
  
  // ...
  
  foo.on( 'method', ( evt, args ) => {
  	args[ 0 ] = 3;
  
  	console.log( args[ 1 ] ); // -> 2
  }, { priority: 'high' } );
  
  foo.method( 1, 2 ); // -> '3, 2'
  

  Parameters

  methodName : 'off' | 'on' | 'once' | 'listenTo' | 'stopListening' | 'fire' | 'delegate' | 'stopDelegating' | 'set' | 'bind' | 'unbind' | 'decorate' | 'destroy' | 'init' | 'editor' | 'isEnabled' | 'forceDisabled' | 'clearForceDisabled' | 'adapter' | '_adapter' | 'activeMarkers' | '_descriptionFactory' | 'trackChangesCommand' | '_suggestionFactory' | '_isForcedDefaultExecutionBlock' | '_recordAttributeSuggestions' | 'acceptSuggestion' | 'discardSuggestion' | 'getSuggestions' | 'getSuggestion' | 'hasSuggestion' | 'addSuggestionData' | 'enableCommand' | 'forceDefaultExecution' | 'markInsertion' | 'markMultiRangeInsertion' | 'markInlineFormat' | 'markBlockFormat' | 'markMultiRangeBlockFormat' | 'markDeletion' | 'markMultiRangeDeletion' | 'markAttributeChange' | '_registerBlockAttribute' | '_registerInlineAttribute' | '_enableDefaultAttributesIntegration' | '_getAttributeKey' | '_splitMarkerName' | '_findSuggestions' | '_setSuggestionData' | '_isBlockAttribute'

  Name of the method to decorate.

  Returns

  void

• inherited

  delegate( events ) → EmitterMixinDelegateChainmodule:track-changes/trackchangesediting~TrackChangesEditing#delegate

  Delegates selected events to another Emitter. For instance:

  emitterA.delegate( 'eventX' ).to( emitterB );
  emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
  

  then eventX is delegated (fired by) emitterB and emitterC along with data:

  emitterA.fire( 'eventX', data );
  

  and eventY is delegated (fired by) emitterC along with data:

  emitterA.fire( 'eventY', data );
  

  Parameters

  events : Array<string>

  Event names that will be delegated to another emitter.

  Returns

  EmitterMixinDelegateChain

• inherited

  destroy() → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#destroy

  Destroys the plugin.

  Note: This method is optional. A plugin instance does not need to have it defined.

  Returns

  void

• discardSuggestion( suggestion ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#discardSuggestion

  Discard all adjacent suggestions.

  Parameters

  suggestion : Suggestion

  Returns

  void

• enableCommand( commandName, [ callback ] ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#enableCommand

  Enables command with given commandName in track changes mode.

  When a command gets enabled in track changes mode, its original execute() method is overwritten by provided callback() function. The callback() should provide alternative logic to be executed instead.

  The callback() function is passed one or more parameters:

  • the first parameter is executeCommand(), a function that upon calling will fire the original execute() method,
  • then, all the parameters passed to original execute() call are passed.

  Using those parameters it is possible to call the original command in the callback() (or skip it) and also do something before and/or after that call.

  If callback is not set then the command will work the same both when track changes is on and off.

  See the Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  commandName : string

  [ callback ] : Function

  Returns

  void

• inherited

  fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]module:track-changes/trackchangesediting~TrackChangesEditing#fire

  Fires an event, executing all callbacks registered for it.

  The first parameter passed to callbacks is an EventInfo object, followed by the optional args provided in the fire() method call.

  Type parameters

  TEvent : extends BaseEvent

  The type describing the event. See BaseEvent.

  Parameters

  eventOrInfo : GetNameOrEventInfo<TEvent>

  The name of the event or EventInfo object if event is delegated.

  args : TEvent[ 'args' ]

  Additional arguments to be passed to the callbacks.

  Returns

  GetEventInfo<TEvent>[ 'return' ]

  By default the method returns undefined. However, the return value can be changed by listeners through modification of the evt.return's property (the event info is the first param of every callback).

• forceDefaultExecution( callback ) → unknownmodule:track-changes/trackchangesediting~TrackChangesEditing#forceDefaultExecution

  Temporarily disable track changes to accept or discard a suggestion without intercepting original calls.

  Parameters

  callback : Function

  Returns

  unknown

• inherited

  forceDisabled( id ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#forceDisabled

  Disables the plugin.

  Plugin may be disabled by multiple features or algorithms (at once). When disabling a plugin, unique id should be passed (e.g. feature name). The same identifier should be used when enabling back the plugin. The plugin becomes enabled only after all features enabled it back.

  Disabling and enabling a plugin:

  plugin.isEnabled; // -> true
  plugin.forceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> false
  plugin.clearForceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> true
  

  Plugin disabled by multiple features:

  plugin.forceDisabled( 'MyFeature' );
  plugin.forceDisabled( 'OtherFeature' );
  plugin.clearForceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> false
  plugin.clearForceDisabled( 'OtherFeature' );
  plugin.isEnabled; // -> true
  

  Multiple disabling with the same identifier is redundant:

  plugin.forceDisabled( 'MyFeature' );
  plugin.forceDisabled( 'MyFeature' );
  plugin.clearForceDisabled( 'MyFeature' );
  plugin.isEnabled; // -> true
  

  Note: some plugins or algorithms may have more complex logic when it comes to enabling or disabling certain plugins, so the plugin might be still disabled after clearForceDisabled was used.

  Parameters

  id : string

  Unique identifier for disabling. Use the same id when enabling back the plugin.

  Returns

  void

• getSuggestion( id ) → Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#getSuggestion

  Returns suggestion for given id.

  Parameters

  id : string

  Returns

  Suggestion

• getSuggestions( options = { [options.skipNotAttached], options.toJSON } ) → Array<SuggestionJSON>module:track-changes/trackchangesediting~TrackChangesEditing#getSuggestions

  Returns the list of all Suggestion instances existing in the editor.

  Parameters

  options : object

  Properties

  [ options.skipNotAttached ] : boolean

  options.toJSON : true

  Returns

  Array<SuggestionJSON>

• getSuggestions( options = { [options.skipNotAttached], options.toJSON } ) → Array<Suggestion> | Array<SuggestionJSON>module:track-changes/trackchangesediting~TrackChangesEditing#getSuggestions

  Returns the list of all Suggestion instances existing in the editor.

  Parameters

  options : object

  Properties

  [ options.skipNotAttached ] : boolean

  options.toJSON : boolean

  Returns

  Array<Suggestion> | Array<SuggestionJSON>

• getSuggestions( [ options ] = { [options.skipNotAttached], [options.toJSON] } ) → Array<Suggestion>module:track-changes/trackchangesediting~TrackChangesEditing#getSuggestions

  Returns the list of all Suggestion instances existing in the editor.

  Parameters

  [ options ] : object

  Properties

  [ options.skipNotAttached ] : boolean

  [ options.toJSON ] : false

  Returns

  Array<Suggestion>

• hasSuggestion( id ) → booleanmodule:track-changes/trackchangesediting~TrackChangesEditing#hasSuggestion

  Checks if suggestion of given id exist.

  Parameters

  id : string

  Returns

  boolean

• init() → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#init

  Returns

  void

• inherited

  listenTo( emitter, event, callback, [ options ] ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#listenTo:BASE_EMITTER

  Registers a callback function to be executed when an event is fired in a specific (emitter) object.

  Events can be grouped in namespaces using :. When namespaced event is fired, it additionally fires all callbacks for that namespace.

  // myEmitter.on( ... ) is a shorthand for myEmitter.listenTo( myEmitter, ... ).
  myEmitter.on( 'myGroup', genericCallback );
  myEmitter.on( 'myGroup:myEvent', specificCallback );
  
  // genericCallback is fired.
  myEmitter.fire( 'myGroup' );
  // both genericCallback and specificCallback are fired.
  myEmitter.fire( 'myGroup:myEvent' );
  // genericCallback is fired even though there are no callbacks for "foo".
  myEmitter.fire( 'myGroup:foo' );
  

  An event callback can stop the event and set the return value of the fire method.

  Type parameters

  TEvent : extends BaseEvent

  The type describing the event. See BaseEvent.

  Parameters

  emitter : Emitter

  The object that fires the event.

  event : TEvent[ 'name' ]

  The name of the event.

  callback : GetCallback<TEvent>

  The function to be called on event.

  [ options ] : GetCallbackOptions<TEvent>

  Additional options.

  Returns

  void

• markAttributeChange( range, key, oldValue, newValue, attributes = { attributes.groupId, attributes[key: string] } ) → Array<Suggestion>module:track-changes/trackchangesediting~TrackChangesEditing#markAttributeChange

  Marks a single-range attribute suggestion on the given range.

  Note: all nodes in the given range must have the same current value of key attribute.

  Note: if a block attribute is marked, range should include only a single model element.

  attributes is a required value and must include groupId: string property. The group id is used to group attribute suggestions together. All suggestions with the same groupId will be put into one suggestion chain. By default, all attribute suggestions created during the same batch have the same groupId.

  It's possible that more than one suggestion will be created by this method if there are already suggestions with the same key but a different oldValue intersecting with the given range.

  It is guaranteed that there will be no "conflicting" suggestions, that is, there will be no two intersecting suggestions for the same attribute key. If there is a conflicting suggestion, it will be partially or fully replaced by a new suggestion.

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  See Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  range : Range

  Range for which the attribute has changed.

  key : string

  Key of the attribute that changed.

  oldValue : unknown

  Previous value of the attribute.

  newValue : unknown

  New value of the attribute.

  attributes : object

  Suggestion attributes. Must include groupId.

  Properties

  attributes.groupId : string

  attributes[key: string] : any

  Returns

  Array<Suggestion>

• markBlockFormat( elementOrRange, formatData, affectedElements, subType, attributes ) → null | Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#markBlockFormat

  Marks a block format suggestion on the given range.

  Block format suggestions are directly coupled with editor commands and represent a command execution on the given range or element.

  This type of format suggestion is suitable for formatting (attribute) changes on block elements. Changes like resizing image, applying block quote or changing header type use this type of format suggestion.

  Pass element if the suggestion should be marked exactly on that element. This is suitable if the command modifies exactly given element (for example, changes an attribute of that element). If such element is split, an additional suggestion is created for the new element:

  	[<paragraph>Foobar]</paragraph>  -->  [<paragraph>Foo]</paragraph>[<paragraph>bar]</paragraph>
  

  Pass range for suggestions representing commands that can be executed on multiple blocks at once. This is suitable for commands which modifies all the block elements found in given range (those commands usually operate on selection ranges). This creates only one suggestion for the whole range and do not create additional suggestions if blocks in the range are split:

  	[<paragraph>Foobar]</paragraph>  -->  [<paragraph>Foo</paragraph><paragraph>Bar]</paragraph>
  

  Example of marking block format suggestion on an element:

  trackChangesPlugin.markBlockFormat( paragraphElement, {
  		commandName: 'heading',
  		commandParams: [ { value: 'heading1' } ],
  		formatGroupId: 'blockName'
  	} );
  

  Example of marking block format suggestion on a range:

  plugin.markBlockFormat( selectionRange, {
  		commandName: 'blockQuote',
  		commandParams: [ { forceValue: true } ]
  } );
  

  If you pass a range, it should start before the first element to change and end:

  • for blocks (like paragraph, list item, heading, etc.): at the end of the last element to change,
  • for objects (like image, table, media embed, etc.): after the last element to change.

  [<paragraph>Foo</paragraph><paragraph>Bar]</paragraph><paragraph>Xyz</paragraph>
  [<paragraph>Foo</paragraph><imageBlock src="foo.jpg"></imageBlock>]<paragraph>Xyz</paragraph>
  

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  When a format suggestion is accepted the command is executed based on parameters passed in formatData.

  If a block format suggestion is marked inside the local user's insertion suggestion, the change is applied directly and no suggestion is created. Note that this does not support partial intersections with insertion suggestions (as opposed to inline format suggestions).

  If possible, the new suggestion will be joined with an existing suggestion (of the same type). This happens only if the suggestions are created by the same user and have similar attributes (i.e. passed attributes do not conflict with the existing suggestion).

  See the Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  elementOrRange : Element | Range

  Element or range on which the change happened.

  formatData : FormatData

  Command parameters and additional suggestion parameters.

  affectedElements : Array<Element>

  Elements (other than elementOrRange) that are also affected by the command execution. This parameter is used when the effect of the command execution is larger than elementOrRange. It is used when determining whether the change should be applied directly or if the suggestion should be created.

  Defaults to []

  subType : null | string

  Suggestion subType to set. If not set (which is the default and recommended use) the sub type value is a string hash generated from formatData. This guarantees that all block format suggestions that perform the same changes have the same sub types (and can be properly handled).

  Defaults to null

  attributes : Record<string, unknown>

  Custom suggestion attributes.

  Defaults to {}

  Returns

  null | Suggestion

• markDeletion( range, subType, attributes ) → null | Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#markDeletion

  Marks a single-range deletion suggestion on given range.

  If the range to mark intersects with or contains insertion suggestions created by the local user, those suggestions may be removed in a part or in the whole together with their content.

  trackChangesPlugin.markDeletion( deletedRange );
  trackChangesPlugin.markDeletion( deletedRange, 'customDeletion' );
  

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  If possible, the new suggestion will be joined with an existing suggestion (of the same type). This happens only if the suggestions are created by the same user and have similar attributes (i.e. passed attributes do not conflict with the existing suggestion).

  See Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  range : Range

  Range which should be marked as deletion suggestion.

  subType : null | string

  Suggestion subType to set. If not set, suggestion will be a generic insertion suggestion. Only suggestions with the same sub type will be joined.

  Defaults to null

  attributes : Record<string, unknown>

  Custom suggestion attributes.

  Defaults to {}

  Returns

  null | Suggestion

  Suggestion created or expanded as a result of execution of this method. Returns null if given range was collapsed or the deletion was in insertion (so no suggestion was created or expanded).

• markInlineFormat( range, formatData, subType, attributes ) → nullmodule:track-changes/trackchangesediting~TrackChangesEditing#markInlineFormat

  Marks an inline format suggestion on the given range.

  This type of format suggestion is suitable for formatting (attribute) changes on inline elements and text. Changes like adding bold or setting a link use this type of format suggestion.

  Inline format suggestions are directly coupled with editor commands and represent a command execution on given range.

  trackChangesPlugin.markInlineFormat( formattedRange, {
  		commandName: 'bold',
  		commandParams: [ { forceValue: true } ]
  } );
  
  trackChangesPlugin.markInlineFormat( formattedRange, formatData, 'customSubType' );
  

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  When a format suggestion is accepted the command is executed based on parameters passed in formatData.

  If an inline format suggestion is marked inside the local user's insertion suggestion, the change is applied directly and no suggestion is created. This supports partial intersections with insertion suggestions.

  If possible, the new suggestion will be joined with an existing suggestion (of the same type). This happens only if the suggestions are created by the same user and have similar attributes (i.e. passed attributes do not conflict with the existing suggestion).

  See the Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  range : Range

  Range on which the change happened.

  formatData : FormatData

  Command parameters.

  subType : null | string

  Suggestion subType to set. If not set (which is the default and recommended use) the sub type value is a string hash generated from formatData. This guarantees that all inline format suggestions that perform the same changes have the same sub type (and can be properly handled).

  Defaults to null

  attributes : Record<string, unknown>

  Custom suggestion attributes.

  Defaults to {}

  Returns

  null

• markInsertion( range, subType, attributes ) → null | Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#markInsertion

  Marks a single-range insertion suggestion on the given range.

  It is expected that given range is a range on just-created content and does not intersect with any other suggestion ranges.

  trackChangesPlugin.markInsertion( insertionRange );
  trackChangesPlugin.markInsertion( insertionRange, 'customInsertion' );
  

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  If possible, the new suggestion will be joined with an existing suggestion (of the same type). This happens only if the suggestions are created by the same user and have similar attributes (i.e. passed attributes do not conflict with the existing suggestion).

  See Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  range : Range

  Range on content which got inserted.

  subType : null | string

  Suggestion subType to set. If not set, suggestion will be a generic insertion suggestion. Only suggestions with the same sub type will be joined.

  Defaults to null

  attributes : Record<string, unknown>

  Custom suggestion attributes.

  Defaults to {}

  Returns

  null | Suggestion

  Suggestion created or expanded as a result of execution of this method. Returns null if given range was collapsed (so no suggestion was created or expanded).

• markMultiRangeBlockFormat( elementsOrRanges, formatData, affectedElements, subType, attributes ) → null | Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#markMultiRangeBlockFormat

  Marks a multi-range block format suggestion on given elements.

  See TrackChangesEditing#markBlockFormat() to learn more about block format suggestions. Note that this method can be used only on elements (not on ranges).

  This method is useful for creating a format suggestion on multiple elements which are not siblings, so one range cannot be used.

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  When a format suggestion is accepted the command is executed based on parameters passed in formatData.

  If a block format suggestion is marked inside the local user's insertion suggestion, the change is applied directly and no suggestion is created. Note that this does not support partial intersections with insertion suggestions (as opposed to inline format suggestions).

  If possible, the new suggestion will be joined with an existing suggestion (of the same type). This happens only if the suggestions are created by the same user and have similar attributes (i.e. passed attributes do not conflict with the existing suggestion).

  See the Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  elementsOrRanges : Array<Range> | Array<Element>

  Elements or ranges on which the change happened.

  formatData : FormatData

  Command parameters and additional suggestion parameters.

  affectedElements : Array<Element>

  Elements (other than elementOrRange) that are also affected by the command execution. This parameter is used when the effect of the command execution is larger than elementOrRange. It is used when determining whether the change should be applied directly or if the suggestion should be created.

  Defaults to []

  subType : null | string

  Suggestion subType to set. If not set (which is the default and recommended use) the sub type value is a string hash generated from formatData. This guarantees that all block format suggestions that perform the same changes have the same sub types (and can be properly handled).

  Defaults to null

  attributes : Record<string, unknown>

  Custom suggestion attributes.

  Defaults to {}

  Returns

  null | Suggestion

• markMultiRangeDeletion( ranges, subType, attributes ) → null | Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#markMultiRangeDeletion

  Marks a multi-range deletion suggestion spanning over given ranges.

  Each range of a multi-range deletion suggestion should contain exactly one element and should not be created on a text content.

  If the ranges to mark contain or are contained in insertion suggestions created by the local user, those insertion suggestions may be removed together with their content.

  trackChangesPlugin.markMultiRangeDeletion( deletedRanges );
  trackChangesPlugin.markMultiRangeDeletion( deletedRanges, 'customDeletion' );
  

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  If possible, the new suggestion will be joined with an existing suggestion (of the same type). This happens only if the suggestions are created by the same user and have similar attributes (i.e. passed attributes do not conflict with the existing suggestion).

  See the Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  ranges : Array<Range>

  Ranges which should be marked as deletion suggestion.

  subType : string

  Suggestion subType to set. Only suggestions with the same sub type will be joined.

  Defaults to 'multi'

  attributes : Record<string, unknown>

  Custom suggestion attributes.

  Defaults to {}

  Returns

  null | Suggestion

  Suggestion created or expanded as a result of execution of this method.

• markMultiRangeInsertion( ranges, subType, attributes ) → Suggestionmodule:track-changes/trackchangesediting~TrackChangesEditing#markMultiRangeInsertion

  Marks a multi-range insertion suggestion spanning over given ranges.

  It is expected that given ranges are ranges on just-created content and do not intersect with any other suggestion ranges.

  Each range of a multi-range insertion suggestion should contain exactly one element and should not be created on a text content.

  trackChangesPlugin.markMultiRangeInsertion( insertionRanges );
  trackChangesPlugin.markMultiRangeInsertion( insertionRanges, 'customInsertion' );
  

  This method should be used in callback() in TrackChangesEditing#enableCommand to inform the track changes plugin about a suggestion that happened.

  Always call this method inside model.change() or model.enqueueChange() block to ensure that all operations performed by this method are bound with one undo step.

  If possible, the new suggestion will be joined with an existing suggestion (of the same type). This happens only if the suggestions are created by the same user and have similar attributes (i.e. passed attributes do not conflict with the existing suggestion).

  See the Integrating track changes with custom features guide to learn more about enabling your feature in the suggestion mode.

  Parameters

  ranges : Array<Range>

  Ranges which got inserted.

  subType : string

  Suggestion subType to set. Only suggestions with the same subtype will be joined.

  Defaults to 'multi'

  attributes : Record<string, unknown>

  Custom suggestion attributes.

  Defaults to {}

  Returns

  Suggestion

  Suggestion created or expanded as a result of execution of this method.

• inherited

  off( event, callback ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#off

  Stops executing the callback on the given event. Shorthand for this.stopListening( this, event, callback ).

  Parameters

  event : string

  The name of the event.

  callback : Function

  The function to stop being called.

  Returns

  void

• inherited

  on( event, callback, [ options ] ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#on

  Registers a callback function to be executed when an event is fired.

  Shorthand for this.listenTo( this, event, callback, options ) (it makes the emitter listen on itself).

  Type parameters

  TEvent : extends BaseEvent

  The type descibing the event. See BaseEvent.

  Parameters

  event : TEvent[ 'name' ]

  The name of the event.

  callback : GetCallback<TEvent>

  The function to be called on event.

  [ options ] : GetCallbackOptions<TEvent>

  Additional options.

  Returns

  void

• inherited

  once( event, callback, [ options ] ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#once

  Registers a callback function to be executed on the next time the event is fired only. This is similar to calling on followed by off in the callback.

  Type parameters

  TEvent : extends BaseEvent

  The type descibing the event. See BaseEvent.

  Parameters

  event : TEvent[ 'name' ]

  The name of the event.

  callback : GetCallback<TEvent>

  The function to be called on event.

  [ options ] : GetCallbackOptions<TEvent>

  Additional options.

  Returns

  void

• inherited

  set( values ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#set:OBJECT

  Creates and sets the value of an observable properties of this object. Such a property becomes a part of the state and is observable.

  It accepts a single object literal containing key/value pairs with properties to be set.

  This method throws the observable-set-cannot-override error if the observable instance already has a property with the given property name. This prevents from mistakenly overriding existing properties and methods, but means that foo.set( 'bar', 1 ) may be slightly slower than foo.bar = 1.

  In TypeScript, those properties should be declared in class using declare keyword. In example:

  public declare myProp1: number;
  public declare myProp2: string;
  
  constructor() {
  	this.set( {
  		'myProp1: 2,
  		'myProp2: 'foo'
  	} );
  }
  

  Parameters

  values : object

  An object with name=>value pairs.

  Returns

  void

• inherited

  set( name, value ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#set:KEY_VALUE

  Creates and sets the value of an observable property of this object. Such a property becomes a part of the state and is observable.

  This method throws the observable-set-cannot-override error if the observable instance already has a property with the given property name. This prevents from mistakenly overriding existing properties and methods, but means that foo.set( 'bar', 1 ) may be slightly slower than foo.bar = 1.

  In TypeScript, those properties should be declared in class using declare keyword. In example:

  public declare myProp: number;
  
  constructor() {
  	this.set( 'myProp', 2 );
  }
  

  Type parameters

  K

  Parameters

  name : K

  The property's name.

  value : TrackChangesEditing[ K ]

  The property's value.

  Returns

  void

• inherited

  stopDelegating( [ event ], [ emitter ] ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#stopDelegating

  Stops delegating events. It can be used at different levels:

  • To stop delegating all events.
  • To stop delegating a specific event to all emitters.
  • To stop delegating a specific event to a specific emitter.

  Parameters

  [ event ] : string

  The name of the event to stop delegating. If omitted, stops it all delegations.

  [ emitter ] : Emitter

  (requires event) The object to stop delegating a particular event to. If omitted, stops delegation of event to all emitters.

  Returns

  void

• inherited

  stopListening( [ emitter ], [ event ], [ callback ] ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#stopListening:BASE_STOP

  Stops listening for events. It can be used at different levels:

  • To stop listening to a specific callback.
  • To stop listening to a specific event.
  • To stop listening to all events fired by a specific object.
  • To stop listening to all events fired by all objects.

  Parameters

  [ emitter ] : Emitter

  The object to stop listening to. If omitted, stops it for all objects.

  [ event ] : string

  (Requires the emitter) The name of the event to stop listening to. If omitted, stops it for all events from emitter.

  [ callback ] : Function

  (Requires the event) The function to be removed from the call list for the given event.

  Returns

  void

• inherited

  unbind( unbindProperties ) → voidmodule:track-changes/trackchangesediting~TrackChangesEditing#unbind

  Removes the binding created with bind.

  // Removes the binding for the 'a' property.
  A.unbind( 'a' );
  
  // Removes bindings for all properties.
  A.unbind();
  

  Parameters

  unbindProperties : Array<'off' | 'on' | 'once' | 'listenTo' | 'stopListening' | 'fire' | 'delegate' | 'stopDelegating' | 'set' | 'bind' | 'unbind' | 'decorate' | 'destroy' | 'init' | 'editor' | 'isEnabled' | 'forceDisabled' | 'clearForceDisabled' | 'adapter' | '_adapter' | 'activeMarkers' | '_descriptionFactory' | 'trackChangesCommand' | '_suggestionFactory' | '_isForcedDefaultExecutionBlock' | '_recordAttributeSuggestions' | 'acceptSuggestion' | 'discardSuggestion' | 'getSuggestions' | 'getSuggestion' | 'hasSuggestion' | 'addSuggestionData' | 'enableCommand' | 'forceDefaultExecution' | 'markInsertion' | 'markMultiRangeInsertion' | 'markInlineFormat' | 'markBlockFormat' | 'markMultiRangeBlockFormat' | 'markDeletion' | 'markMultiRangeDeletion' | 'markAttributeChange' | '_registerBlockAttribute' | '_registerInlineAttribute' | '_enableDefaultAttributesIntegration' | '_getAttributeKey' | '_splitMarkerName' | '_findSuggestions' | '_setSuggestionData' | '_isBlockAttribute'>

  Observable properties to be unbound. All the bindings will be released if no properties are provided.

  Returns

  void

Events

• change:activeMarkers( eventInfo, name, value, oldValue )module:track-changes/trackchangesediting~TrackChangesEditing#event:change:activeMarkers

  Fired when the activeMarkers property changed value.

  Parameters

  eventInfo : EventInfo

  An object containing information about the fired event.

  name : string

  Name of the changed property (activeMarkers).

  value : Array<string>

  New value of the activeMarkers property with given key or null, if operation should remove property.

  oldValue : Array<string>

  Old value of the activeMarkers property with given key or null, if property was not set before.

• inherited

  change:isEnabled( eventInfo, name, value, oldValue )module:track-changes/trackchangesediting~TrackChangesEditing#event:change:isEnabled

  Fired when the isEnabled property changed value.

  Parameters

  eventInfo : EventInfo

  An object containing information about the fired event.

  name : string

  Name of the changed property (isEnabled).

  value : boolean

  New value of the isEnabled property with given key or null, if operation should remove property.

  oldValue : boolean

  Old value of the isEnabled property with given key or null, if property was not set before.

• inherited

  change:{property}( eventInfo, name, value, oldValue )module:track-changes/trackchangesediting~TrackChangesEditing#event:change:{property}

  Fired when a property changed value.

  observable.set( 'prop', 1 );
  
  observable.on<ObservableChangeEvent<number>>( 'change:prop', ( evt, propertyName, newValue, oldValue ) => {
  	console.log( `${ propertyName } has changed from ${ oldValue } to ${ newValue }` );
  } );
  
  observable.prop = 2; // -> 'prop has changed from 1 to 2'
  

  Parameters

  eventInfo : EventInfo

  An object containing information about the fired event.

  name : string

  The property name.

  value : TValue

  The new property value.

  oldValue : TValue

  The previous property value.

• set:activeMarkers( eventInfo, name, value, oldValue )module:track-changes/trackchangesediting~TrackChangesEditing#event:set:activeMarkers

  Fired when the activeMarkers property is going to be set but is not set yet (before the change event is fired).

  Parameters

  eventInfo : EventInfo

  An object containing information about the fired event.

  name : string

  Name of the changed property (activeMarkers).

  value : Array<string>

  New value of the activeMarkers property with given key or null, if operation should remove property.

  oldValue : Array<string>

  Old value of the activeMarkers property with given key or null, if property was not set before.

• inherited

  set:isEnabled( eventInfo, name, value, oldValue )module:track-changes/trackchangesediting~TrackChangesEditing#event:set:isEnabled

  Fired when the isEnabled property is going to be set but is not set yet (before the change event is fired).

  Parameters

  eventInfo : EventInfo

  An object containing information about the fired event.

  name : string

  Name of the changed property (isEnabled).

  value : boolean

  New value of the isEnabled property with given key or null, if operation should remove property.

  oldValue : boolean

  Old value of the isEnabled property with given key or null, if property was not set before.

• inherited

  set:{property}( eventInfo, name, value, oldValue )module:track-changes/trackchangesediting~TrackChangesEditing#event:set:{property}

  Fired when a property value is going to be set but is not set yet (before the change event is fired).

  You can control the final value of the property by using the event's return property.

  observable.set( 'prop', 1 );
  
  observable.on<ObservableSetEvent<number>>( 'set:prop', ( evt, propertyName, newValue, oldValue ) => {
  	console.log( `Value is going to be changed from ${ oldValue } to ${ newValue }` );
  	console.log( `Current property value is ${ observable[ propertyName ] }` );
  
  	// Let's override the value.
  	evt.return = 3;
  } );
  
  observable.on<ObservableChangeEvent<number>>( 'change:prop', ( evt, propertyName, newValue, oldValue ) => {
  	console.log( `Value has changed from ${ oldValue } to ${ newValue }` );
  } );
  
  observable.prop = 2; // -> 'Value is going to be changed from 1 to 2'
                       // -> 'Current property value is 1'
                       // -> 'Value has changed from 1 to 3'
  

  Note: The event is fired even when the new value is the same as the old value.

  Parameters

  eventInfo : EventInfo

  An object containing information about the fired event.

  name : string

  The property name.

  value : TValue

  The new property value.

  oldValue : TValue

  The previous property value.