Expand all

ve.dm.Transaction

Constructor

new ve.dm.Transaction([operations], [authorId]) #

Transaction on ve.dm.ElementLinearData, preserving ve.dm.Document tree validity

A transaction represents a mapping on ve.dm.ElementLinearData, from one state (the start state) to another (the end state). The transaction is guaranteed not to break tree validity: if the start state represents a syntactically valid ve.dm.Document tree (without unbalanced tags, bare listItems, bare table cells etc), then the end state tree must be syntactically valid too.

A transaction is comprised of a list of operations, which must preserve tree validity as a whole, though each individual operation may not. For example, a DivNode wrapping can be removed by one operation removing the 'div' and another removing the '/div'. The ve.dm.TransactionBuilder.static.newFrom* methods help build transactions that preserve tree validity.

Parameters:

Name Type Attributes Description
operations Array.<Object> optional

Operations preserving tree validity as a whole; default []
authorId number | null optional

Positive integer author ID; default null
Source:

Transaction on ve.dm.ElementLinearData, preserving ve.dm.Document tree validity

A transaction represents a mapping on ve.dm.ElementLinearData, from one state (the start state) to another (the end state).

Properties

reversers :Object.<string, Object>static #

Specification for how each type of operation should be reversed.

This object maps operation types to objects, which map property names to reversal instructions. A reversal instruction is either a string (which means the value of that property should be used) or an object (which maps old values to new values). For instance, { from: 'to' } means that the .from property of the reversed operation should be set to the .to property of the original operation, and { method: { set: 'clear' } } means that if the .method property of the original operation was 'set', the reversed operation's .method property should be 'clear'.

If a property's treatment isn't specified, its value is simply copied without modification. If an operation type's treatment isn't specified, all properties are copied without modification.

Type:

Source:
Specification for how each type of operation should be reversed.

Methods

adjustRetain(place, diff) #

Adjust (in place) the retain length at the start/end of an operations list

Parameters:

Name Type Description
place string

Where to adjust, start|end
diff number

Adjustment; must not cause negative retain length
Source:
Adjust (in place) the retain length at the start/end of an operations list

clone() → {ve.dm.Transaction} #

Create a clone of this transaction.

The returned transaction will be exactly the same as this one, except that its 'applied' flag will be cleared. This means that if a transaction has already been committed, it will still be possible to commit the clone. This is used for redoing transactions that were undone.

Source:

Returns:

Clone of this transaction

Type
ve.dm.Transaction
Create a clone of this transaction.

getActiveRangeAndLengthDiff() → {ve.dm.Transaction.RangeAndLengthDiff} #

Calculate active range and length change

Source:

Returns:

Active range and length change

Type
ve.dm.Transaction.RangeAndLengthDiff
Calculate active range and length change

getModifiedRange(doc, [options]) → {ve.Range|null} #

Get the range that covers modifications made by this transaction.

In the case of insertions, the range covers content the user intended to insert. It ignores wrappers added by ve.dm.Document#fixUpInsertion.

The returned range is relative to the new state, after the transaction is applied. So for a simple insertion transaction, the range will cover the newly inserted data, and for a simple removal transaction it will be a zero-length range.

Parameters:

Name Type Attributes Description
doc ve.dm.Document

The document in the state to which the transaction applies
options Object optional

Options

Properties:
Name Type Attributes Description
includeInternalList boolean optional

Include changes within the internal list
excludeAnnotations boolean optional

Exclude annotation-only changes
excludeAttributes boolean optional

Exclude attribute changes
Source:

Returns:

Range covering modifications, or null for a no-op transaction

Type
ve.Range | null
Get the range that covers modifications made by this transaction.

getOperations() → {Array.<Object>} #

Get all operations.

Source:

Returns:

List of operations

Type
Array.<Object>
Get all operations.

hasBeenApplied() → {boolean} #

Check whether the transaction has already been applied.

Source:

Returns:

Type
boolean
Check whether the transaction has already been applied.

hasContentDataOperations() → {boolean} #

Check if the transaction has any content data operations, such as insertion or deletion.

Source:

Returns:

Has content data operations

Type
boolean
Check if the transaction has any content data operations, such as insertion or deletion.

hasElementAttributeOperations() → {boolean} #

Check if the transaction has any element attribute operations.

Source:

Returns:

Has element attribute operations

Type
boolean
Check if the transaction has any element attribute operations.

hasOperationWithType(type) → {boolean} #

Check if the transaction has any operations with a certain type.

Parameters:

Name Type Description
type string

Operation type
Source:

Returns:

Has operations of a given type

Type
boolean
Check if the transaction has any operations with a certain type.

insertOperations(offset, operations) #

Insert (in place) operations at the given offset

Merges into existing operations where possible. Offset cannot be in the interior of a replace operation (i.e. the interior of its removed content).

Parameters:

Name Type Description
offset number

The offset at which to insert
operations Array.<Object>

The operations to insert
Source:

Throws:

Offset is in the interior of a replace operation

Type
Error

Insert (in place) operations at the given offset

Merges into existing operations where possible.

isNoOp() → {boolean} #

Check if the transaction would make any actual changes if processed.

There may be more sophisticated checks that can be done, like looking for things being replaced with identical content, but such transactions probably should not be created in the first place.

Source:

Returns:

Transaction is no-op

Type
boolean
Check if the transaction would make any actual changes if processed.

markAsApplied() #

Mark the transaction as having been applied.

Should only be called after committing the transaction.

Source:
See:
Mark the transaction as having been applied.

pushAttributeOp(key, from, to) #

Build an attribute operation

Parameters:

Name Type Description
key string

Name of attribute to change
from any

