Expand all

ve.dm.Document

Extends

Constructor

new ve.dm.Document(data, [htmlDocument], [parentDocument], [internalList], [innerWhitespace], [lang], [dir], [originalDocument], [sourceMode], [persistentStorage]) #

DataModel document.

WARNING: The data parameter is passed by reference. Do not modify a data array after passing it to this constructor, and do not construct multiple Documents with the same data array. If you need to do these things, make a deep copy (ve.copy) of the data array and operate on the copy.

Parameters:

Name Type Attributes Default Description
data Array | ve.dm.ElementLinearData

Raw linear model data or ElementLinearData
htmlDocument HTMLDocument optional

HTML document the data was converted from, if any. If omitted, a new document will be created. If data is an HTMLDocument, this parameter is ignored.
parentDocument ve.dm.Document optional

Document to use as root for created nodes, used when cloning
internalList ve.dm.InternalList optional

Internal list to clone; passed when creating a document slice
innerWhitespace Array.<(string|undefined)> optional

Inner whitespace to clone; passed when creating a document slice
lang string optional

Language code
dir string optional
 'ltr'

Directionality (ltr/rtl)
originalDocument ve.dm.Document optional

Original document form which this was cloned.
sourceMode boolean optional

Document is in source mode
persistentStorage Object optional

Persistent storage object
Source:
DataModel document.

Methods

buildNodeTree() #

Build the node tree.

Source:
Build the node tree.

cloneFromRange([range], [detachedCopy], [mode]) → {ve.dm.Document} #

Clone a sub-document from a range in this document. The new document's elements, store and internal list will be clones of the ones in this document.

Parameters:

Name Type Attributes Description
range ve.Range optional

Range of data to clone, clones the whole document if ommitted.
detachedCopy boolean optional

The copy is not intended to be merged into the original
mode string optional

Mode for getting data, see #getFullData
Source:

Returns:

New document

Type
ve.dm.Document
Clone a sub-document from a range in this document.

cloneWithData(data, [copyInternalList], [detachedCopy]) → {ve.dm.Document} #

Create a sub-document associated with this document like #cloneFromRange, but without cloning any data from a range in this document: instead, use the specified data.

Parameters:

Name Type Attributes Description
data Array | ve.dm.ElementLinearData

Raw linear model data or ElementLinearData
copyInternalList boolean optional

Copy the internal list
detachedCopy boolean optional

The copy is not intended to be merged into the original
Source:

Returns:

New document

Type
ve.dm.Document

Create a sub-document associated with this document like #cloneFromRange, but without cloning any data from a range in this document: instead, use the specified data.

commit(transaction, isStaging) #

Apply a transaction's effects on the content data.

Parameters:

Name Type Description
transaction ve.dm.Transaction

Transaction to apply
isStaging boolean

Transaction is being applied in staging mode
Source:

Fires:

Throws:

Cannot commit a transaction that has already been committed

Type
Error
Apply a transaction's effects on the content data.

findText(query, [options]) → {Array.<ve.Range>} #

Find a text string within the document

Parameters:

Name Type Attributes Description
query string | RegExp

Text to find, string or regex with no flags
options Object optional

Search options

Properties:
Name Type Attributes Description
caseSensitiveString boolean optional

Case sensitive search for a string query. Ignored by regexes (use 'i' flag).
diacriticInsensitiveString boolean optional

Diacritic insensitive search for a string query. Ignored by regexes. Only works in browsers which support the Internationalization API
noOverlaps boolean optional

Avoid overlapping matches
wholeWord boolean optional

Only match whole-word occurrences
Source:

Returns:

List of ranges where the string was found

Type
Array.<ve.Range>
Find a text string within the document

fixupInsertion(data, offset) → {ve.dm.Document.FixedInsertion} #

Fix up data so it can safely be inserted into the document data at an offset.

TODO: this function needs more work but it seems to work, mostly

Parameters:

Name Type Description
data Array

Snippet of linear model data to insert
offset number

Offset in the linear model where the caller wants to insert data
Source:

Returns:

