VisualEditor/API

Use cases

 * Add support for a new kind of content
 * DM: Node class and converter registration
 * CE: Node class
 * UI: Tool/inspector
 * Add support for a new kind of annotation
 * DM: Annotation class and converter registration
 * CE: Annotation class and renderer registration
 * UI: Tool/inspector
 * Make changes to the document model
 * Get the selection range
 * Get information about what's selected
 * Modify selected content
 * Add annotations
 * Change the formatting (heading, paragraph, pre, etc.)
 * List/unlist/change list style
 * Indent/unindent
 * Insert/delete
 * Wrap/unwrap

Surface API
The surface API provides a way to get information about the surface as well as make changes to it. A surface is a document, selection and history of transactions that have been processed over time. Interactions with this API are similar to working with a jQuery selection in many ways, which is done intentionally to make it easier to learn. This is the central component to the surface API, providing an abstraction that greatly simplifies common tasks.

Abstraction of a surface model.

Surface to abstract.

[optional]
Range within surface to work on.

Chaining
Once you have a fragment, you can get information about the surface using a getter function, get another fragment based on the one you have, or make changes to the document. The latter two of these classes of operations are chainable.

Null fragments
Sometimes getting a new fragment based on the one you have results in an invalid fragment, such as asking to expand the range to the nearest paragraph while in a pre-formatted node. In this case a null fragment is returned, from which all getters return empty values, only null fragments can be created and changes to the document are ignored.

Ranges
Each fragment's range will automatically be updated to remain relevant any time a document is modified. This is done internally by using the ve.dm.Transaction.translateRange feature.

Register an annotation in VisualEditor.

Has to be globally unique for all annotations, tag names etc. No hierarchy is enforced although naming conventions encourage usage of the slash character to group related annotations (for readability only) such as.

Describes the annotation. Requires the following three properties:
 * : This object is used to determine whether a given HTMLElement should be represented by this annotation (for more detail on annotation matching, see matchElement). Must have one or more of the following:
 * : A lowercase HTMLElement node name. Omit this property if it can match multiple kinds of elements (including if it may match all html elements), in that case at least one of the next two properties must be included.
 * : Filters by one of the (space-separated) values in txhe RDFa attributes of the HTMLElement (usually the rel attributes @TODO: Which else, when? See Parsoid/RDFa vocabulary.)
 * Should return Boolean true or false.
 * [optional]: Object (or function returning an object) with annotation data to be kept about this annotation in the linear model. Any information that is needed to understand or manipulate the annotation must be extracted at this point as no access to the HTML element will be given during the editing process.
 * : When converting the linear model back to HTML, this object (or the object returned by this function) is used to create an HTML element from the annotation. If the annotation was originally created from an HTML element, the attributes will be based on the original element's attributes, and any attributes specified in 'attributes' below will override these. To explicitly remove an attribute, set it to undefined.
 * : Lowercase HTML element node name.
 * [optional]: Object with attributes and their values.
 * [optional] If the HTML rendering in the editor should be different from the HTML output, this property can be used to override it. This object (or object returned by this function) has the same behavior and properties as 'html' above. If it's omitted, the rules in 'html' will be used.