CodeMirror: Version 4 upgrade guide

CodeMirror

Upgrade guide
Multiple selections
The beforeSelectionChange event
replaceSelection and collapsing
change event data
showIfHidden option to line widgets
Module loaders
Mutating shared data structures
Deprecated interfaces dropped

Upgrading to version 4

CodeMirror 4's interface is very close version 3, but it does fix a few awkward details in a backwards-incompatible ways. At least skim the text below before upgrading.

Multiple selections

The main new feature in version 4 is multiple selections. The single-selection variants of methods are still there, but now typically act only on the primary selection (usually the last one added).

The exception to this is getSelection, which will now return the content of all selections (separated by newlines, or whatever lineSep parameter you passed it).

The beforeSelectionChange event

This event still exists, but the object it is passed has a completely new interface, because such changes now concern multiple selections.

replaceSelection's collapsing behavior

By default, replaceSelection would leave the newly inserted text selected. This is only rarely what you want, and also (slightly) more expensive in the new model, so the default was changed to "end", meaning the old behavior must be explicitly specified by passing a second argument of "around".

change event data

Rather than forcing client code to follow next pointers from one change object to the next, the library will now simply fire multiple "change" events. Existing code will probably continue to work unmodified.

showIfHidden option to line widgets

This option, which conceptually caused line widgets to be visible even if their line was hidden, was never really well-defined, and was buggy from the start. It would be a rather expensive feature, both in code complexity and run-time performance, to implement properly. It has been dropped entirely in 4.0.

Module loaders

All modules in the CodeMirror distribution are now wrapped in a shim function to make them compatible with both AMD (requirejs) and CommonJS (as used by node and browserify) module loaders. When neither of these is present, they fall back to simply using the global CodeMirror variable.

If you have a module loader present in your environment, CodeMirror will attempt to use it, and you might need to change the way you load CodeMirror modules.

Mutating shared data structures

Data structures produced by the library should not be mutated unless explicitly allowed, in general. This is slightly more strict in 4.0 than it was in earlier versions, which copied the position objects returned by getCursor for nebulous, historic reasons. In 4.0, mutating these objects will corrupt your editor's selection.

Deprecated interfaces dropped

A few properties and methods that have been deprecated for a while are now gone. Most notably, the onKeyEvent and onDragEvent options (use the corresponding events instead).

Two silly methods, which were mostly there to stay close to the 0.x API, setLine and removeLine are now gone. Use the more flexible replaceRange method instead.

The long names for folding and completing functions (CodeMirror.braceRangeFinder, CodeMirror.javascriptHint, etc) are also gone (use CodeMirror.fold.brace, CodeMirror.hint.javascript).

The className property in the return value of getTokenAt, which has been superseded by the type property, is also no longer present.