Type
ve.dm.Document.FixedInsertion
Fix up data so it can safely be inserted into the document data at an offset.

getBranchNodeFromOffset(offset) → {ve.Node|null} #

Get a node at an offset.

Parameters:

Name Type Description
offset number

Offset to get node at
Overrides:
Source:

Returns:

Node at offset

Type
ve.Node | null
Get a node at an offset.

getChangeSince(start) → {ve.dm.Change} #

Single change containing most recent transactions in history stack

Parameters:

Name Type Description
start number

Pointer from where to start slicing transactions
Source:

Returns:

Single change containing transactions since pointer

Type
ve.dm.Change
Single change containing most recent transactions in history stack

getCompleteHistoryLength() → {number} #

Get the length of the complete history. This is also the current pointer.

Source:

Returns:

Length of the complete history stack

Type
number
Get the length of the complete history.

getCompleteHistorySince(start) → {Array.<ve.dm.Transaction>} #

Get all the transactions in the complete history since a specified pointer.

Parameters:

Name Type Description
start number

Pointer from where to start the slice
Source:

Returns:

Array of transaction objects

Type
Array.<ve.dm.Transaction>
Get all the transactions in the complete history since a specified pointer.

getCoveredSiblingGroups(range) → {Array} #

Get groups of sibling nodes covered by the given range.

Parameters:

Name Type Description
range ve.Range
Inherited from:
Source:

Returns:

Array of objects. Each object has the following keys:

  • nodes: Array of sibling nodes covered by a part of range
  • parent: Parent of all of these nodes
  • grandparent: parent's parent
Type
Array
Get groups of sibling nodes covered by the given range.

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

Get a slice or copy of the document 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)
Source:

Returns:

Slice or copy of document data

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

getDataFromNode(node) → {Array|null} #

Get the content data of a node.

Parameters:

Name Type Description
node ve.dm.Node

Node to get content data for
Source:

Returns:

List of content and elements inside node or null if node is not found

Type
Array | null
Get the content data of a node.

getDir() → {string} #

Get the content directionality

Source:

Returns:

Directionality (ltr/rtl)

Type
string
Get the content directionality

getDocumentNode() → {ve.BranchNode} #

Get the root of the document's node tree.

Overrides:
Source:

Returns:

Root of node tree

Type
ve.BranchNode
Get the root of the document's node tree.

getDocumentRange() → {ve.Range} #

Get a range that spans the entire document (excluding the internal list)

Source:

Returns:

Document range

Type
ve.Range
Get a range that spans the entire document (excluding the internal list)

getFullData([range], [mode]) → {Array} #

Get document data, possibly with inline MetaItem load offsets restored, possibly without metadata

Parameters:

Name Type Attributes Description
range ve.Range optional

Range to get full data for. If omitted, all data will be returned
mode string optional

If 'roundTrip', restore load offsets of inlined meta items from unchanged branches. If 'noMetadata', don't include metadata items.
Source:

Returns:

Data, with load offset info removed (some items are referenced, others copied)

Type
Array
Get document data, possibly with inline MetaItem load offsets restored, possibly without metadata

getHtmlDocument() → {HTMLDocument} #

Get the HTMLDocument associated with this document.

Source:

Returns:

Associated document

Type
HTMLDocument
Get the HTMLDocument associated with this document.

getInnerWhitespace() → {Array.<(string|undefined)>} #

Get the document's inner whitespace

Source:

Returns:

The document's inner whitespace

Type
Array.<(string|undefined)>
Get the document's inner whitespace

getInternalList() → {ve.dm.InternalList} #

Get the document's internal list

Source:

Returns:

The document's internal list

Type
ve.dm.InternalList
Get the document's internal list

getLang() → {string} #

Get the content language

Source:

Returns:

Language code

Type
string
Get the content language

getLength() → {number} #

Get the length of the document. This is also the highest valid offset in the document.

Source:

Returns:

Length of the document

Type
number
Get the length of the document.

getMetaList() → {ve.dm.MetaList} #

Get the meta list.

Source:

Returns:

