Expand all

ve.dm.SurfaceFragment

Constructor

new ve.dm.SurfaceFragment(surface, [selection], [noAutoSelect], [excludeInsertions]) #

DataModel surface fragment.

Parameters:

Name Type Attributes Description
surface ve.dm.Surface

Target surface
selection ve.dm.Selection optional

Selection within target document, current selection used by default
noAutoSelect boolean optional

Don't update the surface's selection when making changes
excludeInsertions boolean optional

Exclude inserted content at the boundaries when updating range
Source:
DataModel surface fragment.

Methods

adjustLinearSelection([start], [end]) → {ve.dm.SurfaceFragment} #

Get a new fragment with an adjusted position

Parameters:

Name Type Attributes Description
start number optional

Adjustment for start position
end number optional

Adjustment for end position
Source:

Returns:

Adjusted fragment

Type
ve.dm.SurfaceFragment
Get a new fragment with an adjusted position

annotateContent(method, nameOrAnnotations, [data]) → {ve.dm.SurfaceFragment}chainable #

Apply an annotation to content in the fragment.

To avoid problems identified in T35108, use the {ve.dm.SurfaceFragment.trimLinearSelection} method.

TODO: Optionally take an annotation set instead of name and data arguments and set/clear multiple annotations in a single transaction.

Parameters:

Name Type Attributes Description
method string

Mode of annotation, either 'set' or 'clear'
nameOrAnnotations string | ve.dm.Annotation | ve.dm.AnnotationSet

Annotation name, for example: 'textStyle/bold', Annotation object or AnnotationSet
data Object optional

Additional annotation data (not used if annotation object is given)
Source:

Returns:

Type
ve.dm.SurfaceFragment
Apply an annotation to content in the fragment.

change(txs, [selection]) #

Process a set of transactions on the surface, and update the selection if the fragment is auto-selecting.

Parameters:

Name Type Attributes Description
txs ve.dm.Transaction | Array.<ve.dm.Transaction>

Transaction(s) to process
selection ve.dm.Selection optional

Selection to set, if different from translated selection, required if the fragment is null
Source:

Throws:

If fragment is null and selection is omitted

Type
Error

Process a set of transactions on the surface, and update the selection if the fragment is auto-selecting.

changeAttributes(attr, [type]) → {ve.dm.SurfaceFragment}chainable #

Change one or more attributes on covered nodes.

Parameters:

Name Type Attributes Description
attr Object

List of attributes to change, use undefined to remove an attribute
type string optional

Node type to restrict changes to
Source:

Returns:

Type
ve.dm.SurfaceFragment
Change one or more attributes on covered nodes.

clearPending() #

Clear a fragment's pending list

Source:
Clear a fragment's pending list

clone([selection]) → {ve.dm.SurfaceFragment} #

Get a clone of this SurfaceFragment, optionally with a different selection.

Parameters:

Name Type Attributes Description
selection ve.dm.Selection optional

If set, use this selection rather than the old fragment's selection
Source:

Returns:

Clone of this fragment

Type
ve.dm.SurfaceFragment
Get a clone of this SurfaceFragment, optionally with a different selection.

collapseToEnd() → {ve.dm.SurfaceFragment} #

Get a new fragment with a zero-length selection at the end offset.

Source:

Returns:

Collapsed fragment

Type
ve.dm.SurfaceFragment
Get a new fragment with a zero-length selection at the end offset.

collapseToStart() → {ve.dm.SurfaceFragment} #

Get a new fragment with a zero-length selection at the start offset.

Source:

Returns:

Collapsed fragment

Type
ve.dm.SurfaceFragment
Get a new fragment with a zero-length selection at the start offset.

containsOnlyText() → {boolean} #

Whether the fragment contains only text, allowing annotations

Source:

Returns:

Whether there's only text

Type
boolean
Whether the fragment contains only text, allowing annotations

convertNodes(type, [attr], [internal]) → {ve.dm.SurfaceFragment}chainable #

Convert each content branch in the fragment from one type to another.

Parameters:

Name Type Attributes Description
type string

Element type to convert to
attr Object optional

Initial attributes for new element
internal Object optional

Internal attributes for new element
Source:

Returns:

