Expand all

ve.dm.DocumentSlice

Extends

Constructor

new ve.dm.DocumentSlice(data, [htmlDocument], [parentDocument], [internalList], [originalRange], [balancedRange], [originalDocument]) #

DataModel document slice

Parameters:

Name Type Attributes Description
data HTMLDocument | Array | ve.dm.ElementLinearData
htmlDocument HTMLDocument optional
parentDocument ve.dm.Document optional
internalList ve.dm.InternalList optional
originalRange ve.Range optional

Range of original data
balancedRange ve.Range optional

Range of balanced data
originalDocument ve.dm.Document optional
Source:
DataModel document slice

Methods

buildNodeTree() #

Build the node tree.

Inherited from:
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
Inherited from:
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
Inherited from:
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
Inherited from:
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
searchRange boolean optional

Range to search. Defaults to the attached root.
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
Inherited from:
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
Inherited from:
Source:

Returns:

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

getAttachedRoot() → {ve.dm.BranchNode} #

Get the attached root node

Inherited from:
Source:

Returns:

Attached root

Type
ve.dm.BranchNode
Get the attached root node

getAttachedRootRange() → {ve.Range} #

Get a range that spans the attached root (excluding the internal list)

Inherited from:
Source:

Returns:

Attached root's range

Type
ve.Range
Get a range that spans the attached root (excluding the internal list)

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

Get a node at an offset.

Parameters:

Name Type Description
offset number

Offset to get node at
Inherited from:
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
Inherited from:
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.

Inherited from:
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
Inherited from:
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)
Inherited from:
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
Inherited from:
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

Inherited from:
Source:

Returns:

Directionality (ltr/rtl)

Type
string
Get the content directionality

getDocumentNode() → {ve.BranchNode} #

Get the root of the document's node tree.

Inherited from:
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)

Inherited from:
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.
Inherited from:
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.

Inherited from:
Source:

Returns:

Associated document

Type
HTMLDocument
Get the HTMLDocument associated with this document.

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

Get the document's inner whitespace

Inherited from:
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

Inherited from:
Source:

Returns:

The document's internal list

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

getLang() → {string} #

Get the content language

Inherited from:
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.

Inherited from:
Source:

Returns:

Length of the document

Type
number
Get the length of the document.

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

Get the meta list.

Inherited from:
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
Inherited from:
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
Inherited from:
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
Inherited from:
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
Inherited from:
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
Inherited from:
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.

Inherited from:
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]
Inherited from:
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.
Inherited from:
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
Inherited from:
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
Inherited from:
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

Inherited from:
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
Inherited from:
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

Inherited from:
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
Inherited from:
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.

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

rebuildTreeNode(rootNode) #

Rebuild the node tree from linear model data from a specicifc range.

Parameters:

Name Type Description
rootNode ve.dm.BranchNode

Node to rebuild
Inherited from:
Source:
Rebuild the node tree from linear model data from a specicifc range.

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.

setAttachedRoot(attachedRoot) #

Set the attached root node

Parameters:

Name Type Description
attachedRoot ve.dm.BranchNode

Attached root
Inherited from:
Source:
Set the attached root node

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
Inherited from:
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
Inherited from:
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
Inherited from:
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
Inherited 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
Inherited from:
Source:
Update the nodes-by-type index

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
Inherited from:
Source:
Emitted when a transaction is about to be committed.

storage() #

A value in persistent storage has changed

Inherited from:
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
Inherited from:
Source:
Emitted when a transaction has been committed.