Expand all

ve

Namespace for all VisualEditor classes, static methods and static properties.

Namespaces

ce
Namespace for all VisualEditor ContentEditable classes, static methods and static properties.
dm
Namespace for all VisualEditor DataModel classes, static methods and static properties.
init
Namespace for all VisualEditor Initialization classes, static methods and static properties.
ui
Namespace for all VisualEditor UserInterface classes, static methods and static properties.

Classes

BranchNode
Branch node mixin.
DiffMatchPatch
DiffMatchPatch implementation
DiffTreeNode
Tree node for conducting a tree diff.
Document
Generic document.
EventSequencer
EventSequencer class with on-event and after-event listeners.
EventSequencer

To fire after-event listeners promptly, the EventSequencer may need to listen to some events for which it has no registered on-event or after-event listeners.

Filibuster

A scrupulous event logger that logs state at every function call, and shortlists potentially significant observations for strict scrutiny.

Filibuster
LeafNode
Leaf node mixin.
Node
Generic node.
PositionStep
Range
Scheduler
SelectionState

Like the DOM Selection object, but not updated live from the actual selection

WARNING: the Nodes are still live and mutable, which can change the meaning of the offsets or invalidate the value of isBackwards.

TriggerListener
Trigger listener

Properties

debugstatic #

Properties:

Name Type Description
debug boolean
Source:

deepFreezestatic #

Deep freeze an object, making it immutable

Original object properties are overwritten with frozen versions.

Source:

Deep freeze an object, making it immutable

Original object properties are overwritten with frozen versions.

deepFreezestatic #

Deep freeze an object, making it immutable

This implementation does nothing, to add a real implementation ve.freeze needs to be loaded.

Source:

Deep freeze an object, making it immutable

This implementation does nothing, to add a real implementation ve.freeze needs to be loaded.

dirstatic #

Logs an object to the console.

Source:
Logs an object to the console.

dirstatic #

Log an object to the console.

This implementation does nothing, to add a real implementation ve.debug needs to be loaded.

Source:
Log an object to the console.

entriesstatic #

Same as Object.entries, because we don't yet presume ES2017

Source:
Same as Object.entries, because we don't yet presume ES2017

errorstatic #

Logs error to the console.

Source:
Logs error to the console.

errorstatic #

Log error to the console.

This implementation does nothing, to add a real implementation ve.debug needs to be loaded.

Source:
Log error to the console.

escapeHtmlstatic #

Escape non-word characters so they can be safely used as HTML attribute values.

Source:
Escape non-word characters so they can be safely used as HTML attribute values.

logstatic #

Logs data to the console.

Source:
Logs data to the console.

logstatic #

Log data to the console.

This implementation does nothing, to add a real implementation ve.debug needs to be loaded.

Source:
Log data to the console.

supportsSelectionExtendprivatestatic #

Feature detect if the browser supports extending selections

Should work everywhere except IE

Properties:

Type Description
boolean
Source:

Feature detect if the browser supports extending selections

Should work everywhere except IE

Methods

VisualEditorSupportCheck() → {boolean}static #

Check whether the environment has the needed features to load VisualEditor. This considers every ES5 feature, support for contentEditable itself, those specific DOM features we use, and SVG support for the user interface. As we use this to check for feature compatibility this file must be ES3-parsable.

Source:

Returns:

True if the environment should support VisualEditor.

Type
boolean
Check whether the environment has the needed features to load VisualEditor.

addHeadTag(docHtml, tagHtml) → {string}static #

Add a tag to <head> using HTML string splicing

Parameters:

Name Type Description
docHtml string

Document HTML
tagHtml string

Tag HTML to be added to <head>
Source:

Returns:

Document HTML

Type
string
Add a tag to <head> using HTML string splicing

adjacentDomPosition(position, direction, options) → {ve.DomPosition}static #

Get the closest matching DOM position in document order (forward or reverse)

A DOM position is represented as an object with "node" and "offset" properties.

