Expand all

ve.dm.ElementLinearData

Extends

Constructor

new ve.dm.ElementLinearData(store, [data]) #

Element linear data storage

Parameters:

Name Type Attributes Description
store ve.dm.HashValueStore

Hash-value store
data Array optional

Linear data
Source:
Element linear data storage

Methods

batchSplice(offset, remove, data) → {Array} #

Returns ve.batchSplice of linear data

Parameters:

Name Type Description
offset number
remove number
data Array
Inherited from:
Source:
See:

Returns:

Type
Array
Returns ve.batchSplice of linear data

batchSpliceObject(offset, remove, data) → {ve.dm.LinearData} #

Returns ve.batchSplice of linear data, wrapped in a LinearData object

Parameters:

Name Type Description
offset number
remove number
data Array
Inherited from:
Source:
See:

Returns:

Type
ve.dm.LinearData
Returns ve.batchSplice of linear data, wrapped in a LinearData object

canTakeAnnotationAtOffset(offset, annotation, [ignoreClose]) → {boolean} #

Check if an annotation can be applied at a specific offset

Parameters:

Name Type Attributes Description
offset number
annotation ve.dm.Annotation
ignoreClose boolean optional

Ignore close elements, otherwise check if their open element is annotatable
Source:

Returns:

Annotation can be applied at this offset

Type
boolean
Check if an annotation can be applied at a specific offset

cloneElements(preserveGenerated) #

Run all elements through getClonedElement(). This should be done if you intend to insert the sliced data back into the document as a copy of the original data (e.g. for copy and paste).

Parameters:

Name Type Description
preserveGenerated boolean

Preserve internal.generated properties of elements
Source:
Run all elements through getClonedElement().

containsElementData() → {boolean} #

Check for elements in data.

This method assumes that any value that has a type property that's a string is an element object. Elements are discovered by iterating through the entire data array (backwards).

Inherited from:
Source:

Returns:

At least one elements exists in data

Type
boolean
Check for elements in data.

countNonInternalElements([limit]) → {number} #

Counts all elements that aren't between internalList and /internalList

Parameters:

Name Type Attributes Description
limit number optional

Number of elements after which to stop counting
Source:

Returns:

Number of elements that aren't in an internalList

Type
number
Counts all elements that aren't between internalList and /internalList

forEachRunOfContent(range, callback) #

Execute a callback function for each group of consecutive content data (text or content element).

Parameters:

Name Type Description
range ve.Range

Range in which to search
callback function

Function called with the following parameters:

Properties:
Name Type Description
offset number

Offset of the first datum of the run.
text string

Text of the run (with content element opening/closing data replaced with U+FFFC).
Source:
Execute a callback function for each group of consecutive content data (text or content element).

getAnnotatedRangeFromOffset(offset, annotation) → {ve.Range|null} #

Gets the range of content surrounding a given offset that's covered by a given annotation.

Parameters:

Name Type Description
offset number

Offset to begin looking forward and backward from
annotation Object

Annotation to test for coverage with
Source:

Returns:

Range of content covered by annotation, or null if offset is not covered

Type
ve.Range | null
Gets the range of content surrounding a given offset that's covered by a given annotation.

getAnnotatedRangeFromSelection(range, annotation) → {ve.Range|null} #

Get the range of an annotation found within a range.

Parameters:

Name Type Description
range ve.Range

Range to begin looking forward and backward from
annotation ve.dm.Annotation

Annotation to test for coverage with
Source:

Returns:

Range of content covered by annotation, or a copy of the range

Type
ve.Range | null
Get the range of an annotation found within a range.

getAnnotationHashesFromOffset(offset, [ignoreClose]) → {Array.<string>} #

Get annotations' store hashes covered by an offset.

Parameters:

Name Type Attributes Description
offset number

Offset to get annotations for
ignoreClose boolean optional

Ignore annotations on close elements
Source:

Returns:

An array of annotation store hashes the offset is covered by

Type
Array.<string>

Throws:

offset out of bounds

Type
Error
Get annotations' store hashes covered by an offset.

getAnnotationsFromOffset(offset, [ignoreClose]) → {ve.dm.AnnotationSet} #

