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

Returns:

Adjusted fragment

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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)

Returns:

Type
ve.dm.SurfaceFragment
Overrides:
Source:
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

Throws:

If fragment is null and selection is omitted

Type
Error
Inherited from:
Source:

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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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

Returns:

Clone of this fragment

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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.

Returns:

Collapsed fragment

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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.

Returns:

Collapsed fragment

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

containsOnlyText() → {boolean} #

Whether the fragment contains only text, allowing annotations

Returns:

Whether there's only text

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

Returns:

Promise which resolves with document model

Type
jQuery.Promise
Source:

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

Returns:

Type
ve.dm.SurfaceFragment
Overrides:
Source:
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

Returns:

Promise which resolves with source, or rejects

Type
jQuery.Promise
Source:

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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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

Returns:

Expanded fragment

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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 Default Description
all boolean optional
 false

Get annotations which only cover some of the fragment

Returns:

All annotation objects range is covered by

Type
ve.dm.AnnotationSet
Overrides:
Source:
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.

Returns:

List of nodes and related information

Type
Array
Inherited from:
Source:
See:
Get nodes covered by the fragment.

getData([deep]) → {Array.<ve.dm.LinearData.Item>} #

Get data for the fragment.

Parameters:

Name Type Attributes Description
deep boolean optional

Get a deep copy of the data

Returns:

Fragment data

Type
Array.<ve.dm.LinearData.Item>
Inherited from:
Source:
Get data for the fragment.

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

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

Returns:

Document of surface of fragment

Type
ve.dm.Document
Inherited from:
Source:
Get the document of the surface the fragment is a part of.

getLeafNodes() → {Array} #

Get all leaf nodes covered by the fragment.

Returns:

List of nodes and related information

Type
Array
Inherited from:
Source:
See:
Get all leaf nodes covered by the fragment.

getPending() → {jQuery.Promise} #

Get a promise that resolves when the pending list is complete

Returns:

Type
jQuery.Promise
Inherited from:
Source:
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.

Returns:

List of nodes and related information

Type
Array.<ve.dm.Node>
Inherited from:
Source:
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 Default Description
all boolean optional
 false

Include nodes and annotations which only cover some of the fragment

Returns:

Selected models

Type
Array.<ve.dm.Model>
Inherited from:
Source:
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.

Returns:

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

Type
ve.dm.Node | null
Inherited from:
Source:
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.

Returns:

The selection

Type
ve.dm.Selection
Inherited from:
Source:
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.

Returns:

List of nodes and related information

Type
Array
Inherited from:
Source:
See:
Get nodes covered by the fragment.

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

Get the surface the fragment is a part of.

Returns:

Surface of fragment

Type
ve.dm.Surface
Inherited from:
Source:
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

Returns:

Fragment text

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

Returns:

The fragment contains at least one annotation

Type
boolean
Inherited from:
Source:

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.

Returns:

Nodes have a matching ancestor

Type
boolean
Inherited from:
Source:
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.<ve.dm.LinearData.Item>

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

Content should be automatically annotated with annotations covering the selection / annotations at the current offset, or a set of annotations to annotate the content with. or an AnnotationSet from the current offset (calculated from the view)

Returns:

Type
ve.dm.SurfaceFragment
Overrides:
Source:
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 with annotations covering the selection / annotations at the current offset, or a set of annotations to annotate the content with. or an AnnotationSet from the current offset (calculated from the view)

Returns:

Type
ve.dm.SurfaceFragment
Overrides:
Source:
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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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.

Returns:

Fragment is a null fragment

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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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.

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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.

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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 Description
autoSelect boolean

Automatically update surface selection

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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.

Returns:

Trimmed fragment

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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)

Returns:

Truncated fragment

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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

Returns:

Type
ve.dm.SurfaceFragment
Inherited from:
Source:
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.

Returns:

Will automatically update surface selection

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

Returns:

Selection updates will exclude insertions

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

Returns:

Type
ve.dm.SurfaceFragment
Overrides:
Source:
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

Returns:

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