third-party/codemirror-3.15/doc/upgrade_v3.html

   1 <!doctype html>
   2 <html>
   3   <head>
   4     <meta charset="utf-8"/>
   5     <title>CodeMirror: Upgrading to v3</title>
   6     <link rel="stylesheet" type="text/css" href="http://fonts.googleapis.com/css?family=Droid+Sans|Droid+Sans:bold"/>
   7     <link rel="stylesheet" type="text/css" href="docs.css"/>
   8     <script src="../lib/codemirror.js"></script>
   9     <link rel="stylesheet" href="../lib/codemirror.css">
  10     <script src="../addon/runmode/runmode.js"></script>
  11     <script src="../addon/runmode/colorize.js"></script>
  12     <script src="../mode/javascript/javascript.js"></script>
  13     <script src="../mode/xml/xml.js"></script>
  14     <script src="../mode/css/css.js"></script>
  15     <script src="../mode/htmlmixed/htmlmixed.js"></script>
  16   </head>
  17   <body>
  18
  19 <h1><span class="logo-braces">{ }</span> <a href="http://codemirror.net/">CodeMirror</a></h1>
  20
  21 <div class="grey">
  22 <img src="baboon.png" class="logo" alt="logo"/>
  23 <pre>
  24 /* Upgrading to
  25    version 3 */
  26 </pre>
  27 </div>
  28
  29 <div class="clear"><div class="leftbig blk">
  30
  31 <p>Version 3 does not depart too much from 2.x API, and sites that use
  32 CodeMirror in a very simple way might be able to upgrade without
  33 trouble. But it does introduce a number of incompatibilities. Please
  34 at least skim this text before upgrading.</p>
  35
  36 <p>Note that <strong>version 3 drops full support for Internet
  37 Explorer 7</strong>. The editor will mostly work on that browser, but
  38 it'll be significantly glitchy.</p>
  39
  40 <h2 id=dom>DOM structure</h2>
  41
  42 <p>This one is the most likely to cause problems. The internal
  43 structure of the editor has changed quite a lot, mostly to implement a
  44 new scrolling model.</p>
  45
  46 <p>Editor height is now set on the outer wrapper element (CSS
  47 class <code>CodeMirror</code>), not on the scroller element
  48 (<code>CodeMirror-scroll</code>).</p>
  49
  50 <p>Other nodes were moved, dropped, and added. If you have any code
  51 that makes assumptions about the internal DOM structure of the editor,
  52 you'll have to re-test it and probably update it to work with v3.</p>
  53
  54 <p>See the <a href="manual.html#styling">styling section</a> of the
  55 manual for more information.</p>
  56
  57 <h2 id=gutters>Gutter model</h2>
  58
  59 <p>In CodeMirror 2.x, there was a single gutter, and line markers
  60 created with <code>setMarker</code> would have to somehow coexist with
  61 the line numbers (if present). Version 3 allows you to specify an
  62 array of gutters, <a href="manual.html#option_gutters">by class
  63 name</a>,
  64 use <a href="manual.html#setGutterMarker"><code>setGutterMarker</code></a>
  65 to add or remove markers in individual gutters, and clear whole
  66 gutters
  67 with <a href="manual.html#clearGutter"><code>clearGutter</code></a>.
  68 Gutter markers are now specified as DOM nodes, rather than HTML
  69 snippets.</p>
  70
  71 <p>The gutters no longer horizontally scrolls along with the content.
  72 The <code>fixedGutter</code> option was removed (since it is now the
  73 only behavior).</p>
  74
  75 <pre data-lang="text/html">
  76 &lt;style>
  77   /* Define a gutter style */
  78   .note-gutter { width: 3em; background: cyan; }
  79 &lt;/style>
  80 &lt;script>
  81   // Create an instance with two gutters -- line numbers and notes
  82   var cm = new CodeMirror(document.body, {
  83     gutters: ["note-gutter", "CodeMirror-linenumbers"],
  84     lineNumbers: true
  85   });
  86   // Add a note to line 0
  87   cm.setGutterMarker(0, "note-gutter", document.createTextNode("hi"));
  88 &lt;/script>
  89 </pre>
  90
  91 <h2 id=events>Event handling</h2>
  92
  93 <p>Most of the <code>onXYZ</code> options have been removed. The same
  94 effect is now obtained by calling
  95 the <a href="manual.html#on"><code>on</code></a> method with a string
  96 identifying the event type. Multiple handlers can now be registered
  97 (and individually unregistered) for an event, and objects such as line
  98 handlers now also expose events. See <a href="manual.html#events">the
  99 full list here</a>.</p>
 100
 101 <p>(The <code>onKeyEvent</code> and <code>onDragEvent</code> options,
 102 which act more as hooks than as event handlers, are still there in
 103 their old form.)</p>
 104
 105 <pre data-lang="javascript">
 106 cm.on("change", function(cm, change) {
 107   console.log("something changed! (" + change.origin + ")");
 108 });
 109 </pre>
 110
 111 <h2 id=marktext>markText method arguments</h2>
 112
 113 <p>The <a href="manual.html#markText"><code>markText</code></a> method
 114 (which has gained some interesting new features, such as creating
 115 atomic and read-only spans, or replacing spans with widgets) no longer
 116 takes the CSS class name as a separate argument, but makes it an
 117 optional field in the options object instead.</p>
 118
 119 <pre data-lang="javascript">
 120 // Style first ten lines, and forbid the cursor from entering them
 121 cm.markText({line: 0, ch: 0}, {line: 10, ch: 0}, {
 122   className: "magic-text",
 123   inclusiveLeft: true,
 124   atomic: true
 125 });
 126 </pre>
 127
 128 <h2 id=folding>Line folding</h2>
 129
 130 <p>The interface for hiding lines has been
 131 removed. <a href="manual.html#markText"><code>markText</code></a> can
 132 now be used to do the same in a more flexible and powerful way.</p>
 133
 134 <p>The <a href="../demo/folding.html">folding script</a> has been
 135 updated to use the new interface, and should now be more robust.</p>
 136
 137 <pre data-lang="javascript">
 138 // Fold a range, replacing it with the text "??"
 139 var range = cm.markText({line: 4, ch: 2}, {line: 8, ch: 1}, {
 140   replacedWith: document.createTextNode("??"),
 141   // Auto-unfold when cursor moves into the range
 142   clearOnEnter: true
 143 });
 144 // Get notified when auto-unfolding
 145 CodeMirror.on(range, "clear", function() {
 146   console.log("boom");
 147 });
 148 </pre>
 149
 150 <h2 id=lineclass>Line CSS classes</h2>
 151
 152 <p>The <code>setLineClass</code> method has been replaced
 153 by <a href="manual.html#addLineClass"><code>addLineClass</code></a>
 154 and <a href="manual.html#removeLineClass"><code>removeLineClass</code></a>,
 155 which allow more modular control over the classes attached to a line.</p>
 156
 157 <pre data-lang="javascript">
 158 var marked = cm.addLineClass(10, "background", "highlighted-line");
 159 setTimeout(function() {
 160   cm.removeLineClass(marked, "background", "highlighted-line");
 161 });
 162 </pre>
 163
 164 <h2 id=positions>Position properties</h2>
 165
 166 <p>All methods that take or return objects that represent screen
 167 positions now use <code>{left, top, bottom, right}</code> properties
 168 (not always all of them) instead of the <code>{x, y, yBot}</code> used
 169 by some methods in v2.x.</p>
 170
 171 <p>Affected methods
 172 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>,
 173 and <a href="manual.html#getScrollInfo"><code>getScrollInfo</code></a>.</p>
 174
 175 <h2 id=matchbrackets>Bracket matching no longer in core</h2>
 176
 177 <p>The <a href="manual.html#addon_matchbrackets"><code>matchBrackets</code></a>
 178 option is no longer defined in the core editor.
 179 Load <code>addon/edit/matchbrackets.js</code> to enable it.</p>
 180
 181 <h2 id=modes>Mode management</h2>
 182
 183 <p>The <code>CodeMirror.listModes</code>
 184 and <code>CodeMirror.listMIMEs</code> functions, used for listing
 185 defined modes, are gone. You are now encouraged to simply
 186 inspect <code>CodeMirror.modes</code> (mapping mode names to mode
 187 constructors) and <code>CodeMirror.mimeModes</code> (mapping MIME
 188 strings to mode specs).</p>
 189
 190 <h2 id=new>New features</h2>
 191
 192 <p>Some more reasons to upgrade to version 3.</p>
 193
 194 <ul>
 195   <li>Bi-directional text support. CodeMirror will now mostly do the
 196   right thing when editing Arabic or Hebrew text.</li>
 197   <li>Arbitrary line heights. Using fonts with different heights
 198   inside the editor (whether off by one pixel or fifty) is now
 199   supported and handled gracefully.</li>
 200   <li>In-line widgets. See <a href="../demo/widget.html">the demo</a>
 201   and <a href="manual.html#addLineWidget">the docs</a>.</li>
 202   <li>Defining custom options
 203   with <a href="manual.html#defineOption"><code>CodeMirror.defineOption</code></a>.</li>
 204 </ul>
 205
 206 </div><div class="rightsmall blk">
 207
 208 <h2>Contents</h2>
 209
 210 <ul>
 211   <li><a href="#dom">DOM structure</a></li>
 212   <li><a href="#gutters">Gutter model</a></li>
 213   <li><a href="#events">Event handling</a></li>
 214   <li><a href="#folding">Line folding</a></li>
 215   <li><a href="#marktext">markText method arguments</a></li>
 216   <li><a href="#lineclass">Line CSS classes</a></li>
 217   <li><a href="#positions">Position properties</a></li>
 218   <li><a href="#matchbrackets">Bracket matching</a></li>
 219   <li><a href="#modes">Mode management</a></li>
 220   <li><a href="#new">New features</a></li>
 221 </ul>
 222
 223 </div></div>
 224
 225 <script>setTimeout(function(){CodeMirror.colorize();}, 20);</script>
 226   </body>
 227 </html>