Get annotations covered by an offset.

The returned AnnotationSet is a clone of the one in the data.

Parameters:

Name Type Attributes Description
offset number

Offset to get annotations for
ignoreClose boolean optional

Ignore annotations on close elements
Source:

Returns:

A set of all annotation objects offset is covered by

Type
ve.dm.AnnotationSet

Throws:

offset out of bounds

Type
Error
Get annotations covered by an offset.

getAnnotationsFromRange(range, [all], [nullIfContentEmpty]) → {ve.dm.AnnotationSet|null} #

Get annotations common to all content in a range.

Parameters:

Name Type Attributes Default Description
range ve.Range

Range to get annotations for
all boolean optional
 false

Get all annotations found within the range, not just those that cover it
nullIfContentEmpty boolean optional
 false

Returns null (instead of an empty ve.dm.AnnotationSet) if there is no content in the range.
Source:

Returns:

All annotation objects range is covered by.

Type
ve.dm.AnnotationSet | null
Get annotations common to all content in a range.

getCharacterData(offset) → {string} #

Get character data at a specified offset

Parameters:

Name Type Description
offset number

Offset to get character data from
Source:

Returns:

Character data

Type
string
Get character data at a specified offset

getCommonAnnotationArrayLength(range) → {number} #

Get the length of the common start sequence of annotations that applies to a whole range

Parameters:

Name Type Description
range ve.Range

The document range
Source:

Returns:

Common start sequence length (0 if the range is empty)

Type
number
Get the length of the common start sequence of annotations that applies to a whole range

getData([offset]) → {Object|Array} #

Gets linear data from a specified index, or all data if no index specified

Parameters:

Name Type Attributes Description
offset number optional

Offset to get data from
Inherited from:
Source:

Returns:

Data from index, or all data (by reference)

Type
Object | Array
Gets linear data from a specified index, or all data if no index specified

getDataSlice([range], [deep]) → {Array} #

Get a slice or copy of the provided data.

Parameters:

Name Type Attributes Default Description
range ve.Range optional

Range of data to get, all data will be given by default
deep boolean optional
 false

Whether to return a deep copy (WARNING! This may be very slow)
Inherited from:
Source:

Returns:

Slice or copy of data

Type
Array
Get a slice or copy of the provided data.

getInsertionAnnotationsFromRange(range, [startAfterAnnotations]) → {ve.dm.AnnotationSet} #

Get the insertion annotations that should apply to a range.

The semantics are intended to match Chromium's behaviour. TODO: This cannot match Firefox behaviour, which depends on the cursor's annotation boundary side, and performs a union of the annotations at each end of the selection; see https://phabricator.wikimedia.org/T113869 T113869} .

Parameters:

Name Type Attributes Description
range ve.Range

The range into which text would be inserted
startAfterAnnotations boolean optional

Use annotations after cursor if collapsed
Source:

Returns:

The insertion annotations that should apply

Type
ve.dm.AnnotationSet
Get the insertion annotations that should apply to a range.

getLength() → {number} #

Gets length of the linear data

Inherited from:
Source:

Returns:

Length of the linear data

Type
number
Gets length of the linear data

getNearestContentOffset(offset, [direction]) → {number} #

Get the nearest content offset to an offset.

If the offset is already a valid offset, it will be returned unchanged. This method differs from calling {getRelativeContentOffset} with a zero length difference because the direction can be controlled without necessarily moving the offset if it's already valid. Also, if the direction is 0 or undefined than nearest offsets will be found to the left and right and the one with the shortest distance will be used.

Parameters:

Name Type Attributes Description
offset number

Offset to start from
direction number optional

Direction to prefer matching offset in, -1 for left and 1 for right
Source:

Returns:

Nearest content offset or -1 if there are no valid offsets in data

Type
number
Get the nearest content offset to an offset.

getNearestStructuralOffset(offset, [direction], [unrestricted]) → {number} #

Get the nearest structural offset to an offset.

If the offset is already a valid offset, it will be returned unchanged. This method differs from calling {getRelativeStructuralOffset} with a zero length difference because the direction can be controlled without necessarily moving the offset if it's already valid. Also, if the direction is 0 or undefined than nearest offsets will be found to the left and right and the one with the shortest distance will be used.