Meta list of the surface

Type
ve.dm.MetaList
Get the meta list.

getMetadata([range]) → {Array.<ve.dm.MetaItem>} #

Get a copy of the document metadata.

This is just a sparse shallow copy of the document data, with meta-item open tags only (i.e. with blanks in place of non-meta-items and meta-item close tags).

Parameters:

Name Type Attributes Description
range ve.Range optional

Range of metadata to get, all metadata will be given by default
Source:

Returns:

Sparse array of ve.dm.MetaItems.

Type
Array.<ve.dm.MetaItem>
Get a copy of the document metadata.

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

Get the nearest offset that a cursor can be placed at.

Note that an offset in the other direction can be returned if there are no valid offsets in the preferred direction.

Parameters:

Name Type Attributes Default Description
offset number

Offset to start looking at
direction number optional
 -1

Direction to check first, +1 or -1; if 0, find the closest offset
Source:

Returns:

Nearest offset a cursor can be placed at, or -1 if there are no valid offsets in data

Type
number
Get the nearest offset that a cursor can be placed at.

getNearestFocusableNode(offset, direction, limit) → {ve.dm.Node|null} #

Get the nearest focusable node.

Parameters:

Name Type Description
offset number

Offset to start looking at
direction number

Direction to look in, +1 or -1
limit number

Stop looking after reaching certain offset
Source:

Returns:

Nearest focusable node, or null if not found

Type
ve.dm.Node | null
Get the nearest focusable node.

getNearestNodeMatching(test, offset, direction, limit) → {ve.dm.Node|null} #

Get the nearest node matching a test.

Parameters:

Name Type Description
test function

Function to test whether a node matches, called with the nodeType
offset number

Offset to start looking at
direction number

Direction to look in, +1 or -1
limit number

Stop looking after reaching certain offset
Source:

Returns:

Nearest matching node, or null if not found

Type
ve.dm.Node | null
Get the nearest node matching a test.

getNodesByType(type, sort) → {Array.<ve.dm.Node>} #

Get all nodes in the tree for a specific type

If a string type is passed only nodes of that exact type will be returned, if a node class is passed, all sub types will be matched.

String type matching will be faster than class matching.

Parameters:

Name Type Description
type string | function

Node type name or node constructor
sort boolean

Sort nodes by document order
Source:

Returns:

Nodes of a specific type

Type
Array.<ve.dm.Node>

Get all nodes in the tree for a specific type

If a string type is passed only nodes of that exact type will be returned, if a node class is passed, all sub types will be matched.

getOriginalDocument() → {ve.dm.Document|null} #

Get the document model form which this document was cloned.

Source:

Returns:

Original document

Type
ve.dm.Document | null
Get the document model form which this document was cloned.

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

Get the relative word or character boundary.

Parameters:

Name Type Attributes Description
offset number

Offset to start from
direction number

Direction to prefer matching offset in, -1 for left and 1 for right
unit string optional

Unit [word|character]
Source:

Returns:

Relative offset

Type
number
Get the relative word or character boundary.

getRelativeRange(range, direction, unit, expand, [limit]) → {ve.Range} #

Get the relative range.

Parameters:

Name Type Attributes Description
range ve.Range

Input range
direction number

Direction to look in, +1 or -1
unit string

Unit [word|character]
expand boolean

Expanding range
limit ve.Range optional

Optional limiting range. If the relative range is not in this range the input range is returned instead.
Source:

Returns:

Relative range

Type
ve.Range
Get the relative range.

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

Get the nearest word boundary.

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 word boundary

Type
number
Get the nearest word boundary.

getStorage([key]) → {any|Object} #

Get a value from the persistent static storage, or the whole store

Parameters:

Name Type Attributes Description
key string optional

Key
Source:

Returns:

Value at key, or whole storage object if key not provided

Type
any | Object
Get a value from the persistent static storage, or the whole store

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

Get the document's hash-value store

Source:

Returns:

The document's hash-value store

Type
ve.dm.HashValueStore
Get the document's hash-value store

hasSlugAtOffset(offset) → {boolean} #

