4 <meta charset="utf-8"/>
5 <title>CodeMirror: Upgrading to v3</title>
6 <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Droid+Sans|Droid+Sans:bold"/>
7 <link rel="stylesheet" type="text/css" href="docs.css"/>
8 <script src="../lib/codemirror.js"></script>
9 <link rel="stylesheet" href="../lib/codemirror.css">
10 <script src="../addon/runmode/runmode.js"></script>
11 <script src="../addon/runmode/colorize.js"></script>
12 <script src="../mode/javascript/javascript.js"></script>
13 <script src="../mode/xml/xml.js"></script>
14 <script src="../mode/css/css.js"></script>
15 <script src="../mode/htmlmixed/htmlmixed.js"></script>
19 <h1><span class="logo-braces">{ }</span> <a href="http://codemirror.net/">CodeMirror</a></h1>
22 <img src="baboon.png" class="logo" alt="logo"/>
29 <div class="clear"><div class="leftbig blk">
31 <p>Version 3 does not depart too much from 2.x API, and sites that use
32 CodeMirror in a very simple way might be able to upgrade without
33 trouble. But it does introduce a number of incompatibilities. Please
34 at least skim this text before upgrading.</p>
36 <p>Note that <strong>version 3 drops full support for Internet
37 Explorer 7</strong>. The editor will mostly work on that browser, but
38 it'll be significantly glitchy.</p>
40 <h2 id=dom>DOM structure</h2>
42 <p>This one is the most likely to cause problems. The internal
43 structure of the editor has changed quite a lot, mostly to implement a
44 new scrolling model.</p>
46 <p>Editor height is now set on the outer wrapper element (CSS
47 class <code>CodeMirror</code>), not on the scroller element
48 (<code>CodeMirror-scroll</code>).</p>
50 <p>Other nodes were moved, dropped, and added. If you have any code
51 that makes assumptions about the internal DOM structure of the editor,
52 you'll have to re-test it and probably update it to work with v3.</p>
54 <p>See the <a href="manual.html#styling">styling section</a> of the
55 manual for more information.</p>
57 <h2 id=gutters>Gutter model</h2>
59 <p>In CodeMirror 2.x, there was a single gutter, and line markers
60 created with <code>setMarker</code> would have to somehow coexist with
61 the line numbers (if present). Version 3 allows you to specify an
62 array of gutters, <a href="manual.html#option_gutters">by class
64 use <a href="manual.html#setGutterMarker"><code>setGutterMarker</code></a>
65 to add or remove markers in individual gutters, and clear whole
67 with <a href="manual.html#clearGutter"><code>clearGutter</code></a>.
68 Gutter markers are now specified as DOM nodes, rather than HTML
71 <p>The gutters no longer horizontally scrolls along with the content.
72 The <code>fixedGutter</code> option was removed (since it is now the
75 <pre data-lang="text/html">
77 /* Define a gutter style */
78 .note-gutter { width: 3em; background: cyan; }
81 // Create an instance with two gutters -- line numbers and notes
82 var cm = new CodeMirror(document.body, {
83 gutters: ["note-gutter", "CodeMirror-linenumbers"],
86 // Add a note to line 0
87 cm.setGutterMarker(0, "note-gutter", document.createTextNode("hi"));
91 <h2 id=events>Event handling</h2>
93 <p>Most of the <code>onXYZ</code> options have been removed. The same
94 effect is now obtained by calling
95 the <a href="manual.html#on"><code>on</code></a> method with a string
96 identifying the event type. Multiple handlers can now be registered
97 (and individually unregistered) for an event, and objects such as line
98 handlers now also expose events. See <a href="manual.html#events">the
99 full list here</a>.</p>
101 <p>(The <code>onKeyEvent</code> and <code>onDragEvent</code> options,
102 which act more as hooks than as event handlers, are still there in
105 <pre data-lang="javascript">
106 cm.on("change", function(cm, change) {
107 console.log("something changed! (" + change.origin + ")");
111 <h2 id=marktext>markText method arguments</h2>
113 <p>The <a href="manual.html#markText"><code>markText</code></a> method
114 (which has gained some interesting new features, such as creating
115 atomic and read-only spans, or replacing spans with widgets) no longer
116 takes the CSS class name as a separate argument, but makes it an
117 optional field in the options object instead.</p>
119 <pre data-lang="javascript">
120 // Style first ten lines, and forbid the cursor from entering them
121 cm.markText({line: 0, ch: 0}, {line: 10, ch: 0}, {
122 className: "magic-text",
128 <h2 id=folding>Line folding</h2>
130 <p>The interface for hiding lines has been
131 removed. <a href="manual.html#markText"><code>markText</code></a> can
132 now be used to do the same in a more flexible and powerful way.</p>
134 <p>The <a href="../demo/folding.html">folding script</a> has been
135 updated to use the new interface, and should now be more robust.</p>
137 <pre data-lang="javascript">
138 // Fold a range, replacing it with the text "??"
139 var range = cm.markText({line: 4, ch: 2}, {line: 8, ch: 1}, {
140 replacedWith: document.createTextNode("??"),
141 // Auto-unfold when cursor moves into the range
144 // Get notified when auto-unfolding
145 CodeMirror.on(range, "clear", function() {
150 <h2 id=lineclass>Line CSS classes</h2>
152 <p>The <code>setLineClass</code> method has been replaced
153 by <a href="manual.html#addLineClass"><code>addLineClass</code></a>
154 and <a href="manual.html#removeLineClass"><code>removeLineClass</code></a>,
155 which allow more modular control over the classes attached to a line.</p>
157 <pre data-lang="javascript">
158 var marked = cm.addLineClass(10, "background", "highlighted-line");
159 setTimeout(function() {
160 cm.removeLineClass(marked, "background", "highlighted-line");
164 <h2 id=positions>Position properties</h2>
166 <p>All methods that take or return objects that represent screen
167 positions now use <code>{left, top, bottom, right}</code> properties
168 (not always all of them) instead of the <code>{x, y, yBot}</code> used
169 by some methods in v2.x.</p>
172 are <a href="manual.html#cursorCoords"><code>cursorCoords</code></a>, <a href="manual.html#charCoords"><code>charCoords</code></a>, <a href="manual.html#coordsChar"><code>coordsChar</code></a>,
173 and <a href="manual.html#getScrollInfo"><code>getScrollInfo</code></a>.</p>
175 <h2 id=matchbrackets>Bracket matching no longer in core</h2>
177 <p>The <a href="manual.html#addon_matchbrackets"><code>matchBrackets</code></a>
178 option is no longer defined in the core editor.
179 Load <code>addon/edit/matchbrackets.js</code> to enable it.</p>
181 <h2 id=modes>Mode management</h2>
183 <p>The <code>CodeMirror.listModes</code>
184 and <code>CodeMirror.listMIMEs</code> functions, used for listing
185 defined modes, are gone. You are now encouraged to simply
186 inspect <code>CodeMirror.modes</code> (mapping mode names to mode
187 constructors) and <code>CodeMirror.mimeModes</code> (mapping MIME
188 strings to mode specs).</p>
190 <h2 id=new>New features</h2>
192 <p>Some more reasons to upgrade to version 3.</p>
195 <li>Bi-directional text support. CodeMirror will now mostly do the
196 right thing when editing Arabic or Hebrew text.</li>
197 <li>Arbitrary line heights. Using fonts with different heights
198 inside the editor (whether off by one pixel or fifty) is now
199 supported and handled gracefully.</li>
200 <li>In-line widgets. See <a href="../demo/widget.html">the demo</a>
201 and <a href="manual.html#addLineWidget">the docs</a>.</li>
202 <li>Defining custom options
203 with <a href="manual.html#defineOption"><code>CodeMirror.defineOption</code></a>.</li>
206 </div><div class="rightsmall blk">
211 <li><a href="#dom">DOM structure</a></li>
212 <li><a href="#gutters">Gutter model</a></li>
213 <li><a href="#events">Event handling</a></li>
214 <li><a href="#folding">Line folding</a></li>
215 <li><a href="#marktext">markText method arguments</a></li>
216 <li><a href="#lineclass">Line CSS classes</a></li>
217 <li><a href="#positions">Position properties</a></li>
218 <li><a href="#matchbrackets">Bracket matching</a></li>
219 <li><a href="#modes">Mode management</a></li>
220 <li><a href="#new">New features</a></li>
225 <script>setTimeout(function(){CodeMirror.colorize();}, 20);</script>