Type
ve.dm.SurfaceFragment
Convert each content branch in the fragment from one type to another.

delete([directionAfterDelete]) → {ve.dm.SurfaceFragment}chainable #

Delete content and correct selection

Parameters:

Name Type Attributes Default Description
directionAfterDelete number optional
 -1

Direction to move after delete: 1 or -1 or 0
Source:

Returns:

Type
ve.dm.SurfaceFragment
Delete content and correct selection

expandLinearSelection([scope], [type]) → {ve.dm.SurfaceFragment} #

Get a new fragment that covers an expanded range of the document.

Parameters:

Name Type Attributes Default Description
scope string optional
 'parent'

Method of expansion:

  • word: Expands to cover the nearest word by looking for word breaks (see UnicodeJS.wordbreak)
  • annotation: Expands to cover a given annotation type (ve.dm.Annotation) within the current range
  • root: Expands to cover the entire document
  • siblings: Expands to cover all sibling nodes
  • closest: Expands to cover the closest common ancestor node of a give type (ve.dm.Node)
  • parent: Expands to cover the closest common parent node
type ve.dm.Annotation | ve.dm.Node optional

Parameter to use with scope method if needed
Source:

Returns:

Expanded fragment

Type
ve.dm.SurfaceFragment
Get a new fragment that covers an expanded range of the document.

getAnnotations([all]) → {ve.dm.AnnotationSet} #

Get annotations in fragment.

By default, this will only get annotations that completely cover the fragment. Use the {all} argument to get all annotations that occur within the fragment.

Parameters:

Name Type Attributes Description
all boolean optional

Get annotations which only cover some of the fragment
Source:

Returns:

All annotation objects range is covered by

Type
ve.dm.AnnotationSet
Get annotations in fragment.

getCoveredNodes() → {Array} #

Get nodes covered by the fragment.

Does not descend into nodes that are entirely covered by the range. The result is similar to that of {ve.dm.SurfaceFragment.prototype.getLeafNodes} except that if a node is entirely covered, its children aren't returned separately.

Source:
See:

Returns:

List of nodes and related information

Type
Array
Get nodes covered by the fragment.

getData([deep]) → {Array} #

Get data for the fragment.

Parameters:

Name Type Attributes Description
deep boolean optional

Get a deep copy of the data
Source:

Returns:

Fragment data

Type
Array
Get data for the fragment.

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

Get the document of the surface the fragment is a part of.

Source:

Returns:

Document of surface of fragment

Type
ve.dm.Document | null
Get the document of the surface the fragment is a part of.

getLeafNodes() → {Array} #

Get all leaf nodes covered by the fragment.

Source:
See:

Returns:

List of nodes and related information

Type
Array
Get all leaf nodes covered by the fragment.

getPending() → {jQuery.Promise} #

Get a promise that resolves when the pending list is complete

Source:

Returns:

Type
jQuery.Promise
Get a promise that resolves when the pending list is complete

getSelectedLeafNodes() → {Array.<ve.dm.Node>} #

Get all leaf nodes excluding nodes where the selection is empty.

Source:

Returns:

List of nodes and related information

Type
Array.<ve.dm.Node>
Get all leaf nodes excluding nodes where the selection is empty.

getSelectedModels([all]) → {Array.<ve.dm.Model>} #

Get list of selected nodes and annotations.

Parameters:

Name Type Attributes Description
all boolean optional

Include nodes and annotations which only cover some of the fragment
Source:

Returns:

Selected models

Type
Array.<ve.dm.Model>
Get list of selected nodes and annotations.

getSelectedNode() → {ve.dm.Node|null} #

Get the node selected by a range, i.e. the range matches the node's range exactly.

Note that this method operates on the fragment's range, not the document's current selection. This fragment does not need to be selected for this method to work.

Source:

Returns:

The node selected by the range, or null if a node is not selected

Type
ve.dm.Node | null
Get the node selected by a range, i.e.

getSelection() → {ve.dm.Selection} #

Get the selection of the fragment within the surface.

This method also calls update to make sure the selection returned is current.

Source:

Returns:

The selection

Type
ve.dm.Selection
Get the selection of the fragment within the surface.

getSiblingNodes() → {Array} #

