Expand all

ve.dm.Surface

Constructor

new ve.dm.Surface(doc, [attachedRoot], [config]) #

DataModel surface for a node within a document

Methods do not check that ranges actually lie inside the surfaced node

Parameters:

Name Type Attributes Description
doc ve.dm.Document

Document model to create surface for
attachedRoot ve.dm.BranchNode optional

Branch node which is editable; default is document node
config Object optional

Configuration options

Properties:
Name Type Attributes Default Description
sourceMode boolean optional
 false

Source editing mode
Mixes in:
Source:

DataModel surface for a node within a document

Methods do not check that ranges actually lie inside the surfaced node

Methods

addInsertionAnnotations(annotations) #

Add an annotation to be used upon insertion.

Parameters:

Name Type Description
annotations ve.dm.Annotation | ve.dm.AnnotationSet

Insertion annotation to add
Source:

Fires:

Add an annotation to be used upon insertion.

applyAllStaging() #

Apply the staging stack until empty

Source:
Apply the staging stack until empty

applyStaging() #

Apply a level of staging from the staging stack

Source:

Fires:

Apply a level of staging from the staging stack

breakpoint() → {boolean} #

Set a history state breakpoint.

Source:

Returns:

A breakpoint was added

Type
boolean

Fires:

Set a history state breakpoint.

canRedo() → {boolean} #

Check if redo is allowed in the current state.

Source:

Returns:

Redo is allowed

Type
boolean
Check if redo is allowed in the current state.

canUndo() → {boolean} #

Check if undo is allowed in the current state.

Source:

Returns:

Undo is allowed

Type
boolean
Check if undo is allowed in the current state.

change(transactions, [selection]) #

Apply a transactions and selection changes to the document.

Parameters:

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

One or more transactions to process, or null to process none
selection ve.dm.Selection optional

Selection to apply
Source:
Apply a transactions and selection changes to the document.

changeInternal(transactions, [selection], [skipUndoStack])private #

Internal implementation of change(). Do not use this, use change() instead.

Parameters:

Name Type Attributes Default Description
transactions ve.dm.Transaction | Array.<ve.dm.Transaction> | null
selection ve.dm.Selection optional
skipUndoStack boolean optional
 false

If true, do not modify the undo stack. Used by undo/redo
Source:

Fires:

Internal implementation of change().

createSynchronizer(documentId, [config]) #

Create a surface synchronizer.

Must be created before the surface model is added to a view.

Parameters:

Name Type Attributes Description
documentId string

Document ID
config Object optional

Configuration options
Source:
Create a surface synchronizer.

doesStagingAllowUndo() → {boolean|undefined} #

Undo is allowed at the current staging stack depth

Source:

Returns:

Undo is allowed, or undefined if not staging

Type
boolean | undefined
Undo is allowed at the current staging stack depth

emitContextChange()private #

Emit a contextChange event. If #startQueueingContextChanges has been called, then the event is deferred until #stopQueueingContextChanges is called.

Source:

Fires:

Emit a contextChange event.
Grows a range so that any partially selected links are totally selected

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

Get the surfaced node

Deprecated:
  • Use getDocument().getAttachedRoot()
Source:

Returns:

The surfaced node

Type
ve.dm.BranchNode
Get the surfaced node

getAuthorId() → {number} #

Get the author ID

Source:

Returns:

The author ID

Type
number
Get the author ID

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

Get the document model.

Source:

Returns:

Document model of the surface

Type
ve.dm.Document
Get the document model.

getDom() → {HTMLDocument|string} #

Get the DOM representation of the surface's current state.

Source:

Returns:

HTML document (visual mode) or text (source mode)

Type
HTMLDocument | string
Get the DOM representation of the surface's current state.

getFragment([selection], [noAutoSelect], [excludeInsertions]) → {ve.dm.SurfaceFragment} #

Get a fragment for a selection.

Parameters:

Name Type Attributes Description
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:

Returns:

Surface fragment

Type
ve.dm.SurfaceFragment
Get a fragment for a selection.

getHistory() → {Array.<ve.dm.Surface.UndoStackItem>} #

Get a list of all applied history states.

Source:

Returns:

List of applied transaction stacks

Type
Array.<ve.dm.Surface.UndoStackItem>
Get a list of all applied history states.

getHtml() → {string} #

Get the HTML representation of the surface's current state.

