Spaces:
Running
Running
| <html> | |
| <head> | |
| <meta charset="utf-8"/> | |
| <title>CodeMirror: Upgrading to v3</title> | |
| <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Droid+Sans|Droid+Sans:bold"/> | |
| <link rel="stylesheet" type="text/css" href="docs.css"/> | |
| <script src="../lib/codemirror.js"></script> | |
| <link rel="stylesheet" href="../lib/codemirror.css"> | |
| <script src="../addon/runmode/runmode.js"></script> | |
| <script src="../addon/runmode/colorize.js"></script> | |
| <script src="../mode/javascript/javascript.js"></script> | |
| <script src="../mode/xml/xml.js"></script> | |
| <script src="../mode/css/css.js"></script> | |
| <script src="../mode/htmlmixed/htmlmixed.js"></script> | |
| </head> | |
| <body> | |
| <h1><span class="logo-braces">{ }</span> <a href="http://codemirror.net/">CodeMirror</a></h1> | |
| <div class="grey"> | |
| <img src="baboon.png" class="logo" alt="logo"/> | |
| <pre> | |
| /* Upgrading to | |
| version 3 */ | |
| </pre> | |
| </div> | |
| <div class="clear"><div class="leftbig blk"> | |
| <p>Version 3 does not depart too much from 2.x API, and sites that use | |
| CodeMirror in a very simple way might be able to upgrade without | |
| trouble. But it does introduce a number of incompatibilities. Please | |
| at least skim this text before upgrading.</p> | |
| <p>Note that <strong>version 3 drops full support for Internet | |
| Explorer 7</strong>. The editor will mostly work on that browser, but | |
| it'll be significantly glitchy.</p> | |
| <h2 id=dom>DOM structure</h2> | |
| <p>This one is the most likely to cause problems. The internal | |
| structure of the editor has changed quite a lot, mostly to implement a | |
| new scrolling model.</p> | |
| <p>Editor height is now set on the outer wrapper element (CSS | |
| class <code>CodeMirror</code>), not on the scroller element | |
| (<code>CodeMirror-scroll</code>).</p> | |
| <p>Other nodes were moved, dropped, and added. If you have any code | |
| that makes assumptions about the internal DOM structure of the editor, | |
| you'll have to re-test it and probably update it to work with v3.</p> | |
| <p>See the <a href="manual.html#styling">styling section</a> of the | |
| manual for more information.</p> | |
| <h2 id=gutters>Gutter model</h2> | |
| <p>In CodeMirror 2.x, there was a single gutter, and line markers | |
| created with <code>setMarker</code> would have to somehow coexist with | |
| the line numbers (if present). Version 3 allows you to specify an | |
| array of gutters, <a href="manual.html#option_gutters">by class | |
| name</a>, | |
| use <a href="manual.html#setGutterMarker"><code>setGutterMarker</code></a> | |
| to add or remove markers in individual gutters, and clear whole | |
| gutters | |
| with <a href="manual.html#clearGutter"><code>clearGutter</code></a>. | |
| Gutter markers are now specified as DOM nodes, rather than HTML | |
| snippets.</p> | |
| <p>The gutters no longer horizontally scrolls along with the content. | |
| The <code>fixedGutter</code> option was removed (since it is now the | |
| only behavior).</p> | |
| <pre data-lang="text/html"> | |
| <style> | |
| /* Define a gutter style */ | |
| .note-gutter { width: 3em; background: cyan; } | |
| </style> | |
| <script> | |
| // Create an instance with two gutters -- line numbers and notes | |
| var cm = new CodeMirror(document.body, { | |
| gutters: ["note-gutter", "CodeMirror-linenumbers"], | |
| lineNumbers: true | |
| }); | |
| // Add a note to line 0 | |
| cm.setGutterMarker(0, "note-gutter", document.createTextNode("hi")); | |
| </script> | |
| </pre> | |
| <h2 id=events>Event handling</h2> | |
| <p>Most of the <code>onXYZ</code> options have been removed. The same | |
| effect is now obtained by calling | |
| the <a href="manual.html#on"><code>on</code></a> method with a string | |
| identifying the event type. Multiple handlers can now be registered | |
| (and individually unregistered) for an event, and objects such as line | |
| handlers now also expose events. See <a href="manual.html#events">the | |
| full list here</a>.</p> | |
| <p>(The <code>onKeyEvent</code> and <code>onDragEvent</code> options, | |
| which act more as hooks than as event handlers, are still there in | |
| their old form.)</p> | |
| <pre data-lang="javascript"> | |
| cm.on("change", function(cm, change) { | |
| console.log("something changed! (" + change.origin + ")"); | |
| }); | |
| </pre> | |
| <h2 id=marktext>markText method arguments</h2> | |
| <p>The <a href="manual.html#markText"><code>markText</code></a> method | |
| (which has gained some interesting new features, such as creating | |
| atomic and read-only spans, or replacing spans with widgets) no longer | |
| takes the CSS class name as a separate argument, but makes it an | |
| optional field in the options object instead.</p> | |
| <pre data-lang="javascript"> | |
| // Style first ten lines, and forbid the cursor from entering them | |
| cm.markText({line: 0, ch: 0}, {line: 10, ch: 0}, { | |
| className: "magic-text", | |
| inclusiveLeft: true, | |
| atomic: true | |
| }); | |
| </pre> | |
| <h2 id=folding>Line folding</h2> | |
| <p>The interface for hiding lines has been | |
| removed. <a href="manual.html#markText"><code>markText</code></a> can | |
| now be used to do the same in a more flexible and powerful way.</p> | |
| <p>The <a href="../demo/folding.html">folding script</a> has been | |
| updated to use the new interface, and should now be more robust.</p> | |
| <pre data-lang="javascript"> | |
| // Fold a range, replacing it with the text "??" | |
| var range = cm.markText({line: 4, ch: 2}, {line: 8, ch: 1}, { | |
| replacedWith: document.createTextNode("??"), | |
| // Auto-unfold when cursor moves into the range | |
| clearOnEnter: true | |
| }); | |
| // Get notified when auto-unfolding | |
| CodeMirror.on(range, "clear", function() { | |
| console.log("boom"); | |
| }); | |
| </pre> | |
| <h2 id=lineclass>Line CSS classes</h2> | |
| <p>The <code>setLineClass</code> method has been replaced | |
| by <a href="manual.html#addLineClass"><code>addLineClass</code></a> | |
| and <a href="manual.html#removeLineClass"><code>removeLineClass</code></a>, | |
| which allow more modular control over the classes attached to a line.</p> | |
| <pre data-lang="javascript"> | |
| var marked = cm.addLineClass(10, "background", "highlighted-line"); | |
| setTimeout(function() { | |
| cm.removeLineClass(marked, "background", "highlighted-line"); | |
| }); | |
| </pre> | |
| <h2 id=positions>Position properties</h2> | |
| <p>All methods that take or return objects that represent screen | |
| positions now use <code>{left, top, bottom, right}</code> properties | |
| (not always all of them) instead of the <code>{x, y, yBot}</code> used | |
| by some methods in v2.x.</p> | |
| <p>Affected methods | |
| 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>, | |
| and <a href="manual.html#getScrollInfo"><code>getScrollInfo</code></a>.</p> | |
| <h2 id=matchbrackets>Bracket matching no longer in core</h2> | |
| <p>The <a href="manual.html#addon_matchbrackets"><code>matchBrackets</code></a> | |
| option is no longer defined in the core editor. | |
| Load <code>addon/edit/matchbrackets.js</code> to enable it.</p> | |
| <h2 id=modes>Mode management</h2> | |
| <p>The <code>CodeMirror.listModes</code> | |
| and <code>CodeMirror.listMIMEs</code> functions, used for listing | |
| defined modes, are gone. You are now encouraged to simply | |
| inspect <code>CodeMirror.modes</code> (mapping mode names to mode | |
| constructors) and <code>CodeMirror.mimeModes</code> (mapping MIME | |
| strings to mode specs).</p> | |
| <h2 id=new>New features</h2> | |
| <p>Some more reasons to upgrade to version 3.</p> | |
| <ul> | |
| <li>Bi-directional text support. CodeMirror will now mostly do the | |
| right thing when editing Arabic or Hebrew text.</li> | |
| <li>Arbitrary line heights. Using fonts with different heights | |
| inside the editor (whether off by one pixel or fifty) is now | |
| supported and handled gracefully.</li> | |
| <li>In-line widgets. See <a href="../demo/widget.html">the demo</a> | |
| and <a href="manual.html#addLineWidget">the docs</a>.</li> | |
| <li>Defining custom options | |
| with <a href="manual.html#defineOption"><code>CodeMirror.defineOption</code></a>.</li> | |
| </ul> | |
| </div><div class="rightsmall blk"> | |
| <h2>Contents</h2> | |
| <ul> | |
| <li><a href="#dom">DOM structure</a></li> | |
| <li><a href="#gutters">Gutter model</a></li> | |
| <li><a href="#events">Event handling</a></li> | |
| <li><a href="#folding">Line folding</a></li> | |
| <li><a href="#marktext">markText method arguments</a></li> | |
| <li><a href="#lineclass">Line CSS classes</a></li> | |
| <li><a href="#positions">Position properties</a></li> | |
| <li><a href="#matchbrackets">Bracket matching</a></li> | |
| <li><a href="#modes">Mode management</a></li> | |
| <li><a href="#new">New features</a></li> | |
| </ul> | |
| </div></div> | |
| <script>setTimeout(function(){CodeMirror.colorize();}, 20);</script> | |
| </body> | |
| </html> | |