Parameters:

Name Type Attributes Description
offset number

Offset to start from
direction number optional

Direction to prefer matching offset in, -1 for left and 1 for right
unrestricted boolean optional

Only consider offsets where any kind of element can be inserted
Source:

Returns:

Nearest structural offset

Type
number
Get the nearest structural offset to an offset.

getRelativeContentOffset(offset, distance) → {number} #

Get a content offset at a distance from an offset.

This method is a wrapper around {getRelativeOffset}, using {isContentOffset} as the offset validation callback.

Parameters:

Name Type Description
offset number

Offset to start from
distance number

Number of content offsets to move
Source:

Returns:

Relative content offset or -1 if there are no valid offsets in data

Type
number
Get a content offset at a distance from an offset.

getRelativeOffset(offset, distance, callback, […args]) → {number} #

Get an offset at a distance to an offset that passes a validity test.

  • If {offset} is not already valid, one step will be used to move it to a valid one.
  • If {offset} is already valid and cannot be moved in the direction of {distance} and still be valid, it will be left where it is
  • If {distance} is zero the result will either be {offset} if it's already valid or the nearest valid offset to the right if possible and to the left otherwise.
  • If {offset} is after the last valid offset and {distance} is >= 1, or if {offset} if before the first valid offset and {distance} <= 1 than the result will be the nearest valid offset in the opposite direction.
  • If the data does not contain a single valid offset the result will be -1

