VisualEditor/API/Data Model/Surface

A surface contains a document, selection and history of transactions that have been processed over time. When working with a surface a surface fragment object is used to abstract away the complexity of getting information about a surface and making changes to it while keeping everything in sync. 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.

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.

ve.dm.SurfaceFragment( surface, range )
Selected portion of a surface.
 * surface {ve.dm.Surface}
 * Target surface


 * range {ve.Range} [optional]
 * Range within target document, current selection used by default


 * isNull
 * Responds to transactions being processed on the document
 * Returns  {Boolean}  Fragment is a null fragment


 * adjustRange( start, end )
 * Gets a new fragment with an adjusted position
 * Returns  {ve.dm.SurfaceFragment}  Adjusted fragment


 * start {Number} [optional]
 * Adjustment for start position


 * end {Number} [optional]
 * Adjustment for end position