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