Get nodes covered by the fragment.

Includes adjacent siblings covered by the range, descending if the range is in a single node.

Source:
See:

Returns:

List of nodes and related information

Type
Array
Get nodes covered by the fragment.

getSurface() → {ve.dm.Surface|null} #

Get the surface the fragment is a part of.

Source:

Returns:

Surface of fragment

Type
ve.dm.Surface | null
Get the surface the fragment is a part of.

getText([maintainIndices]) → {string} #

Get plain text for the fragment.

Parameters:

Name Type Attributes Description
maintainIndices boolean optional

Maintain data offset to string index alignment by replacing elements with line breaks
Source:

Returns:

Fragment text

Type
string
Get plain text for the fragment.

hasAnnotations() → {boolean} #

Check if the fragment has any annotations

Quicker than doing !fragment.getAnnotations( true ).isEmpty() as it stops at the first sight of an annotation.

Source:

Returns:

The fragment contains at least one annotation

Type
boolean

Check if the fragment has any annotations

Quicker than doing !fragment.getAnnotations( true ).isEmpty() as it stops at the first sight of an annotation.

hasMatchingAncestor(type, [attributes], [matchFirstAncestorOfType]) → {boolean} #

Check if the nodes at the current fragment have an ancestor with matching type and attribute values.

Parameters:

Name Type Attributes Description
type string

Node type to match
attributes Object optional

Node attributes to match
matchFirstAncestorOfType boolean optional

Require the match to be the first of its type, e.g. if type is 'list', only match the first 'list' ancestor, then check if the attributes match.
Source:

Returns:

Nodes have a matching ancestor

Type
boolean
Check if the nodes at the current fragment have an ancestor with matching type and attribute values.

insertContent(content, [annotateOrSet]) → {ve.dm.SurfaceFragment}chainable #

Remove content in the fragment and insert content before it.

This will move the fragment's range to cover the inserted content. Note that this may be different from what a normal range translation would do: the insertion might occur at a different offset if that is needed to make the document balanced.

If the content is a plain text string containing linebreaks, each line will be wrapped in a paragraph.

Parameters:

Name Type Attributes Description
content string | Array

Content to insert, can be either a string or array of data
annotateOrSet boolean | ve.dm.AnnotationSet optional

Content should be automatically annotated to match surrounding content, or an AnnotationSet from the current offset (calculated from the view)
Source:

Returns:

Type
ve.dm.SurfaceFragment
Remove content in the fragment and insert content before it.

insertDocument(newDoc, [newDocRange], [annotateOrSet]) → {ve.dm.SurfaceFragment}chainable #

Insert a ve.dm.Document in the fragment.

This will move the fragment's range to cover the inserted content. Note that this may be different from what a normal range translation would do: the insertion might occur at a different offset if that is needed to make the document balanced.

Parameters:

Name Type Attributes Description
newDoc ve.dm.Document

Document to insert
newDocRange ve.Range optional

Range from the new document to insert (defaults to entire document)
annotateOrSet boolean | ve.dm.AnnotationSet optional

Content should be automatically annotated to match surrounding content, or an AnnotationSet from the current offset (calculated from the view)
Source:

Returns:

Type
ve.dm.SurfaceFragment
Insert a ve.dm.Document in the fragment.

insertHtml(html, [importRules]) → {ve.dm.SurfaceFragment}chainable #

Insert HTML in the fragment.

This will move the fragment's range to cover the inserted content. Note that this may be different from what a normal range translation would do: the insertion might occur at a different offset if that is needed to make the document balanced.

Parameters:

Name Type Attributes Description
html string

HTML to insert
importRules Object optional

The import rules for the target surface, if importing
Source:

Returns:

Type
ve.dm.SurfaceFragment
Insert HTML in the fragment.

insertMeta(meta, offset) #

Insert new metadata into the document. This builds and processes a transaction that inserts metadata into the document.

Pass a plain object rather than a MetaItem into this function unless you know what you're doing.

Parameters:

Name Type Description
meta Object | ve.dm.MetaItem

Metadata element (or MetaItem) to insert
offset number

Document offset to insert at; must be a valid offset for metadata; defaults to document end
Source:
Insert new metadata into the document.

