|
0
|
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>
|
