upgrade_v4.html (5456B)
1 <!doctype html> 2 3 <title>CodeMirror: Version 4 upgrade guide</title> 4 <meta charset="utf-8"/> 5 <link rel=stylesheet href="docs.css"> 6 <script src="activebookmark.js"></script> 7 8 <div id=nav> 9 <a href="http://codemirror.net"><h1>CodeMirror</h1><img id=logo src="logo.png"></a> 10 11 <ul> 12 <li><a href="../index.html">Home</a> 13 <li><a href="manual.html">Manual</a> 14 <li><a href="https://github.com/codemirror/codemirror">Code</a> 15 </ul> 16 <ul> 17 <li><a class=active href="#upgrade">Upgrade guide</a> 18 <li><a href="#multisel">Multiple selections</a> 19 <li><a href="#beforeSelectionChange">The beforeSelectionChange event</a> 20 <li><a href="#replaceSelection">replaceSelection and collapsing</a> 21 <li><a href="#changeEvent">change event data</a> 22 <li><a href="#showIfHidden">showIfHidden option to line widgets</a> 23 <li><a href="#module">Module loaders</a> 24 <li><a href="#shareddata">Mutating shared data structures</a></li> 25 <li><a href="#deprecated">Deprecated interfaces dropped</a> 26 </ul> 27 </div> 28 29 <article> 30 31 <h2 id=upgrade>Upgrading to version 4</h2> 32 33 <p>CodeMirror 4's interface is <em>very</em> close version 3, but it 34 does fix a few awkward details in a backwards-incompatible ways. At 35 least skim the text below before upgrading.</p> 36 37 <section id=multisel><h2>Multiple selections</h2> 38 39 <p>The main new feature in version 4 is multiple selections. The 40 single-selection variants of methods are still there, but now 41 typically act only on the <em>primary</em> selection (usually the last 42 one added).</p> 43 44 <p>The exception to this 45 is <a href="manual.html#getSelection"><strong><code>getSelection</code></strong></a>, 46 which will now return the content of <em>all</em> selections 47 (separated by newlines, or whatever <code>lineSep</code> parameter you passed 48 it).</p> 49 50 </section> 51 52 <section id=beforeSelectionChange><h2>The beforeSelectionChange event</h2> 53 54 <p>This event still exists, but the object it is passed has 55 a <a href="manual.html#event_beforeSelectionChange">completely new 56 interface</a>, because such changes now concern multiple 57 selections.</p> 58 59 </section> 60 61 <section id=replaceSelection><h2>replaceSelection's collapsing behavior</h2> 62 63 <p>By 64 default, <a href="manual.html#replaceSelection"><code>replaceSelection</code></a> 65 would leave the newly inserted text selected. This is only rarely what 66 you want, and also (slightly) more expensive in the new model, so the 67 default was changed to <code>"end"</code>, meaning the old behavior 68 must be explicitly specified by passing a second argument 69 of <code>"around"</code>.</p> 70 71 </section> 72 73 <section id=changeEvent><h2>change event data</h2> 74 75 <p>Rather than forcing client code to follow <code>next</code> 76 pointers from one change object to the next, the library will now 77 simply fire 78 multiple <a href="manual.html#event_change"><code>"change"</code></a> 79 events. Existing code will probably continue to work unmodified.</p> 80 81 </section> 82 83 <section id=showIfHidden><h2>showIfHidden option to line widgets</h2> 84 85 <p>This option, which conceptually caused line widgets to be visible 86 even if their line was hidden, was never really well-defined, and was 87 buggy from the start. It would be a rather expensive feature, both in 88 code complexity and run-time performance, to implement properly. It 89 has been dropped entirely in 4.0.</p> 90 91 </section> 92 93 <section id=module><h2>Module loaders</h2> 94 95 <p>All modules in the CodeMirror distribution are now wrapped in a 96 shim function to make them compatible with both AMD 97 (<a href="http://requirejs.org">requirejs</a>) and CommonJS (as used 98 by <a href="http://nodejs.org/">node</a> 99 and <a href="http://browserify.org/">browserify</a>) module loaders. 100 When neither of these is present, they fall back to simply using the 101 global <code>CodeMirror</code> variable.</p> 102 103 <p>If you have a module loader present in your environment, CodeMirror 104 will attempt to use it, and you might need to change the way you load 105 CodeMirror modules.</p> 106 107 </section> 108 109 <section id=shareddata><h2>Mutating shared data structures</h2> 110 111 <p>Data structures produced by the library should not be mutated 112 unless explicitly allowed, in general. This is slightly more strict in 113 4.0 than it was in earlier versions, which copied the position objects 114 returned by <a href="manual.html#getCursor"><code>getCursor</code></a> 115 for nebulous, historic reasons. In 4.0, mutating these 116 objects <em>will</em> corrupt your editor's selection.</p> 117 118 </section> 119 120 <section id=deprecated><h2>Deprecated interfaces dropped</h2> 121 122 <p>A few properties and methods that have been deprecated for a while 123 are now gone. Most notably, the <code>onKeyEvent</code> 124 and <code>onDragEvent</code> options (use the 125 corresponding <a href="manual.html#event_dom">events</a> instead).</p> 126 127 <p>Two silly methods, which were mostly there to stay close to the 0.x 128 API, <code>setLine</code> and <code>removeLine</code> are now gone. 129 Use the more 130 flexible <a href="manual.html#replaceRange"><code>replaceRange</code></a> 131 method instead.</p> 132 133 <p>The long names for folding and completing functions 134 (<code>CodeMirror.braceRangeFinder</code>, <code>CodeMirror.javascriptHint</code>, 135 etc) are also gone 136 (use <code>CodeMirror.fold.brace</code>, <code>CodeMirror.hint.javascript</code>).</p> 137 138 <p>The <code>className</code> property in the return value 139 of <a href="manual.html#getTokenAt"><code>getTokenAt</code></a>, which 140 has been superseded by the <code>type</code> property, is also no 141 longer present.</p> 142 143 </section> 144 </article>