isNull() → {boolean} #

Check if the fragment is null.

Source:

Returns:

Fragment is a null fragment

Type
boolean
Check if the fragment is null.

isolateAndUnwrap(isolateForType) → {ve.dm.SurfaceFragment}chainable #

Isolates the nodes in a fragment then unwraps them.

The node selection is expanded to siblings. These are isolated such that they are the sole children of the nearest parent element which can 'type' can exist in.

The new isolated selection is then safely unwrapped.

Parameters:

Name Type Description
isolateForType string

Node type to isolate for
Source:

Returns:

Type
ve.dm.SurfaceFragment
Isolates the nodes in a fragment then unwraps them.

pushPending(promise) #

Push a promise to the fragment's pending list

Parameters:

Name Type Description
promise jQuery.Promise
Source:
Push a promise to the fragment's pending list

removeContent() → {ve.dm.SurfaceFragment}chainable #

Remove content in the fragment.

Source:

Returns:

Type
ve.dm.SurfaceFragment
Remove content in the fragment.

removeMeta(item) #

Remove a meta item from the document. This builds and processes a transaction that removes the associated metadata from the document.

Parameters:

Name Type Description
item ve.dm.MetaItem

Item to remove
Source:
Remove a meta item from the document.

replaceMeta(oldItem, meta) #

Replace a MetaItem with another in-place.

Pass a plain object rather than a MetaItem into this function unless you know what you're doing.

Parameters:

Name Type Description
oldItem ve.dm.MetaItem

Old item to replace
meta Object | ve.dm.MetaItem

Metadata element (or MetaItem) to insert
Source:
Replace a MetaItem with another in-place.

rewrapAllNodes(depth, wrapper) → {ve.dm.SurfaceFragment}chainable #

Change the wrapping of nodes in the fragment from one type to another.

A wrapper object is a linear model element; a plain object containing a type property and an optional attributes property.

Example: // fragment is a selection of:

a

b

fragment.rewrapAllNodes( 1, { type: 'heading', attributes: { level: 2 } } ); // fragment is now a selection of:

a

b

Parameters:

Name Type Description
depth number

Number of nodes to unwrap
wrapper Object | Array.<Object>

Wrapper object, or array of wrapper objects (see above)

Properties:
Name Type Attributes Description
type string

Node type of wrapper
attributes Object optional

Attributes of wrapper
Source:

Returns:

Type
ve.dm.SurfaceFragment
Change the wrapping of nodes in the fragment from one type to another.

rewrapNodes(depth, wrapper) → {ve.dm.SurfaceFragment}chainable #

Change the wrapping of each node in the fragment from one type to another.

A wrapper object is a linear model element; a plain object containing a type property and an optional attributes property.

Example: // fragment is a selection of:

a

b

fragment.rewrapNodes( 2, [{ type: 'list', attributes: { style: 'bullet' } }, { type: 'listItem' }] ) // fragment is now a selection of:

  • a

  • b

Parameters:

Name Type Description
depth number

Number of nodes to unwrap
wrapper Object | Array.<Object>

Wrapper object, or array of wrapper objects (see above)

Properties:
Name Type Attributes Description
type string

Node type of wrapper
attributes Object optional

Attributes of wrapper
Source:

Returns:

Type
ve.dm.SurfaceFragment
Change the wrapping of each node in the fragment from one type to another.

select() → {ve.dm.SurfaceFragment}chainable #

Apply the fragment's range to the surface as a selection.

Source:

Returns:

Type
ve.dm.SurfaceFragment
Apply the fragment's range to the surface as a selection.

setAutoSelect([autoSelect]) → {ve.dm.SurfaceFragment}chainable #

Change whether to automatically update the surface selection when making changes.

Parameters:

Name Type Attributes Default Description
autoSelect boolean optional
 true

Automatically update surface selection
Source:

Returns:

Type
ve.dm.SurfaceFragment
Change whether to automatically update the surface selection when making changes.

setExcludeInsertions(excludeInsertions) → {ve.dm.SurfaceFragment}chainable #

Tell this fragment whether it should exclude insertions. If this option is enabled, updates to this fragment's selection in response to transactions will not include content inserted at the boundaries of the selection; if it is disabled, insertions will be included.