Source:

Returns:

HTML

Type
string
Get the HTML representation of the surface's current state.

getInsertionAnnotations() → {ve.dm.AnnotationSet} #

Get annotations that will be used upon insertion.

Source:

Returns:

Insertion annotations

Type
ve.dm.AnnotationSet
Get annotations that will be used upon insertion.

getLinearFragment(range, [noAutoSelect], [excludeInsertions]) → {ve.dm.SurfaceFragment} #

Get a fragment for a linear selection's range.

Parameters:

Name Type Attributes Description
range ve.Range

Selection's range
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:

Returns:

Surface fragment

Type
ve.dm.SurfaceFragment
Get a fragment for a linear selection's range.

getModifiedRanges([options]) → {Array.<ve.Range>} #

Get a minimal set of ranges which have been modified by changes to the surface.

Parameters:

Name Type Attributes Description
options Object optional

Options

Properties:
Name Type Attributes Description
includeCollapsed boolean optional

Include collapsed ranges (removed content)
includeInternalList boolean optional

Include changes within the internal list
excludeAnnotations boolean optional

Exclude annotation-only changes
excludeAttributes boolean optional

Exclude attribute changes
Source:

Returns:

Modified ranges

Type
Array.<ve.Range>
Get a minimal set of ranges which have been modified by changes to the surface.

getOffsetFromSourceOffset(offset) → {number} #

Get a VE source-mode surface offset from a plaintext source offset.

Parameters:

Name Type Description
offset number

Source text offset
Source:

Returns:

Surface offset

Type
number

Throws:

Offset out of bounds

Type
Error
Get a VE source-mode surface offset from a plaintext source offset.

getRangeFromSourceOffsets(from, [to]) → {ve.Range} #

Get a VE source-mode surface range from plaintext source offsets.

Parameters:

Name Type Attributes Description
from number

Source text from offset
to number optional

Source text to offset, omit for a collapsed range
Source:

Returns:

Source surface offset

Type
ve.Range
Get a VE source-mode surface range from plaintext source offsets.

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

Get the cached selected node covering the current selection, or null

Source:

Returns:

Selected node

Type
ve.dm.Node | null
Get the cached selected node covering the current selection, or null

getSelectedNodeFromSelection([selection]) → {ve.dm.Node|null} #

Get the selected node covering a specific selection, or null

Parameters:

Name Type Attributes Description
selection ve.dm.Selection optional

Selection, defaults to the current selection
Source:

Returns:

Selected node

Type
ve.dm.Node | null
Get the selected node covering a specific selection, or null

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

Get the selection.

Source:

Returns:

Current selection

Type
ve.dm.Selection
Get the selection.

getSourceOffsetFromOffset(offset) → {number} #

Get a plaintext source offset from a VE source-mode surface offset.

Parameters:

Name Type Description
offset number

Surface offset
Source:

Returns:

Source text offset

Type
number

Throws:

Offset out of bounds

Type
Error
Get a plaintext source offset from a VE source-mode surface offset.

getStaging() → {ve.dm.Surface.StagingState|undefined} #

Get the staging state at the current staging stack depth

Source:

Returns:

staging Staging state object, or undefined if not staging

Type
ve.dm.Surface.StagingState | undefined
Get the staging state at the current staging stack depth

getStagingTransactions() → {Array.<ve.dm.Transaction>|undefined} #

Get the staging transactions at the current staging stack depth

The array is returned by reference so it can be pushed to.

Source:

Returns:

Staging transactions, or undefined if not staging

Type
Array.<ve.dm.Transaction> | undefined

Get the staging transactions at the current staging stack depth

The array is returned by reference so it can be pushed to.

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

Get the selection translated for the transaction that's being committed, if any.

Source:

Returns:

Current selection translated for new transaction

Type
ve.dm.Selection
Get the selection translated for the transaction that's being committed, if any.

hasBeenModified() → {boolean} #

Check if the surface has been modified.

This only checks if there are transactions which haven't been undone.

Source:

Returns:

The surface has been modified

Type
boolean
Check if the surface has been modified.

initialize() #

Initialize the surface model

Source:

Fires:

Initialize the surface model

isMultiUser() → {boolean} #

Check if the surface is in multi-user mode

Source:

Returns:

Surface is in multi-user mode

Type
boolean
Check if the surface is in multi-user mode

