Mercurial

comparison .cms/lib/codemirror/doc/upgrade_v3.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 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="https://codemirror.net/5"><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/codemirror5">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 &lt;style>
91 /* Define a gutter style */
92 .note-gutter { width: 3em; background: cyan; }
93 &lt;/style>
94 &lt;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 &lt;/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>