Upgrading to version 3
Version 3 does not depart too much from 2.x API, and sites that use CodeMirror in a very simple way might be able to upgrade without trouble. But it does introduce a number of incompatibilities. Please at least skim this text before upgrading.
Note that version 3 drops full support for Internet Explorer 7. The editor will mostly work on that browser, but it'll be significantly glitchy.
DOM structure
This one is the most likely to cause problems. The internal structure of the editor has changed quite a lot, mostly to implement a new scrolling model.
Editor height is now set on the outer wrapper element (CSS
class CodeMirror
), not on the scroller element
(CodeMirror-scroll
).
Other nodes were moved, dropped, and added. If you have any code that makes assumptions about the internal DOM structure of the editor, you'll have to re-test it and probably update it to work with v3.
See the styling section of the manual for more information.
Gutter model
In CodeMirror 2.x, there was a single gutter, and line markers
created with setMarker
would have to somehow coexist with
the line numbers (if present). Version 3 allows you to specify an
array of gutters, by class
name,
use setGutterMarker
to add or remove markers in individual gutters, and clear whole
gutters
with clearGutter
.
Gutter markers are now specified as DOM nodes, rather than HTML
snippets.
The gutters no longer horizontally scrolls along with the content.
The fixedGutter
option was removed (since it is now the
only behavior).
<style> /* Define a gutter style */ .note-gutter { width: 3em; background: cyan; } </style> <script> // Create an instance with two gutters -- line numbers and notes var cm = new CodeMirror(document.body, { gutters: ["note-gutter", "CodeMirror-linenumbers"], lineNumbers: true }); // Add a note to line 0 cm.setGutterMarker(0, "note-gutter", document.createTextNode("hi")); </script>
Event handling
Most of the onXYZ
options have been removed. The same
effect is now obtained by calling
the on
method with a string
identifying the event type. Multiple handlers can now be registered
(and individually unregistered) for an event, and objects such as line
handlers now also expose events. See the
full list here.
(The onKeyEvent
and onDragEvent
options,
which act more as hooks than as event handlers, are still there in
their old form.)
cm.on("change", function(cm, change) { console.log("something changed! (" + change.origin + ")"); });
markText method arguments
The markText
method
(which has gained some interesting new features, such as creating
atomic and read-only spans, or replacing spans with widgets) no longer
takes the CSS class name as a separate argument, but makes it an
optional field in the options object instead.
// Style first ten lines, and forbid the cursor from entering them cm.markText({line: 0, ch: 0}, {line: 10, ch: 0}, { className: "magic-text", inclusiveLeft: true, atomic: true });
Line folding
The interface for hiding lines has been
removed. markText
can
now be used to do the same in a more flexible and powerful way.
The folding script has been updated to use the new interface, and should now be more robust.
// Fold a range, replacing it with the text "??" var range = cm.markText({line: 4, ch: 2}, {line: 8, ch: 1}, { replacedWith: document.createTextNode("??"), // Auto-unfold when cursor moves into the range clearOnEnter: true }); // Get notified when auto-unfolding CodeMirror.on(range, "clear", function() { console.log("boom"); });
Line CSS classes
The setLineClass
method has been replaced
by addLineClass
and removeLineClass
,
which allow more modular control over the classes attached to a line.
var marked = cm.addLineClass(10, "background", "highlighted-line"); setTimeout(function() { cm.removeLineClass(marked, "background", "highlighted-line"); });
Position properties
All methods that take or return objects that represent screen
positions now use {left, top, bottom, right}
properties
(not always all of them) instead of the {x, y, yBot}
used
by some methods in v2.x.
Affected methods
are cursorCoords
, charCoords
, coordsChar
,
and getScrollInfo
.
Bracket matching no longer in core
The matchBrackets
option is no longer defined in the core editor.
Load addon/edit/matchbrackets.js
to enable it.
Mode management
The CodeMirror.listModes
and CodeMirror.listMIMEs
functions, used for listing
defined modes, are gone. You are now encouraged to simply
inspect CodeMirror.modes
(mapping mode names to mode
constructors) and CodeMirror.mimeModes
(mapping MIME
strings to mode specs).
New features
Some more reasons to upgrade to version 3.
- Bi-directional text support. CodeMirror will now mostly do the right thing when editing Arabic or Hebrew text.
- Arbitrary line heights. Using fonts with different heights inside the editor (whether off by one pixel or fifty) is now supported and handled gracefully.
- In-line widgets. See the demo and the docs.
- Defining custom options
with
CodeMirror.defineOption
.