isReadOnly() → {boolean} #

Check if the surface is read-only

Source:

Returns:

Type
boolean
Check if the surface is read-only

isStaging() → {boolean} #

If the surface in staging mode.

Source:

Returns:

The surface in staging mode

Type
boolean
If the surface in staging mode.

onDocumentPreCommit(tx) #

Update translatedSelection early (before the commit actually occurs)

This is so ve.ce.ContentBranchNode#getRenderedContents can consider the translated selection for unicorn rendering.

Parameters:

Name Type Description
tx ve.dm.Transaction

Transaction that's about to be committed
Source:

Update translatedSelection early (before the commit actually occurs)

This is so ve.ce.ContentBranchNode#getRenderedContents can consider the translated selection for unicorn rendering.

onDocumentTransact(tx) #

Respond to transactions processed on the document by translating the selection and updating other state.

Parameters:

Name Type Description
tx ve.dm.Transaction

Transaction that was processed
Source:

Fires:

Respond to transactions processed on the document by translating the selection and updating other state.

popAllStaging() → {Array.<ve.dm.Transaction>|undefined} #

Pop the staging stack until empty

Source:

Returns:

Staging transactions, or undefined if not staging

Type
Array.<ve.dm.Transaction> | undefined
Pop the staging stack until empty

popStaging() → {Array.<ve.dm.Transaction>|undefined} #

Pop a level of staging from the staging stack

Source:

Returns:

Staging transactions, or undefined if not staging

Type
Array.<ve.dm.Transaction> | undefined

Fires:

Pop a level of staging from the staging stack

pushStaging([allowUndo]) #

Push another level of staging to the staging stack

Parameters:

Name Type Attributes Default Description
allowUndo boolean optional
 false

Allow undo while staging
Source:

Fires:

Push another level of staging to the staging stack

redo() #

Step forwards in history.

Source:

Fires:

Step forwards in history.

removeDocStateAndChanges() #

Remove the auto-saved document state and stashed changes

Source:
Remove the auto-saved document state and stashed changes

removeInsertionAnnotations(annotations) #

Remove an annotation from those that will be used upon insertion.

Parameters:

Name Type Description
annotations ve.dm.Annotation | ve.dm.AnnotationSet

Insertion annotation to remove
Source:

Fires:

Remove an annotation from those that will be used upon insertion.

resetHistoryTrackingInterval() #

Reset the timer for automatic history-tracking

Source:
Reset the timer for automatic history-tracking

restoreChanges() → {boolean} #

Restore transactions from session storage

Source:

Returns:

Some changes were restored

Type
boolean

Throws:

Failed to restore auto-saved session

Type
Error
Restore transactions from session storage

setAuthorId(authorId) #

Set the author ID

Parameters:

Name Type Description
authorId number

The new author ID
Source:
Set the author ID

setAutosaveDocId(docId) #

Set an document ID for autosave.

For session storage this is only required if there is more than one document on the page.

Parameters:

Name Type Description
docId string

Document ID.
Source:
Set an document ID for autosave.

setInsertionAnnotations(annotations) #

Set annotations that will be used upon insertion.

Parameters:

Name Type Description
annotations ve.dm.AnnotationSet | null

Insertion annotations to use or null to disable them
Source:

Fires:

Set annotations that will be used upon insertion.

setLinearSelection(range) #

Set a linear selection at a specified range on the model

Parameters:

Name Type Description
range ve.Range

Range to create linear selection at
Source:
Set a linear selection at a specified range on the model

setMultiUser(multiUser) #

Set the surface multi-user mode

Parameters:

Name Type Description
multiUser boolean

Multi-user mode
Source:
Set the surface multi-user mode

setNullSelection() #

Set a null selection on the model

Source:
Set a null selection on the model

setReadOnly(readOnly) #

Set the read-only state of the surface

Parameters:

Name Type Description
readOnly boolean

Make surface read-only
Source:
Set the read-only state of the surface

setSelection(selection) #

Change the selection

Parameters:

Name Type Description
selection ve.dm.Selection

New selection
Source:

Fires:

Change the selection

setStorage(storage, [storageExpiry]) #

Set the storage interface for autosave

Parameters:

Name Type Attributes Description
storage ve.init.ConflictableStorage

Storage interface
storageExpiry number optional

Storage expiry time in seconds
Source:
Set the storage interface for autosave

startHistoryTracking() #

