/* 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.
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.
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>
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 + ")"); });
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 });
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"); });
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"); });
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
.
The matchBrackets
option is no longer defined in the core editor.
Load addon/edit/matchbrackets.js
to enable it.
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).
Some more reasons to upgrade to version 3.
CodeMirror.defineOption
.