Mercurial

comparison .cms/lib/codemirror/doc/upgrade_v4.html @ 0:78edf6b517a0 draft

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
24.10
author Coffee CMS <info@coffee-cms.ru>
date Fri, 11 Oct 2024 22:40:23 +0000
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:78edf6b517a0
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>