Check if there is a slug at an offset.

Parameters:

Name Type Description
offset number

Offset to check for a slug at
Source:

Returns:

There is a slug at the offset

Type
boolean
Check if there is a slug at an offset.

isReadOnly() → {boolean} #

Check if the document is read-only

Source:

Returns:

Type
boolean
Check if the document is read-only

newFromHtml(html, [importRules]) → {ve.dm.Document} #

Create a document given an HTML string or document.

Parameters:

Name Type Attributes Description
html string | HTMLDocument

HTML string or document to insert
importRules Object optional

The import rules with which to sanitize the HTML, if importing
Source:

Returns:

New document

Type
ve.dm.Document
Create a document given an HTML string or document.

nodeAttached(node) #

Callback when a node is attached with ve.Node#setDocument

The node and all its children are guaranteed to be attached

Parameters:

Name Type Description
node ve.Node

The node attached
Inherited from:
Source:

Fires:

Callback when a node is attached with ve.Node#setDocument

The node and all its children are guaranteed to be attached

nodeDetached(node) #

Callback when a node is attached with ve.Node#setDocument

The node and all its children are guaranteed to be attached

Parameters:

Name Type Description
node ve.Node

The node detached
Inherited from:
Source:

Fires:

Callback when a node is attached with ve.Node#setDocument

The node and all its children are guaranteed to be attached

rangeInsideOneLeafNode(range) → {boolean} #

Test whether a range lies within a single leaf node.

Parameters:

Name Type Description
range ve.Range

The range to test
Inherited from:
Source:

Returns:

Whether the range lies within a single node

Type
boolean
Test whether a range lies within a single leaf node.

rebuildTree() #

Rebuild the entire node tree from linear model data.

Source:
Rebuild the entire node tree from linear model data.

selectNodes(range, [mode]) → {Array} #

Gets a list of nodes and the ranges within them that a selection of the document covers.

Parameters:

Name Type Attributes Default Description
range ve.Range

Range within document to select nodes
mode string optional
 'leaves'

Type of selection to perform:

  • leaves: Return all leaf nodes in the given range (descends all the way down)
  • branches': Return all branch nodes in the given range
  • covered: Do not descend into nodes that are entirely covered by the range. The result is similar to that of 'leaves' except that if a node is entirely covered, its children aren't returned separately.
  • siblings: Return a set of adjacent siblings covered by the range (descends as long as the range is in a single node)
Inherited from:
Source:

Returns:

List of objects describing nodes in the selection and the ranges therein:

  • node: Reference to a ve.Node
  • range: ve.Range, missing if the entire node is covered
  • index: Index of the node in its parent, missing if node has no parent
  • indexInNode: If range is a zero-length range between two children of node, this is set to the index of the child following range (or to node.children.length + 1 if range is between the last child and the end). If range is a zero-length range inside an empty non-content branch node, this is 0. Missing in all other cases.
  • nodeRange: Range covering the inside of the entire node, not including wrapper
  • nodeOuterRange: Range covering the entire node, including wrapper
  • parentOuterRange: Outer range of node's parent. Missing if there is no parent or if indexInNode is set.
Type
Array

Throws:

  • Invalid mode

    Type
    Error

  • Invalid start offset

    Type
    Error

  • Invalid end offset

    Type
    Error

  • Failed to select any nodes

    Type
    Error
Gets a list of nodes and the ranges within them that a selection of the document covers.

setReadOnly(readOnly) #

Set the read-only state of the document

Actual locking of the model is done by the surface, but we pass through this flag so we can do some optimizations in read-only mode, such as caching node offsets.

TODO: It might just be easier for Documents to know which Surface they belong to, although we should make sure that this doesn't violate the direction of data flow.

Parameters:

Name Type Description
readOnly boolean

Mark document as read-only
Source:

Set the read-only state of the document

Actual locking of the model is done by the surface, but we pass through this flag so we can do some optimizations in read-only mode, such as caching node offsets.

setStorage([keyOrStorage], [value]) #

Set a key/value pair in persistent static storage, or restore the whole store

