|
0
|
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="https://codemirror.net/5"><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/codemirror5">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>
|
