upgrade_v3.html 8.2 KB

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