Storage is used for static variables related to document state, such as InternalList's nextUniqueNumber.

Parameters:

Name Type Attributes Description
keyOrStorage string | Object optional

Key, or storage object to restore
value any optional

Serializable value, if key is set
Source:

Fires:

Set a key/value pair in persistent static storage, or restore the whole store

Storage is used for static variables related to document state, such as InternalList's nextUniqueNumber.

shallowCloneFromRange([range]) → {ve.dm.DocumentSlice} #

Clone a sub-document from a shallow copy of this document.

The new document's elements, internal list and store will only contain references to data within the slice.

Parameters:

Name Type Attributes Description
range ve.Range optional

Range of data to slice; defaults to whole document
Source:

Returns:

New document

Type
ve.dm.DocumentSlice
Clone a sub-document from a shallow copy of this document.

shallowCloneFromSelection(selection) → {ve.dm.DocumentSlice} #

Clone a sub-document from a shallow copy of this document.

The new document's elements, internal list and store will only contain references to data within the slice.

Parameters:

Name Type Description
selection ve.dm.Selection

Selection to create sub-document from
Source:

Returns:

New document

Type
ve.dm.DocumentSlice
Clone a sub-document from a shallow copy of this document.

updateNodesByType(addedNodes, removedNodes) #

Update the nodes-by-type index

Parameters:

Name Type Description
addedNodes Array.<ve.dm.Node>

Added nodes
removedNodes Array.<ve.dm.Node>

Removed nodes
Source:
Update the nodes-by-type index

addAnnotationsToData(data, annotationSet, [replaceComparable], [store], [prepend])static #

Apply annotations to content data.

This method modifies data in place.

Parameters:

Name Type Attributes Description
data ve.dm.ElementLinearData | Array

Data to apply annotations to
annotationSet ve.dm.AnnotationSet

Annotations to apply
replaceComparable boolean optional

Whether to remove annotations from the data which are comparable to those in annotationSet
store ve.dm.HashValueStore optional

Store associated with the data; only needs to be provided if that data is associated with a different store than annotationSet
prepend boolean optional

Whether to prepend annotationSet to the existing annotations
Source:
Apply annotations to content data.

newBlankDocument([paragraphType]) → {ve.dm.Document}static #

Provide a new, empty Document.

Parameters:

Name Type Attributes Default Description
paragraphType string optional
 'empty'

Paragraph type: 'empty', 'wrapper' or null for a regular paragraph
Source:

Returns:

Type
ve.dm.Document
Provide a new, empty Document.

Type Definitions

FixedInsertion #

Properties:

Name Type Attributes Description
data Array

Possibly modified copy of data
offset number

Possibly modified offset
remove number

Number of elements to remove after the modified offset
insertedDataOffset number optional

Offset of intended insertion within fixed up data
insertedDataLength number optional

Length of intended insertion within fixed up data
Source:

Events

nodeAttached(node) #

A node has been attached with ve.Node#setDocument . Its descendants are guaranteed to be attached too (and the event is emitted for descendants first, and for siblings in their order in the children list)

Parameters:

Name Type Description
node ve.Node

The node that has been attached
Inherited from:
Source:
A node has been attached with ve.Node#setDocument .

nodeDetached(node) #

A node has been detached with ve.Node#setDocument . Its descendants are guaranteed to be detached too (and the event is emitted for descendants first, and for siblings in their order in the children list)

Parameters:

Name Type Description
node ve.Node

The node that has been detached
Inherited from:
Source:
A node has been detached with ve.Node#setDocument .

precommit(tx) #

Emitted when a transaction is about to be committed.

Parameters:

Name Type Description
tx ve.dm.Transaction

Transaction that is about to be committed
Source:
Emitted when a transaction is about to be committed.

storage() #

A value in persistent storage has changed

Source:
A value in persistent storage has changed

transact(tx) #

Emitted when a transaction has been committed.

Parameters:

Name Type Description
tx ve.dm.Transaction

Transaction that was just processed
Source:
Emitted when a transaction has been committed.