Mercurial
comparison .cms/lib/codemirror/doc/upgrade_v3.html @ 0:78edf6b517a0 draft
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 <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> |