Parameters:

Name Type Description
excludeInsertions boolean

Whether to exclude insertions
Source:

Returns:

Type
ve.dm.SurfaceFragment
Tell this fragment whether it should exclude insertions.

trimLinearSelection() → {ve.dm.SurfaceFragment} #

Get a new fragment with a range that no longer includes leading and trailing whitespace.

Source:

Returns:

Trimmed fragment

Type
ve.dm.SurfaceFragment
Get a new fragment with a range that no longer includes leading and trailing whitespace.

truncateLinearSelection(limit) → {ve.dm.SurfaceFragment} #

Get a new fragment with a truncated length.

Parameters:

Name Type Description
limit number

Maximum length of new range (negative for left-side truncation)
Source:

Returns:

Truncated fragment

Type
ve.dm.SurfaceFragment
Get a new fragment with a truncated length.

unwrapNodes(outerDepth, innerDepth) → {ve.dm.SurfaceFragment}chainable #

Unwrap nodes in the fragment out of one or more elements.

Example: // fragment is a selection of:

    「

  • a

  • b

    • 」
fragment.unwrapNodes( 1, 1 ) // fragment is now a selection of: 「

a

b

」

Parameters:

Name Type Description
outerDepth number

Number of nodes outside the selection to unwrap
innerDepth number

Number of nodes inside the selection to unwrap
Source:

Returns:

Type
ve.dm.SurfaceFragment
Unwrap nodes in the fragment out of one or more elements.

update([selection]) → {ve.dm.SurfaceFragment}chainable #

Update selection based on un-applied transactions in the surface, or specified selection.

Parameters:

Name Type Attributes Description
selection ve.dm.Selection optional

Optional selection to set
Source:

Returns:

Type
ve.dm.SurfaceFragment
Update selection based on un-applied transactions in the surface, or specified selection.

willAutoSelect() → {boolean} #

Check if the surface's selection will be updated automatically when changes are made.

Source:

Returns:

Will automatically update surface selection

Type
boolean
Check if the surface's selection will be updated automatically when changes are made.

willExcludeInsertions() → {boolean} #

Check whether updates to this fragment's selection will exclude content inserted at the boundaries.

Source:

Returns:

Selection updates will exclude insertions

Type
boolean
Check whether updates to this fragment's selection will exclude content inserted at the boundaries.

wrapAllNodes(wrapOuter, wrapEach) → {ve.dm.SurfaceFragment}chainable #

Wrap nodes in the fragment with one or more elements.

A wrapper object is a linear model element; a plain object containing a type property and an optional attributes property.

Example: // fragment is a selection of:

a

b

fragment.wrapAllNodes( { type: 'list', attributes: { style: 'bullet' } }, { type: 'listItem' } ) // fragment is now a selection of:

  • a

  • b

Example: // fragment is a selection of:

a

b

fragment.wrapAllNodes( [{ type: 'list', attributes: { style: 'bullet' } }, { type: 'listItem' }] ) // fragment is now a selection of:

  • a

    b

Parameters:

Name Type Description
wrapOuter Object | Array.<Object>

Opening element(s) to wrap around the range
wrapEach Object | Array.<Object>

Opening element(s) to wrap around each top-level element in the range
Source:

Returns:

Type
ve.dm.SurfaceFragment
Wrap nodes in the fragment with one or more elements.

wrapNodes(wrapper) → {ve.dm.SurfaceFragment}chainable #

Wrap each node in the fragment with one or more elements.

A wrapper object is a linear model element; a plain object containing a type property and an optional attributes property.

Example: // fragment is a selection of:

a

b

fragment.wrapNodes( [{ type: 'list', attributes: { style: 'bullet' } }, { type: 'listItem' }] ) // fragment is now a selection of:

  • a

  • b

Parameters:

Name Type Description
wrapper Object | Array.<Object>

Wrapper object, or array of wrapper objects (see above)

Properties:
Name Type Attributes Description
type string

Node type of wrapper
attributes Object optional

Attributes of wrapper
Source:

Returns:

Type
ve.dm.SurfaceFragment
Wrap each node in the fragment with one or more elements.