Expand all

ve.dm.SourceSurfaceFragment

Extends

Constructor

new ve.dm.SourceSurfaceFragment(doc) #

Surface fragment for editing surfaces in source mode.

Parameters:

Name Type Description
doc ve.dm.Document
Source:
Surface fragment for editing surfaces in source mode.

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

Returns:

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

clearPending() #

Clear a fragment's pending list

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

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

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

Inherited from:
Source:

Returns:

Whether there's only text

Type
boolean
Whether the fragment contains only text, allowing annotations

convertFromSource(source) → {jQuery.Promise} #

Convert source text to model slice

The default implementation converts from HTML synchronously.

If the conversion is asynchronous it should lock the surface until complete.

Parameters:

Name Type Description
source string

Source text
Source:

Returns:

Promise which resolves with document model

Type
jQuery.Promise

Convert source text to model slice

The default implementation converts from HTML synchronously.

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
Overrides:
Source:

Returns:

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

convertToSource(doc) → {jQuery.Promise} #

Convert model slice to source text

The default implementation converts to HTML synchronously.

If the conversion is asynchronous it should lock the surface until complete.

Parameters:

Name Type Description
doc ve.dm.Document
Source:

Returns:

Promise which resolves with source, or rejects

Type
jQuery.Promise

Convert model slice to source text

The default implementation converts to HTML synchronously.

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

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

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

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

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

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

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

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

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

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

Inherited from:
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.
Inherited from:
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)
Overrides:
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)
Overrides:
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
Inherited from:
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
Inherited from:
Source:
Insert new metadata into the document.

isNull() → {boolean} #

Check if the fragment is null.

Inherited from:
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
Inherited from:
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
Inherited from:
Source:
Push a promise to the fragment's pending list

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

Remove content in the fragment.

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

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

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

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

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

Returns:

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