ProposedChangesCollection

class

A set of proposed changes for one or multiple documents. Keeps and manages these changes' current state.

The changes inside one set are logically related and can be thought as one "review". They are a result of one "processing cycle": one set of changes, all proposed together at once, for one or multiple documents, to be reviewed and accepted or rejected.

The proposed changes are given an index and are addressed by their index in the set. A change never leaves the set, and its index does not change. An accepted or rejected change is still kept in the set at its original index, and can be rendered for preview purposes.

Create the set from the proposed changes, then pass it to create a controller, which binds the set with related editor instance(s) and optionally a view component. Read the set directly, but modify it through the controller API.

The set is owned by the integrator and outlives the controller. It can be passed to a new controller, for example to keep the review when the controller is re-created for a new editor instance. A set must be bound with one controller at a time.

Methods

constructor( changes )
Parameters
changes: Array<DocumentChange & object>
The changes to review, in the order they should be reviewed in. A change may state its decision, to restore a review. Defaults to 'pending'.
Defaults to []
delegate( events ) → EmitterMixinDelegateChain
inherited
module:ai/toolkit/proposedchangescollection~ProposedChangesCollection#delegate
Delegates selected events to another Emitter. For instance:
```
emitterA.delegate( 'eventX' ).to( emitterB );
emitterA.delegate( 'eventX', 'eventY' ).to( emitterC );
```
Copy code
then eventX is delegated (fired by) emitterB and emitterC along with data:
```
emitterA.fire( 'eventX', data );
```
Copy code
and eventY is delegated (fired by) emitterC along with data:
```
emitterA.fire( 'eventY', data );
```
Copy code
Parameters
events: Array<string>
Event names that will be delegated to another emitter.
Returns
EmitterMixinDelegateChain
fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]
inherited
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).
getActionableSibling( index, direction ) → number | null
The position of the nearest actionable change in the given direction, or null when there is none.

It is cyclic: "next" from the last change is the first one. null is returned only once there are no actionable changes in the set.
Parameters
index: number
The index to step away from.
direction: 'next' | 'previous'
Which way to step.
Returns
number | null
getChange( index ) → ProposedChange | undefined
Returns the proposed change at index, or undefined when the set holds none there.
Parameters
index: number
Returns
ProposedChange | undefined
getChanges() → readonly Array<ProposedChange>
Returns the proposed changes.
Returns
readonly Array<ProposedChange>
hasWritableChanges() → boolean
Whether there is any writable ("applicable") change in the collection.
Returns
boolean
isActionable( index ) → boolean
Whether the user can make an action (accept or reject) for the change at index.

Actionable change must be in pending state (not accepted or rejected yet), it must yield actual change, it cannot be outdated (the related content must not be removed), and the related document must be available.

If the change affects a read-only content, it is still actionable. Such a change cannot be accepted, but it can be rejected.

An actionable change that can still be accepted is writeable.
Parameters
index: number
Returns
boolean
isWritable( index ) → boolean
Whether the change at index can be accepted by the user.

It must be actionable and affect content that is not read-only.
Parameters
index: number
Returns
boolean
listenTo( emitter, event, callback, options? ) → void
inherited
module:ai/toolkit/proposedchangescollection~ProposedChangesCollection#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' );
```
Copy code
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
off( event, callback ) → void
inherited
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
on( event, callback, options? ) → void
inherited
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
once( event, callback, options? ) → void
inherited
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
stopDelegating( event?, emitter? ) → void
inherited
module:ai/toolkit/proposedchangescollection~ProposedChangesCollection#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
stopListening( emitter?, event?, callback? ) → void
inherited
module:ai/toolkit/proposedchangescollection~ProposedChangesCollection#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

ProposedChangesCollection

Methods

constructor( changes )

Parameters

delegate( events ) → EmitterMixinDelegateChaininherited

Parameters

Returns

fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]inherited

Type parameters

Parameters

Returns

getActionableSibling( index, direction ) → number | null

Parameters

Returns

getChange( index ) → ProposedChange | undefined

Parameters

Returns

getChanges() → readonly Array<ProposedChange>

Returns

hasWritableChanges() → boolean

Returns

isActionable( index ) → boolean

Parameters

Returns

isWritable( index ) → boolean

Parameters

Returns

listenTo( emitter, event, callback, options? ) → voidinherited

Type parameters

Parameters

Returns

off( event, callback ) → voidinherited

Parameters

Returns

on( event, callback, options? ) → voidinherited

Type parameters

Parameters

Returns

once( event, callback, options? ) → voidinherited

Type parameters

Parameters

Returns

stopDelegating( event?, emitter? ) → voidinherited

Parameters

Returns

stopListening( emitter?, event?, callback? ) → voidinherited

Parameters

Returns

Events

changeUpdated( eventInfo, <anonymous> = { <anonymous>.change, <anonymous>.index } )

Parameters

`constructor( changes )`

`delegate( events ) → EmitterMixinDelegateChain`
inherited

`fire( eventOrInfo, args ) → GetEventInfo<TEvent>[ 'return' ]`
inherited

`getActionableSibling( index, direction ) → number | null`

`getChange( index ) → ProposedChange | undefined`

`getChanges() → readonly Array<ProposedChange>`

`hasWritableChanges() → boolean`

`isActionable( index ) → boolean`

`isWritable( index ) → boolean`

`listenTo( emitter, event, callback, options? ) → void`
inherited

`off( event, callback ) → void`
inherited

`on( event, callback, options? ) → void`
inherited

`once( event, callback, options? ) → void`
inherited

`stopDelegating( event?, emitter? ) → void`
inherited

`stopListening( emitter?, event?, callback? ) → void`
inherited

`changeUpdated( eventInfo, <anonymous> = { <anonymous>.change, <anonymous>.index } )`