Start tracking state changes in history.

Source:
Start tracking state changes in history.

startQueueingContextChanges()private #

Start queueing up calls to #emitContextChange until #stopQueueingContextChanges is called. While queueing is active, contextChanges are also collapsed, so if #emitContextChange is called multiple times, only one contextChange event will be emitted by #stopQueueingContextChanges.

this.emitContextChange(); // emits immediately
this.startQueueingContextChanges();
this.emitContextChange(); // doesn't emit
this.emitContextChange(); // doesn't emit
this.stopQueueingContextChanges(); // emits one contextChange event
Source:
Start queueing up calls to #emitContextChange until #stopQueueingContextChanges is called.

startStoringChanges() #

Start storing changes after every undoStackChange

Source:
Start storing changes after every undoStackChange

stopHistoryTracking() #

Stop tracking state changes in history.

Source:
Stop tracking state changes in history.

stopQueueingContextChanges()private #

Stop queueing contextChange events. If #emitContextChange was called previously, a contextChange event will now be emitted. Any future calls to #emitContextChange will once again emit the event immediately.

Source:

Fires:

Stop queueing contextChange events.

stopStoringChanges() #

Stop storing changes

Source:
Stop storing changes

storeChanges() #

Store latest transactions into session storage

Source:

Fires:

Store latest transactions into session storage

storeDocState([state], [html]) → {boolean} #

Store a snapshot of the current document state.

If custom HTML is provided, the caller must manually set the lastStoredChange pointer to the correct value.

Parameters:

Name Type Attributes Description
state Object optional

JSONable object describing document state
html string optional

Document HTML, will generate from current state if not provided
Source:

Returns:

Doc state was successfully stored

Type
boolean
Store a snapshot of the current document state.

storeDocStorage() #

Store persistent document storage into session storage

Source:
Store persistent document storage into session storage

truncateUndoStack() #

Prevent future states from being redone.

Callers should eventually emit a 'history' event after using this method.

Source:

Fires:

Prevent future states from being redone.

undo() #

Step backwards in history.

Source:

Fires:

Step backwards in history.

updateDocState(state) → {boolean} #

Update stored document state metadata, without changing the HTML

Parameters:

Name Type Description
state Object

Document state
Source:

Returns:

Document metadata was successfully stored

Type
boolean
Update stored document state metadata, without changing the HTML

updateExpiry([skipKeys]) #

Update the expiry value of keys in use

Parameters:

Name Type Attributes Description
skipKeys Array.<string> optional

Keys to skip (because they have just been updated)
Source:
Update the expiry value of keys in use

Type Definitions

StagingState #

Type:

Properties:

Name Type Description
transactions Array.<ve.dm.Transaction>

Staging transactions
selectionBefore ve.dm.Selection

Selection before transactions were applied
allowUndo boolean

Allow undo while staging
Source:

UndoStackItem #

Type:

Properties:

Name Type Description
start number
transactions Array.<ve.dm.Transaction>
selection ve.dm.Selection
selectionBefore ve.dm.Selection
Source:

Events

autosaveFailed() #

Auto-save failed to store a change

Source:
Auto-save failed to store a change

blur() #

The selection was just set to a null selection

Source:
The selection was just set to a null selection

contextChange() #

Source:

documentUpdate(tx) #

Emitted when a transaction has been processed on the document and the selection has been translated to account for that transaction. You should only use this event if you need to access the selection; in most cases, you should use {ve.dm.Document#event-transact}.

Parameters:

Name Type Description
tx ve.dm.Transaction

Transaction that was processed on the document
Source:

Emitted when a transaction has been processed on the document and the selection has been translated to account for that transaction.

focus() #

The selection was just set to a non-null selection

Source:
The selection was just set to a non-null selection

history() #

Emitted when the history stacks change, or the ability to use them changes.

Source:
Emitted when the history stacks change, or the ability to use them changes.

insertionAnnotationsChange(insertionAnnotations) #

Parameters:

Name Type Description
insertionAnnotations ve.dm.AnnotationSet

AnnotationSet being inserted
Source:

select(selection) #

Parameters:

Name Type Description
selection ve.dm.Selection
Source:

undoStackChange() #

Emitted when the main undo stack changes (this.undoStack or this.undoIndex).

Source:
Emitted when the main undo stack changes (this.undoStack or this.undoIndex).