Value to change attribute from, or undefined if not previously set
to any

Value to change attribute to, or undefined to remove
Source:
Build an attribute operation

pushReplaceOp(remove, insert, [insertedDataOffset], [insertedDataLength]) #

Build a replace operation

The insertedDataOffset and insertedDataLength parameters indicate the intended insertion is wrapped with fixup data to preserve HTML validity. For instance, an intended table cell insertion may have been fixed up by wrapping inside a table row, table section and table.

Parameters:

Name Type Attributes Description
remove Array

Data to remove
insert Array

Data to insert, possibly fixed up
insertedDataOffset number optional

Offset of intended insertion within fixed up data
insertedDataLength number optional

Length of intended insertion within fixed up data
Source:

Build a replace operation

The insertedDataOffset and insertedDataLength parameters indicate the intended insertion is wrapped with fixup data to preserve HTML validity.

pushRetainOp(length) #

Push a retain operation

Parameters:

Name Type Description
length number

Length > 0 of content data to retain
Source:
Push a retain operation

reversed() → {ve.dm.Transaction} #

Create a reversed version of this transaction.

The returned transaction will be the same as this one but with all operations reversed. This means that applying the original transaction and then applying the reversed transaction will result in no net changes. This is used to undo transactions.

Source:

Returns:

Reverse of this transaction

Type
ve.dm.Transaction
Create a reversed version of this transaction.

toJSON([key]) → {Object|Array} #

Serialize the transaction into a JSONable object

Values are not necessarily deep copied

Parameters:

Name Type Attributes Description
key string optional

Key in parent object
Source:

Returns:

JSONable object

Type
Object | Array

Serialize the transaction into a JSONable object

Values are not necessarily deep copied

translateOffset(offset, [excludeInsertion]) → {number} #

Translate an offset based on a transaction.

This is useful when you want to anticipate what an offset will be after a transaction is processed.

Parameters:

Name Type Attributes Description
offset number

Offset in the linear model before the transaction has been processed
excludeInsertion boolean optional

Map the offset immediately before an insertion to right before the insertion rather than right after
Source:

Returns:

Translated offset, as it will be after processing transaction

Type
number
Translate an offset based on a transaction.

translateRange(range, [excludeInsertion]) → {ve.Range} #

Translate a range based on the transaction, with grow/shrink preference at changes

This is useful when you want to anticipate what a selection will be after a transaction is processed.

Parameters:

Name Type Attributes Description
range ve.Range

Range in the linear model before the transaction has been processed
excludeInsertion boolean optional

Do not grow the range to cover insertions on the boundaries of the range.
Source:
See:

Returns:

Translated range, as it will be after processing transaction

Type
ve.Range

Translate a range based on the transaction, with grow/shrink preference at changes

This is useful when you want to anticipate what a selection will be after a transaction is processed.

translateRangeWithAuthor(range, [authorId]) → {ve.Range} #

Translate a range based on the transaction, with bias depending on author ID comparison

Biases backward if !authorId || !this.authorId || authorId <= this.authorId

Parameters:

Name Type Attributes Description
range ve.Range

Range in the linear model before the transaction has been processed
authorId number optional

Author ID of the range
Source:
See:

Returns:

Translated range, as it will be after processing transaction

Type
ve.Range

Translate a range based on the transaction, with bias depending on author ID comparison

Biases backward if !authorId || !this.authorId || authorId <= this.authorId

trySplit(offset) → {number} #

Split (in place) the retain at the given offset, if any

Offset cannot be in the interior of a replace operation (i.e. the interior of its removed content).

Parameters:

Name Type Description
offset number

The offset at which to split
Source:

Returns:

Index in operations starting at offset

Type
number

Throws:

Offset is in the interior of a replace operation

Type
Error

Split (in place) the retain at the given offset, if any

Offset cannot be in the interior of a replace operation (i.e.

tryUnsplit(index) #

Unsplit (in place) the two operations around the given index, if possible

Parameters:

Name Type Description
index number

The index at which to unsplit
Source:
Unsplit (in place) the two operations around the given index, if possible

compareElementsForTranslate(a, b) → {boolean}static #

Simpified comparison of linear data elements

Identical to ve.dm.ElementLinearData.static.compareElementsUnannotated, but without the complex comparison of node elements that requires the model registry.

For the purposes of translateOffset it is just sufficient that we catch obvious cases of annotations being set/clear.

Parameters:

Name Type Description
a Object | Array | string

First element
b Object | Array | string

Second element
Source:

Returns:

Elements are comparable

Type
boolean

Simpified comparison of linear data elements

Identical to ve.dm.ElementLinearData.static.compareElementsUnannotated, but without the complex comparison of node elements that requires the model registry.

deserialize(data) → {ve.dm.Transaction}static #

Deserialize a transaction from a JSONable object

Values are either new or deep copied, so there is no reference into the serialized structure

Parameters:

Name Type Description
data Object | Array

Transaction serialized as a JSONable object
Source:

Returns:

Deserialized transaction

Type
ve.dm.Transaction

Deserialize a transaction from a JSONable object

Values are either new or deep copied, so there is no reference into the serialized structure

isAnnotationOnlyOperation(op) → {boolean}static #

Check if an operation only changes annotations

Parameters:

Name Type Description
op Object

Operation object
Source:

Returns:

Operation is annotation-only

Type
boolean
Check if an operation only changes annotations

Type Definitions

RangeAndLengthDiff #

Type:

Properties:

Name Type Attributes Description
start number optional

Start offset of the active range
end number optional

End offset of the active range
startOpIndex number optional

Start operation index of the active range
endOpIndex number optional

End operation index of the active range
diff number

Length change the transaction causes
Source: