123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227 |
- <!doctype html>
- <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>
|