Nodes that want their children to be ignored (see ve.dm.Node#static-ignoreChildren) are not descended into. Giving a starting offset inside an ignoreChildren node will give unpredictable results.

Parameters:

Name Type Attributes Description
offset number

Offset to start from
distance number

Number of valid offsets to move
callback function

Function to call to check if an offset is valid which will be given initial argument of offset
args any optional
repeatable

Additional arguments to pass to the callback
Source:

Returns:

Relative valid offset or -1 if there are no valid offsets in data

Type
number
Get an offset at a distance to an offset that passes a validity test.

getRelativeStructuralOffset(offset, distance, [unrestricted]) → {number} #

Get a structural offset at a distance from an offset.

This method is a wrapper around {getRelativeOffset}, using {this.isStructuralOffset} as the offset validation callback.

Parameters:

Name Type Attributes Description
offset number

Offset to start from
distance number

Number of structural offsets to move
unrestricted boolean optional

Only consider offsets where any kind of element can be inserted
Source:

Returns:

Relative structural offset

Type
number
Get a structural offset at a distance from an offset.

getSourceText([range]) → {string} #

Get the data as original source text (source mode only)

Split paragraphs are converted to single line breaks. It is assumed the document contains nothing but plain text and paragraph elements.

Parameters:

Name Type Attributes Description
range ve.Range optional

Range to get the data for. The whole data set if not specified.
Source:

Returns:

Data as original source text

Type
string

Get the data as original source text (source mode only)

Split paragraphs are converted to single line breaks.

getStore() → {ve.dm.HashValueStore} #

Gets the hash-value store

Inherited from:
Source:

Returns:

The hash-value store

Type
ve.dm.HashValueStore
Gets the hash-value store

getText([maintainIndices], [range]) → {string} #

Get the data as plain text

Parameters:

Name Type Attributes Description
maintainIndices boolean optional

Maintain data offset to string index alignment by replacing elements with line breaks
range ve.Range optional

Range to get the data for. The whole data set if not specified.
Source:

Returns:

Data as plain text

Type
string
Get the data as plain text

getType(offset) → {string} #

Get the type of the element at a specified offset.

Parameters:

Name Type Description
offset number

Data offset
Inherited from:
Source:

Returns:

Type of the element

Type
string
Get the type of the element at a specified offset.

getUsedStoreValues([range]) → {Object} #

Finds all instances of items being stored in the hash-value store for this data store

Currently this is just all annotations still in use.

Parameters:

Name Type Attributes Description
range ve.Range optional

Optional range to get store values for
Source:

Returns:

Object containing all store values, keyed by store hash

Type
Object

Finds all instances of items being stored in the hash-value store for this data store

Currently this is just all annotations still in use.

getWordRange(offset) → {ve.Range} #

Get the range of the word at offset (else a collapsed range)

First, if the offset is not a content offset then it will be moved to the nearest one. Then, if the offset is inside a word, it will be expanded to that word; else if the offset is at the end of a word, it will be expanded to that word; else if the offset is at the start of a word, it will be expanded to that word; else the offset is not adjacent to any word and is returned as a collapsed range.

Parameters:

Name Type Description
offset number

Offset to start from; must not be inside a surrogate pair
Source:

Returns:

Boundaries of the adjacent word (else offset as collapsed range)

Type
ve.Range

Get the range of the word at offset (else a collapsed range)

First, if the offset is not a content offset then it will be moved to the nearest one.

hasAnnotationsInRange(range) → {boolean} #

Check if the range has any annotations

Parameters:

Name Type Description
range ve.Range

Range to check for annotations
Source:

Returns:

The range contains at least one annotation

Type
boolean
Check if the range has any annotations

hasContent() → {boolean} #

Checks if the document has content that's not part of an internalList.

Source:

Returns:

The document has content

Type
boolean
Checks if the document has content that's not part of an internalList.

isCloseElementData(offset) → {boolean} #

Checks if data at a given offset is a close element.

Parameters:

Name Type Description
offset number

Data offset
Inherited from:
Source:

Returns:

Data at offset is a close element

Type
boolean
Checks if data at a given offset is a close element.

isContentData() → {boolean} #

Check for non-content elements in data.

This method assumes that any value that has a type property that's a string is an element object. Elements are discovered by iterating through the entire data array.

Source:

Returns:

True if all elements in data are content elements

Type
boolean
Check for non-content elements in data.

isContentOffset(offset) → {boolean} #

Check if content can be inserted at an offset in document data.

This method assumes that any value that has a type property that's a string is an element object.

Content offsets:

 <heading> a </heading> <paragraph> b c <img> </img> </paragraph>
.         ^ ^          .           ^ ^ ^     .      ^            .

Content offsets:

 <list> <listItem> </listItem> <list>
.      .          .           .      .

Parameters:

Name Type Description
offset number

Document offset
Source:

Returns:

Content can be inserted at offset

Type
boolean
Check if content can be inserted at an offset in document data.

isElementData(offset) → {boolean} #

Check if data at a given offset is an element.

Parameters:

Name Type Description
offset number

Data offset
Inherited from:
Source:

Returns:

Data at offset is an element

Type
boolean
Check if data at a given offset is an element.

isOpenElementData(offset) → {boolean} #

Checks if data at a given offset is an open element.

Parameters:

Name Type Description
offset number

Data offset
Inherited from:
Source:

Returns:

Data at offset is an open element

Type
boolean
Checks if data at a given offset is an open element.

isPlainText([range], [ignoreNonContentNodes], [ignoredTypes], [ignoreCoveringAnnotations], [ignoreAllAnnotations]) → {boolean} #

Check if the data is just text

Parameters:

Name Type Attributes Description
range ve.Range optional

Range to get the data for. The whole data set if not specified.
ignoreNonContentNodes boolean optional

Ignore all non-content nodes, e.g. paragraphs, headings, lists
ignoredTypes Array.<string> optional

Only ignore specific non-content types
ignoreCoveringAnnotations boolean optional

Ignore covering annotations
ignoreAllAnnotations boolean optional

Ignore all annotations
Source:

Returns:

The data is plain text

Type
boolean
Check if the data is just text

isStructuralOffset(offset, [unrestricted]) → {boolean} #

Check if structure can be inserted at an offset in document data.

If the {unrestricted} param is true than only offsets where any kind of element can be inserted will return true. This can be used to detect the difference between a location that a paragraph can be inserted, such as between two tables but not directly inside a table.

This method assumes that any value that has a type property that's a string is an element object.

Structural offsets (unrestricted = false):

 <heading> a </heading> <paragraph> b c <img> </img> </paragraph>
^         . .          ^           . . .     .      .            ^

Structural offsets (unrestricted = true):

 <heading> a </heading> <paragraph> b c <img> </img> </paragraph>
^         . .          ^           . . .     .      .            ^

Structural offsets (unrestricted = false):

 <list> <listItem> </listItem> <list>
^      ^          ^           ^      ^

Content branch offsets (unrestricted = true):

 <list> <listItem> </listItem> <list>
^      .          ^           .      ^

Parameters:

Name Type Attributes Description
offset number

Document offset
unrestricted boolean optional

Only return true if any kind of element can be inserted at offset
Source:

Returns:

Structure can be inserted at offset

Type
boolean
Check if structure can be inserted at an offset in document data.

modifyData(offset, modify) #

Modify an existing object in the linear model

As objects in the model and immutable, this creates a clone which is passed to a callback function for modification, then the clone is inserted into the model.

Parameters:

Name Type Description
offset number

Offset to modify data at
modify function

Modification function. First argument is the data element to modify.
Inherited from:
Source:

Modify an existing object in the linear model

As objects in the model and immutable, this creates a clone which is passed to a callback function for modification, then the clone is inserted into the model.

push([…values]) → {number} #

Push data to the end of the array

Parameters:

Name Type Attributes Description
values Object optional
repeatable

Values to store
Inherited from:
Source:

Returns:

The new length of the linear data

Type
number
Push data to the end of the array

remapAnnotationHash(oldHash, newHash) #

Remap an annotation hash when it changes

Parameters:

Name Type Description
oldHash string

Old hash to replace
newHash string

New hash to replace it with
Source:
Remap an annotation hash when it changes

remapInternalListIndexes(mapping, internalList) #

Remap the internal list indexes used in this linear data.

Calls remapInternalListIndexes() for each node.

Parameters:

Name Type Description
mapping Object

Mapping from internal list indexes to internal list indexes
internalList ve.dm.InternalList

Internal list the indexes are being mapped into. Used for refreshing attribute values that were computed with getNextUniqueNumber().
Source:
Remap the internal list indexes used in this linear data.

remapInternalListKeys(internalList) #

Remap the internal list keys used in this linear data.

Calls remapInternalListKeys() for each node.

Parameters:

Name Type Description
internalList ve.dm.InternalList

Internal list the keys are being mapped into.
Source:
Remap the internal list keys used in this linear data.

sanitize(rules) #

Sanitize data according to a set of rules.

Parameters:

Name Type Description
rules Object

Sanitization rules

Properties:
Name Type Attributes Description
blacklist Array.<string> optional

Blacklist of model types which aren't allowed
conversions Object optional

Model type conversions to apply, e.g. { heading: 'paragraph' }
removeOriginalDomElements boolean optional

Remove references to DOM elements data was converted from
plainText boolean optional

Remove all formatting for plain text import
allowBreaks boolean optional

Allow
line breaks, otherwise the node will be split
preserveHtmlWhitespace boolean optional

Preserve non-semantic HTML whitespace
nodeSanitization boolean optional

Apply per-type node sanitizations via ve.dm.Node#sanitize
keepEmptyContentBranches boolean optional

Preserve empty content branch nodes
singleLine boolean optional

Don't allow more that one ContentBranchNode
allowMetaData boolean optional

Don't strip metadata
Source:
Sanitize data according to a set of rules.

setAnnotationHashesAtOffset(offset, hashes) #

Set annotations' store hashes at a specified offset.

Cleans up data structure if hashes array is empty.

Parameters:

Name Type Description
offset number

Offset to set annotation hashes at
hashes Array.<string>

Annotations' store hashes
Source:
Set annotations' store hashes at a specified offset.

setAnnotationsAtOffset(offset, annotations) #

Set annotations of data at a specified offset.

Cleans up data structure if annotation set is empty.

Parameters:

Name Type Description
offset number

Offset to set annotations at
annotations ve.dm.AnnotationSet

Annotations to set
Source:
Set annotations of data at a specified offset.

setAttributeAtOffset(offset, key, value) #

Set or unset an attribute at a specified offset.

Parameters:

Name Type Description
offset number

Offset to set/unset attribute at
key string

Attribute name
value any

Value to set, or undefined to unset
Source:
Set or unset an attribute at a specified offset.

setData(offset, value) #

Sets linear data at a specified index

Parameters:

Name Type Description
offset number

Offset to set data at
value Object | string

Value to store
Inherited from:
Source:
Sets linear data at a specified index

slice(begin, [end]) → {Array} #

Slice linear data

Parameters:

Name Type Attributes Description
begin number

Index to begin at
end number optional

Index to end at
Inherited from:
Source:

Returns:

One-level deep copy of sliced range

Type
Array
Slice linear data

sliceObject(begin, [end]) → {ve.dm.LinearData} #

Slice linear data and return new LinearData object containing result

Parameters:

Name Type Attributes Description
begin number

Index to begin at
end number optional

Index to end at
Inherited from:
Source:

Returns:

LinearData object containing one-level deep copy of sliced range

Type
ve.dm.LinearData
Slice linear data and return new LinearData object containing result

splice(index, deleteCount, […elements]) → {Array} #

Splice linear data

Parameters:

Name Type Attributes Description
index number

Splice from
deleteCount number

Items to be removed
elements Object optional
repeatable

Items to be inserted
Inherited from:
Source:

Returns:

Elements removed

Type
Array
Splice linear data

spliceObject(index, deleteCount, […elements]) → {ve.dm.LinearData} #

Splice linear data and return new LinearData object containing result

Parameters:

Name Type Attributes Description
index number

Splice from
deleteCount number

Items to be removed
elements Object optional
repeatable

Items to be inserted
Inherited from:
Source:

Returns:

LinearData object containing elements removed

Type
ve.dm.LinearData
Splice linear data and return new LinearData object containing result

trimOuterSpaceFromRange(range) → {Object} #

Get a range without any whitespace content at the beginning and end.

Parameters:

Name Type Description
range ve.Range

Range to trim
Source:

Returns:

Trimmed range

Type
Object
Get a range without any whitespace content at the beginning and end.

compareElements(a, b, aStore, [bStore]) → {boolean}static #

Compare two elements' basic properties and annotations

Elements are comparable if they have the same type, attributes, text data and annotations, as determined by ve.dm.AnnotationSet#compareTo .

Parameters:

Name Type Attributes Description
a Object | Array | string

First element
b Object | Array | string

Second element
aStore ve.dm.HashValueStore

First element's store
bStore ve.dm.HashValueStore optional

Second element's store, if different
Source:

Returns:

Elements are comparable

Type
boolean

Compare two elements' basic properties and annotations

Elements are comparable if they have the same type, attributes, text data and annotations, as determined by ve.dm.AnnotationSet#compareTo .

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

Compare two elements' basic properties

Elements are comparable if they have the same type and attributes, or have the same text data. Anything semantically irrelevant is filtered out first.

When changing, ensure that ve.dm.Transaction.static.compareElementsForTranslate is also updated.

Parameters:

Name Type Description
a Object | Array | string

First element
b Object | Array | string

Second element
Source:

Returns:

Elements are comparable

Type
boolean

Compare two elements' basic properties

Elements are comparable if they have the same type and attributes, or have the same text data.

getAnnotationHashesFromItem(item) → {Array.<string>}static #

Read the array of annotation store hashes from an item of linear data

Parameters:

Name Type Description
item string | Array | Object

Item of linear data
Source:

Returns:

An array of annotation store hashes

Type
Array.<string>
Read the array of annotation store hashes from an item of linear data

getCharacterDataFromItem(item) → {string}static #

Get character data from an item

Parameters:

Name Type Description
item string | Array | Object

Item to get character data from
Source:

Returns:

Character data, or '' if no character data

Type
string
Get character data from an item

replaceAnnotationHashesForItem(item, hashes) → {string|Array|Object}static #

Set annotations' store hashes at a specified offset.

Cleans up data structure if hashes array is empty.

Parameters:

Name Type Description
item string | Array | Object

Item of linear data
hashes Array.<string>

Annotations' store hashes
Source:

Returns:

Deep-copied, modified item

Type
string | Array | Object
Set annotations' store hashes at a specified offset.