The noDescend option can be used to exclude the positions inside certain element nodes; it is a jQuery selector/function ( used as a test by $node.is() - see http://api.jquery.com/is/ ); it defaults to ve.rejectsCursor . Void elements (those matching ve.isVoidElement) are always excluded.

As well as the end position, an array of ve.PositionSteps (node traversals) is returned. The "stop" option is a boolean-valued function used to test each ve.PositionStep in turn. If If it returns true, the position arrived at is returned; else the stepping continues to the next matching DOM position. It defaults to ve.isHardCursorStep .

Limitation: some DOM positions cannot actually hold the cursor; e.g. the start of the interior of a table node. Browser cursoring jumps over text node/annotation node boundaries as if they were invisible, and skips over most grapheme clusters e.g. 'x\u0301' (though not all e.g. '\u062D\u0627'). Also, Chromium normalizes cursor focus/offset, when they are set, to the start-most such cursor position (Firefox does not).

Parameters:

Name Type Description
position Object

Start position

Properties:
Name Type Description
node Node

Start node
offset number

Start offset
direction number

+1 for forward, -1 for reverse
options Object
Properties:
Name Type Attributes Description
noDescend function | string optional

Selector or function: nodes to skip over
stop function optional

Boolean-valued ve.PositionStep test function
Source:
See:

Returns:

The adjacent DOM position encountered

Type
ve.DomPosition

Get the closest matching DOM position in document order (forward or reverse)

A DOM position is represented as an object with "node" and "offset" properties.

appendToRel(element, value)static #

Add a value to an element's rel attribute if it's not already present

Rel is like class: it's actually a set, represented as a string. We don't want to add the same value to the attribute if this function is called repeatedly. This is mostly a placeholder for the relList property someday becoming widely supported.

Parameters:

Name Type Description
element HTMLElement

DOM element whose attribute should be checked
value string

New rel value to be added
Source:

Add a value to an element's rel attribute if it's not already present

Rel is like class: it's actually a set, represented as a string.

batchPush(arr, data) → {number}static #

Push one array into another.

This is the equivalent of arr.push( d1, d2, d3, … ) except that arguments are specified as an array rather than separate parameters.

Parameters:

Name Type Description
arr Array | ve.dm.BranchNode

Object supporting .push() to insert at the end of the array. Will be modified
data Array

Array of items to insert.
Source:

Returns:

length of the new array

Type
number
Push one array into another.

batchSplice(arr, offset, remove, data) → {Array}static #

Splice one array into another.

This is the equivalent of arr.splice( offset, remove, d1, d2, d3, … ) except that arguments are specified as an array rather than separate parameters.

This method has been proven to be faster than using slice and concat to create a new array, but performance tests should be conducted on each use of this method to verify this is true for the particular use. Also, browsers change fast, never assume anything, always test everything.

Includes a replacement for broken implementations of Array.prototype.splice().

Parameters:

Name Type Description
arr Array | ve.dm.BranchNode

Target object (must have splice method, object will be modified)
offset number

Offset in arr to splice at. This MUST NOT be negative, unlike the 'index' parameter in Array#splice.
remove number

Number of elements to remove at the offset. May be zero
data Array

Array of items to insert at the offset. Must be non-empty if remove=0
Source:

Returns:

Array of items removed

Type
Array
Splice one array into another.

binarySearch(arr, searchFunc, [forInsertion]) → {number|null}static #

Use binary search to locate an element in a sorted array.

searchFunc is given an element from the array. searchFunc(elem) must return a number above 0 if the element we're searching for is to the right of (has a higher index than) elem, below 0 if it is to the left of elem, or zero if it's equal to elem.

To search for a specific value with a comparator function (a function cmp(a,b) that returns above 0 if a > b, below 0 if a < b, and 0 if a == b), you can use searchFunc = cmp.bind( null, value ).

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Attributes Description
arr Array

Array to search in
searchFunc function

Search function
forInsertion boolean optional

If not found, return index where val could be inserted
Source:

Returns:

Index where val was found, or null if not found

Type
number | null
Use binary search to locate an element in a sorted array.

cloneObject(origin) → {Object}static #

Create a new object that is an instance of the same constructor as the input, inherits from the same object and contains the same own properties.

This makes a shallow non-recursive copy of own properties. To create a recursive copy of plain objects, use #copy.

var foo = new Person( mom, dad );
foo.setAge( 21 );
var foo2 = OO.cloneObject( foo );
foo.setAge( 22 );

// Then
foo2 !== foo; // true
foo2 instanceof Person; // true
foo2.getAge(); // 21
foo.getAge(); // 22

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Description
origin Object
Source:

Returns:

Clone of origin

Type
Object

Create a new object that is an instance of the same constructor as the input, inherits from the same object and contains the same own properties.

compare(a, b, [asymmetrical]) → {boolean}static #

Recursively compare properties between two objects.

A false result may be caused by property inequality or by properties in one object missing from the other. An asymmetrical test may also be performed, which checks only that properties in the first object are present in the second object, but not the inverse.

If either a or b is null or undefined it will be treated as an empty object.

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Attributes Description
a Object | undefined | null

First object to compare
b Object | undefined | null

Second object to compare
asymmetrical boolean optional

Whether to check only that a's values are equal to b's (i.e. a is a subset of b)
Source:

Returns:

If the objects contain the same values as each other

Type
boolean
Recursively compare properties between two objects.

compareClassLists(classList1, classList2) → {boolean}static #

Compare two class lists, either whitespace separated strings or arrays

Class lists are equivalent if they contain the same members, excluding duplicates and ignoring order.

Parameters:

Name Type Description
classList1 Array.<string> | string

First class list
classList2 Array.<string> | string

Second class list
Source:

Returns:

Class lists are equivalent

Type
boolean

Compare two class lists, either whitespace separated strings or arrays

Class lists are equivalent if they contain the same members, excluding duplicates and ignoring order.

compareDocumentOrder(node1, offset1, node2, offset2) → {number|null}static #

Compare two nodes for position in document

Return null if either position is either null or incomparable (e.g. where one of the nodes is detached or the nodes are from different documents).

Parameters:

Name Type Description
node1 Node | null

First node
offset1 number | null

First offset
node2 Node | null

Second node
offset2 number | null

Second offset
Source:

Returns:

negative, zero or positive number, or null if nodes null or incomparable

Type
number | null

Compare two nodes for position in document

Return null if either position is either null or incomparable (e.g.

compareTuples(a, b) → {number}static #

Compare two tuples in lexicographical order.

This function first compares a[0] with b[0], then a[1] with b[1], etc. until it encounters a pair where a[k] != b[k]; then returns a[k] - b[k].

If a[k] == b[k] for every k, this function returns 0.

If a and b are of unequal length, but a[k] == b[k] for all k that exist in both a and b, then this function returns Infinity (if a is longer) or -Infinity (if b is longer).

Parameters:

Name Type Description
a Array.<number>

First tuple
b Array.<number>

Second tuple
Source:

Returns:

a[k] - b[k] where k is the lowest k such that a[k] != b[k]

Type
number
Compare two tuples in lexicographical order.

config(key) → {any|Object}static #

Get platform config value(s)

Parameters:

Name Type Description
key string | Array.<string>

Config key, or list of keys
Source:

Returns:

Config value, or keyed object of config values if list of keys provided

Type
any | Object
Get platform config value(s)

convertDomElements(value) → {Object}privatestatic #

Callback for #copy to convert nodes to a comparable summary.

Parameters:

Name Type Description
value Object

Value in the object/array
Source:

Returns:

DOM element summary if value is a node, otherwise just the value

Type
Object
Callback for #copy to convert nodes to a comparable summary.

copy(source, [leafCallback], [nodeCallback]) → {Object}static #

Create a plain deep copy of any kind of object.

Copies are deep, and will either be an object or an array depending on source.

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Attributes Description
source Object

Object to copy
leafCallback function optional

Applied to leaf values after they are cloned but before they are added to the clone
nodeCallback function optional

Applied to all values before they are cloned. If the nodeCallback returns a value other than undefined, the returned value is used instead of attempting to clone.
Source:

Returns:

Copy of source object

Type
Object
Create a plain deep copy of any kind of object.

copyDomElements(domElements, [doc]) → {Array.<HTMLElement>}static #

Copy an array of DOM elements, optionally into a different document.

Parameters:

Name Type Attributes Description
domElements Array.<HTMLElement>

DOM elements to copy
doc HTMLDocument optional

Document to create the copies in; if unset, simply clone each element
Source:

Returns:

Copy of domElements with copies of each element

Type
Array.<HTMLElement>
Copy an array of DOM elements, optionally into a different document.

countEdgeMatches(before, after, [equals]) → {ve.ChangeOffsets|null}static #

Count the common elements at the start and end of two sequences

Parameters:

Name Type Attributes Description
before Array | string

The original sequence
after Array | string

The modified sequence
equals function optional

Two-argument comparison returning boolean (defaults to ===)
Source:

Returns:

Change offsets (valid in both sequences), or null if unchanged

Type
ve.ChangeOffsets | null
Count the common elements at the start and end of two sequences

createDeferred() → {jQuery.Deferred}static #

Create a jQuery.Deferred-compatible object

See http://api.jquery.com/jQuery.Deferred/

Source:

Returns:

Type
jQuery.Deferred

Create a jQuery.Deferred-compatible object

See http://api.jquery.com/jQuery.Deferred/

createDocumentFromHtml(html) → {HTMLDocument}static #

Create an HTMLDocument from an HTML string.

The html parameter is supposed to be a full HTML document with a doctype and an <html> tag. If you pass a document fragment, it will be wrapped in <body>…</body>.

To create an empty document, pass the empty string.

If your input is both valid HTML and valid XML, and you need to work around style normalization bugs in Internet Explorer, use #parseXhtml and #serializeXhtml.

Parameters:

Name Type Description
html string
Source:

Returns:

Document constructed from the HTML string

Type
HTMLDocument
Create an HTMLDocument from an HTML string.

debounce()static #

Source:
See:

deleteProp(obj, […keys])static #

Delete a deeply nested property of an object using variadic arguments, protecting against undefined property errors, and deleting resulting empty objects.

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Attributes Description
obj Object
keys any optional
repeatable
Source:

Delete a deeply nested property of an object using variadic arguments, protecting against undefined property errors, and deleting resulting empty objects.

extendObject([recursive], [target], […sources]) → {any}static #

Merge properties of one or more objects into another. Preserves original object's inheritance (e.g. Array, Object, whatever). In case of array or array-like objects only the indexed properties are copied over. Beware: If called with only one argument, it will consider 'target' as 'source' and 'this' as 'target'. Which means ve.extendObject( { a: 1 } ); sets ve.a = 1;

See http://api.jquery.com/jQuery.extend/

Parameters:

Name Type Attributes Default Description
recursive boolean optional
 false
target any optional

Object that will receive the new properties
sources any optional
repeatable

Variadic list of objects containing properties to be merged into the target.
Source:

Returns:

Modified version of first or second argument

Type
any
Merge properties of one or more objects into another.

filterMetaElements(contents) → {Array.<Node>}static #

Filter out metadata elements

Parameters:

Name Type Description
contents Array.<Node>

DOM nodes
Source:

Returns:

Filtered DOM nodes

Type
Array.<Node>
Filter out metadata elements

fixBase(targetDoc, sourceDoc, [fallbackBase])static #

Take a target document with a possibly relative base URL, and modify it to be absolute. The base URL of the target document is resolved using the base URL of the source document.

Note that the fallbackBase parameter will be used if there is no tag, even if the document does have a valid base URL: this is to work around Firefox's behavior of having documents created by DOMParser inherit the base URL of the main document.

Parameters:

Name Type Attributes Description
targetDoc HTMLDocument

Document whose base URL should be resolved
sourceDoc HTMLDocument

Document whose base URL should be used for resolution
fallbackBase string optional

Base URL to use if resolving the base URL fails or there is no tag
Source:
Take a target document with a possibly relative base URL, and modify it to be absolute.

fixSelectionNodes(selection)static #

Workaround for catastrophic Firefox bug (T209646)

Support: Firefox <= ~70 anchorNode and focusNode return unusable 'Restricted' object when focus is in a number input: https://bugzilla.mozilla.org/show_bug.cgi?id=1495482 This task was resolved around late 2019

Parameters:

Name Type Description
selection Selection

Native selection
Source:

Workaround for catastrophic Firefox bug (T209646)

Support: Firefox <= ~70 anchorNode and focusNode return unusable 'Restricted' object when focus is in a number input: https://bugzilla.mozilla.org/show_bug.cgi?id=1495482 This task was resolved around late 2019

fixupPreBug(element) → {HTMLElement}static #

Helper function for #properInnerHtml, #properOuterHtml and #serializeXhtml.

Detect whether the browser has broken <pre> serialization, and if so return a clone of the node with extra newlines added to make it serialize properly. If the browser is not broken, just return the original node.

Parameters:

Name Type Description
element HTMLElement

HTML element to fix up
Source:

Returns:

Either element, or a fixed-up clone of it

Type
HTMLElement
Helper function for #properInnerHtml, #properOuterHtml and #serializeXhtml.

getByteOffset(text, clusterOffset) → {number}static #

Convert a grapheme cluster offset to a byte offset.

Parameters:

Name Type Description
text string

Text in which to calculate offset
clusterOffset number

Grapheme cluster offset
Source:

Returns:

Byte offset

Type
number
Convert a grapheme cluster offset to a byte offset.

getClusterOffset(text, byteOffset) → {number}static #

Convert a byte offset to a grapheme cluster offset.

Parameters:

Name Type Description
text string

Text in which to calculate offset
byteOffset number

Byte offset
Source:

Returns:

Grapheme cluster offset

Type
number
Convert a byte offset to a grapheme cluster offset.

getCommonAncestor(nodes) → {Node|null}static #

Find the nearest common ancestor of DOM nodes

Parameters:

Name Type Description
nodes Node | null

DOM nodes
Source:

Returns:

Nearest common ancestor; or null if there is none / an argument is null

Type
Node | null
Find the nearest common ancestor of DOM nodes

getCommonStartSequenceLength(sequences) → {number}static #

Find the length of the common start sequence of one or more sequences

Items are tested for sameness using === .

Parameters:

Name Type Description
sequences Array

Array of sequences (arrays, strings etc)
Source:

Returns:

Common start sequence length (0 if sequences is empty)

Type
number

Find the length of the common start sequence of one or more sequences

Items are tested for sameness using === .

getDomAttributes(element) → {Object}static #

Get the attributes of a DOM element as an object with key/value pairs.

Parameters:

Name Type Description
element HTMLElement
Source:

Returns:

Type
Object
Get the attributes of a DOM element as an object with key/value pairs.

getDomElementSummary(element, [includeHtml], [getAttributeSummary]) → {Object}privatestatic #

Build a summary of an HTML element.

Summaries include node name, text, attributes and recursive summaries of children. Used for serializing or comparing HTML elements.

Parameters:

Name Type Attributes Default Description
element HTMLElement

Element to summarize
includeHtml boolean optional
 false

Include an HTML summary for element nodes
getAttributeSummary function optional

Callback to modify the summary of an attribute

Properties:
Name Type Attributes Description
name string optional

Name of the attribute to modify.
value string optional

Value to return for the given attribute.
Source:

Returns:

Summary of element.

Type
Object
Build a summary of an HTML element.

getNodeHtml(node) → {string}static #

Get an HTML representation of a DOM element node, text node or comment node

Parameters:

Name Type Description
node Node

The DOM node
Source:

Returns:

HTML representation of the node

Type
string
Get an HTML representation of a DOM element node, text node or comment node

getObjectValues(obj) → {Array}static #

Get an array of all property values in an object.

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Description
obj Object

Object to get values from
Source:

Returns:

List of object values

Type
Array
Get an array of all property values in an object.

getOffsetPath(ancestor, node, nodeOffset) → {Array.<number>}static #

Get the offset path from ancestor to offset in descendant

Parameters:

Name Type Description
ancestor Node

The ancestor node
node Node

The descendant node
nodeOffset number

The offset in the descendant node
Source:

Returns:

The offset path

Type
Array.<number>
Get the offset path from ancestor to offset in descendant

getProp(obj, […keys]) → {Object|undefined}static #

Get a deeply nested property of an object using variadic arguments, protecting against undefined property errors.

quux = OO.getProp( obj, 'foo', 'bar', 'baz' ); is equivalent to quux = obj.foo.bar.baz; except that the former protects against JS errors if one of the intermediate properties is undefined. Instead of throwing an error, this function will return undefined in that case.

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Attributes Description
obj Object
keys any optional
repeatable
Source:

Returns:

obj[arguments[1]][arguments[2]].... or undefined

Type
Object | undefined

Get a deeply nested property of an object using variadic arguments, protecting against undefined property errors.

getStartAndEndRects(rects) → {Object.<string, Object>|null}static #

Get the start and end rectangles (in a text flow sense) from a list of rectangles

The start rectangle is the top-most, and the end rectangle is the bottom-most.

Parameters:

Name Type Description
rects Array.<Object> | null

Full list of rectangles
Source:

Returns:

Object containing two rectangles: start and end, or null if there are no rectangles

Type
Object.<string, Object> | null

Get the start and end rectangles (in a text flow sense) from a list of rectangles

The start rectangle is the top-most, and the end rectangle is the bottom-most.

getSystemPlatform() → {string}static #

Get the client platform string from the browser.

FIXME T126036: This is a wrapper for calling getSystemPlatform() on the current platform except that if the platform hasn't been constructed yet, it falls back to using the base class implementation in {ve.init.Platform}. A proper solution would be not to need this information before the platform is constructed.

Source:
See:

Returns:

Client platform string

Type
string
Get the client platform string from the browser.

graphemeSafeSubstring(text, start, end, [outer]) → {string}static #

Get a text substring, taking care not to split grapheme clusters.

Parameters:

Name Type Attributes Default Description
text string

Text to take the substring from
start number

Start offset
end number

End offset
outer boolean optional
 false

Include graphemes if the offset splits them
Source:

Returns:

Substring of text

Type
string
Get a text substring, taking care not to split grapheme clusters.

htmlMsg(key, […params]) → {Array.<Node>}static #

Get an HTML localized message with HTML or DOM arguments.

Parameters:

Name Type Attributes Description
key string

Message key
params any optional
repeatable

Message parameters
Source:

Returns:

Localized message

Type
Array.<Node>
Get an HTML localized message with HTML or DOM arguments.

initFilibuster()static #

Initialize ve.filibuster

ve.filibuster will monitor calls in ve.{dm,ce,ui} and DM / DOM changes

Source:

Initialize ve.filibuster

ve.filibuster will monitor calls in ve.{dm,ce,ui} and DM / DOM changes

insertIntoArray(arr, offset, src)static #

Insert one array into another.

Shortcut for ve.batchSplice( arr, offset, 0, src ).

Parameters:

Name Type Description
arr Array | ve.dm.BranchNode

Target object (must have splice method)
offset number

Offset in arr where items will be inserted
src Array

Items to insert at offset
Source:
See:
Insert one array into another.

isBlockElement(element) → {boolean}static #

Check whether a given DOM element has a block element type.

Parameters:

Name Type Description
element HTMLElement | string

Element or element name
Source:

Returns:

Element is a block element

Type
boolean
Check whether a given DOM element has a block element type.

isClipboardDataFormatsSupported(e, [customTypes]) → {boolean}static #

Are multiple formats for clipboardData items supported?

If you want to use unknown formats, an additional check for whether we're on MS Edge needs to be made, as that only supports standard plain text / HTML.

Parameters:

Name Type Attributes Description
e jQuery.Event

A jQuery event object for a copy/paste event
customTypes boolean optional

Check whether non-standard formats are supported
Source:

Returns:

Whether multiple clipboardData item formats are supported

Type
boolean

Are multiple formats for clipboardData items supported?

If you want to use unknown formats, an additional check for whether we're on MS Edge needs to be made, as that only supports standard plain text / HTML.

isContentEditable(node) → {boolean}static #

Check whether a given node is contentEditable

Handles 'inherit', via checking isContentEditable. Knows to check for text nodes, and will return whether the text node's parent is contentEditable.

Parameters:

Name Type Description
node HTMLElement | Text

Node to check contenteditable status of
Source:

Returns:

Node is contenteditable

Type
boolean

Check whether a given node is contentEditable

Handles 'inherit', via checking isContentEditable.

isEmptyObject(obj) → {boolean}static #

Check to see if an object is empty (contains no properties).

See http://api.jquery.com/jQuery.isEmptyObject/

Parameters:

Name Type Description
obj Object

The object that will be checked to see if it's empty
Source:

Returns:

Type
boolean
Check to see if an object is empty (contains no properties).

isEqualDomElements(domElements1, domElements2) → {boolean}static #

Check if two arrays of DOM elements are equal (according to .isEqualNode())

Parameters:

Name Type Description
domElements1 Array.<HTMLElement>

First array of DOM elements
domElements2 Array.<HTMLElement>

Second array of DOM elements
Source:

Returns:

All elements are pairwise equal

Type
boolean
Check if two arrays of DOM elements are equal (according to .isEqualNode())

isHardCursorStep(step) → {boolean}static #

Test whether a cursor movement step uses up a cursor press

Essentially, this is true unless entering/exiting a contentEditable text/annotation node. For instance in <#text>X</#text><b><#text>y</#text></b> a single cursor press will jump from just after X to just after Y.

Parameters:

Name Type Description
step ve.PositionStep

The cursor movement step to test
Source:
See:

Returns:

Whether the cursor movement step uses up a cursor press

Type
boolean

Test whether a cursor movement step uses up a cursor press

Essentially, this is true unless entering/exiting a contentEditable text/annotation node.

isInstanceOfAny(subject, classes) → {boolean}static #

Checks if an object is an instance of one or more classes.

Parameters:

Name Type Description
subject Object

Object to check
classes Array.<function()>

Classes to compare with
Source:

Returns:

Object inherits from one or more of the classes

Type
boolean
Checks if an object is an instance of one or more classes.

isPlainObject(obj) → {boolean}static #

Check to see if an object is a plain object (created using "{}" or "new Object").

See http://api.jquery.com/jQuery.isPlainObject/

Parameters:

Name Type Description
obj Object

The object that will be checked to see if it's a plain object
Source:

Returns:

Type
boolean
Check to see if an object is a plain object (created using "{}" or "new Object").

isUnmodifiedLeftClick(e) → {boolean}static #

Check whether a jQuery event represents a plain left click, without any modifiers

Parameters:

Name Type Description
e jQuery.Event
Source:

Returns:

Whether it was an unmodified left click

Type
boolean
Check whether a jQuery event represents a plain left click, without any modifiers

isUriComponentValid(s) → {boolean}static #

Check if a string is a valid URI component.

A URI component is considered invalid if decodeURIComponent() throws an exception.

Parameters:

Name Type Description
s string

String to test
Source:
See:

Returns:

decodeURIComponent( s ) did not throw an exception

Type
boolean
Check if a string is a valid URI component.

isVoidElement(element) → {boolean}static #

Check whether a given DOM element is a void element (can't have children).

Parameters:

Name Type Description
element HTMLElement | string

Element or element name
Source:

Returns:

Element is a void element

Type
boolean
Check whether a given DOM element is a void element (can't have children).

matchTag(html, tag) → {Array.<string>|null}static #

Match a specific HTML tag that appears once, e.g. 'html' or 'body'

Parameters:

Name Type Description
html string

Document HTML
tag string

Tag name
Source:

Returns:

Regex match, null if not found

Type
Array.<string> | null
Match a specific HTML tag that appears once, e.g.

minimizeRects(rects, [allowedErrorOffset]) → {Array.<Object>}static #

Minimize a set of rectangles by discarding ones which are contained by others

Parameters:

Name Type Attributes Default Description
rects Array.<Object>

Full list of rectangles
allowedErrorOffset number optional
 3

Allowed error offset, the pixel error amount used in coordinate comparisons.
Source:

Returns:

Minimized list of rectangles

Type
Array.<Object>
Minimize a set of rectangles by discarding ones which are contained by others

msg(key, […params]) → {string}static #

Get a localized message.

Parameters:

Name Type Attributes Description
key string

Message key
params any optional
repeatable

Message parameters
Source:

Returns:

Localized message

Type
string
Get a localized message.

normalizeAttributeValue(name, value, [nodeName]) → {string}static #

Helper function for #transformStyleAttributes.

Normalize an attribute value. In compliant browsers, this should be a no-op, but in IE style attributes are normalized on all elements, color and bgcolor attributes are normalized on some elements (like <tr>), and width and height attributes are normalized on some elements( like <table>).

Parameters:

Name Type Attributes Default Description
name string

Attribute name
value string

Attribute value
nodeName string optional
 'div'

Element name
Source:

Returns:

Normalized attribute value

Type
string
Helper function for #transformStyleAttributes.

now() → {number}static #

Get the current time, measured in milliseconds since January 1, 1970 (UTC).

Source:

Returns:

Current time, monotonic in modern browsers (via Performance Timeline API)

Type
number
Get the current time, measured in milliseconds since January 1, 1970 (UTC).

parentIndex(node) → {number}static #

Get the index of a node in its parentNode's childNode list

Parameters:

Name Type Description
node Node

The node
Source:

Returns:

Index in parentNode's childNode list

Type
number
Get the index of a node in its parentNode's childNode list

promiseAll(promises) → {jQuery.Promise}static #

Create a promise which resolves when the list of promises has resolved

Parameters:

Name Type Description
promises Array.<jQuery.Promise>

List of promises
Source:

Returns:

Promise which resolves when the list of promises has resolved

Type
jQuery.Promise
Create a promise which resolves when the list of promises has resolved

properInnerHtml(element) → {string}static #

Get the actual inner HTML of a DOM node.

In most browsers, .innerHTML is broken and eats newlines in <pre> elements, see https://bugzilla.mozilla.org/show_bug.cgi?id=838954 . This function detects this behavior and works around it, to the extent possible. <pre>\nFoo</pre> will become <pre>Foo</pre> if the browser is broken, but newlines are preserved in all other cases.

Parameters:

Name Type Description
element HTMLElement

HTML element to get inner HTML of
Source:

Returns:

Inner HTML

Type
string
Get the actual inner HTML of a DOM node.

properOuterHtml(element) → {string}static #

Get the actual outer HTML of a DOM node.

Parameters:

Name Type Description
element HTMLElement

HTML element to get outer HTML of
Source:
See:

Returns:

Outer HTML

Type
string
Get the actual outer HTML of a DOM node.

rejectsCursor([node]) → {boolean}static #

Tests whether an adjacent cursor would be prevented from entering the node

Parameters:

Name Type Attributes Description
node Node optional

Element node or text node; defaults to "this" if a Node
Source:

Returns:

Whether an adjacent cursor would be prevented from entering

Type
boolean
Tests whether an adjacent cursor would be prevented from entering the node

resolveAttributes(elementsOrJQuery, doc, attrs)static #

Modify a set of DOM elements to resolve attributes in the context of another document.

This performs node.setAttribute( 'attr', nodeInDoc[attr] ); for every node.

Doesn't use jQuery to avoid document switching performance bug

Parameters:

Name Type Description
elementsOrJQuery HTMLElement | Array.<HTMLElement> | NodeList | jQuery

Set of DOM elements to modify. Passing a jQuery selector is deprecated.
doc HTMLDocument

Document to resolve against (different from $elements' .ownerDocument)
attrs Array.<string>

Attributes to resolve
Source:
Modify a set of DOM elements to resolve attributes in the context of another document.

resolveUrl(url, base) → {string}static #

Resolve a URL relative to a given base.

Parameters:

Name Type Description
url string

URL to resolve
base HTMLDocument

Document whose base URL to use
Source:

Returns:

Resolved URL

Type
string
Resolve a URL relative to a given base.

safeDecodeEntities(html) → {string}static #

Safely decode HTML entities

Parameters:

Name Type Description
html string

Text with HTML entities
Source:

Returns:

Text with HTML entities decoded

Type
string
Safely decode HTML entities

safeDecodeURIComponent(s) → {string}static #

Safe version of decodeURIComponent() that doesn't throw exceptions.

If the native decodeURIComponent() call threw an exception, the original string will be returned.

Parameters:

Name Type Description
s string

String to decode
Source:
See:

Returns:

Decoded string, or same string if decoding failed

Type
string
Safe version of decodeURIComponent() that doesn't throw exceptions.

sanitizeHtml(html, [returnDocument]) → {NodeList|HTMLDocument}static #

Parse some user HTML into a sanitized node list, making it safe to load on the page

Parameters:

Name Type Attributes Description
html string
returnDocument boolean optional

For internal use only (if true, return whole document)
Source:

Returns:

Sanitized node list (or HTML document, for internal use only)

Type
NodeList | HTMLDocument
Parse some user HTML into a sanitized node list, making it safe to load on the page

sanitizeHtmlToDocument(html) → {HTMLDocument}static #

Parse some user HTML into a sanitized HTML document, making it safe to load on the page

Parameters:

Name Type Description
html string
Source:

Returns:

Type
HTMLDocument
Parse some user HTML into a sanitized HTML document, making it safe to load on the page

scrollIntoView()static #

Source:
See:

selectElement(element)static #

Select the contents of an element

Parameters:

Name Type Description
element HTMLElement
Source:
Select the contents of an element

serializeNodeDebug(domNode) → {string}static #

Like outerHTML serialization, but wraps each text node in a fake tag. This makes it obvious whether there are split text nodes present.

Parameters:

Name Type Description
domNode Node

The node to serialize
Source:

Returns:

Serialization of the node and its contents

Type
string
Like outerHTML serialization, but wraps each text node in a fake tag.

setAttributeSafe(element, attr, val, [fallbackVal])static #

Set an element attribute to a specific value if it is safe

Parameters:

Name Type Attributes Description
element HTMLElement

Element
attr string

Attribute
val string

Value
fallbackVal string optional

Optional fallback value if val is unsafe (will also be safety-checked)
Source:
Set an element attribute to a specific value if it is safe

setDomAttributes(element, attributes, [allowedAttributes])static #

Set the attributes of a DOM element as an object with key/value pairs.

Use the null or undefined value to ensure an attribute's absence.

Parameters:

Name Type Attributes Description
element HTMLElement

DOM element to apply attributes to
attributes Object

Attributes to apply
allowedAttributes Array.<string> optional

List of attributes to exclusively allow (all lowercase names)
Source:
Set the attributes of a DOM element as an object with key/value pairs.

setProp(obj, […keys], [value])static #

Set a deeply nested property of an object using variadic arguments, protecting against undefined property errors.

OO.setProp( obj, 'foo', 'bar', 'baz' ); is equivalent to obj.foo.bar = baz; except that the former protects against JS errors if one of the intermediate properties is undefined. Instead of throwing an error, undefined intermediate properties will be initialized to an empty object. If an intermediate property is not an object, or if obj itself is not an object, this function will silently abort.

See https://doc.wikimedia.org/oojs/master/OO.html

Parameters:

Name Type Attributes Description
obj Object
keys any optional
repeatable
value any optional
Source:

Set a deeply nested property of an object using variadic arguments, protecting against undefined property errors.

sparseSplice(arr, offset, remove, data) → {Array}static #

Splice one array into another, replicating any holes

Similar to arr.splice( offset, remove, ...data ), except holes in data remain holes in arr. Optimized for length changes that are negative, zero, or fairly small positive.

Parameters:

Name Type Description
arr Array

Array to modify
offset number

Offset in arr to splice at. This MUST NOT be negative, unlike the 'index' parameter in Array#splice.
remove number

Number of elements to remove at the offset. May be zero
data Array

Array of items to insert at the offset
Source:

Returns:

Array of items removed, with holes preserved

Type
Array

Splice one array into another, replicating any holes

Similar to arr.splice( offset, remove, ...data ), except holes in data remain holes in arr.

summarizeTransaction(tx) → {string}static #

Get a human-readable summary of a transaction

Parameters:

Name Type Description
tx ve.dm.Transaction

A transaction
Source:

Returns:

Human-readable summary

Type
string
Get a human-readable summary of a transaction

targetLinksToNewWindow(container)static #

Make all links within a DOM element open in a new window

Parameters:

Name Type Description
container HTMLElement

DOM element to search for links
Source:
Make all links within a DOM element open in a new window

throttle()static #

Source:
See:

track(topic, [data])static #

Track an analytic event.

VisualEditor uses this method internally to track internal changes of state that are of analytic interest, either because they provide data about how users interact with the editor, or because they contain exception info, latency measurements, or other metrics that help gauge performance and reliability. VisualEditor does not transmit these events by default, but it provides a generic interface for routing these events to an analytics framework.

Parameters:

Name Type Attributes Description
topic string

Event name
data Object optional

Additional data describing the event, encoded as an object
Source:
Track an analytic event.

trackSubscribe(topic, callback)static #

Register a handler for subset of analytic events, specified by topic

Handlers will be called once for each tracked event, including any events that fired before the handler was registered, with the topic, event data payload, and event timestamp as the first, second, and third arguments, respectively.

Parameters:

Name Type Description
topic string

Handle events whose name starts with this string prefix
callback function

Handler to call for each matching tracked event
Source:

Register a handler for subset of analytic events, specified by topic

Handlers will be called once for each tracked event, including any events that fired before the handler was registered, with the topic, event data payload, and event timestamp as the first, second, and third arguments, respectively.

translateRect(rect, x, y) → {Object}static #

Translate rect by some fixed vector and return a new offset object

Parameters:

Name Type Description
rect Object

Offset object containing all or any of top, left, bottom, right, width & height
x number

Horizontal translation
y number

Vertical translation
Source:

Returns:

Translated rect

Type
Object
Translate rect by some fixed vector and return a new offset object

userConfig(key, [value]) → {any|Object|boolean}static #

Get or set a user config value.

Parameters:

Name Type Attributes Description
key string | Array.<string> | Object

Config key, list of keys or object mapping keys to values
value any optional

Value to set, if setting and key is a string
Source:

Returns:

Config value, keyed object of config values if list of keys provided, or success boolean if setting.

Type
any | Object | boolean
Get or set a user config value.

Type Definitions

ChangeOffsets #

Type:

Source:

DomPosition #

Type:

Properties:

Name Type Description
node Node | null

The node, or null if we stepped past the root node
offset number | null

The offset, or null if we stepped past the root node
steps Array.<ve.PositionStep>

Steps taken
Source: