← Back to branch summary

~ivle-dev/ivle/codemirror

« back to all changes in this revision

Viewing changes to ivle/webapp/filesystem/browser/media/codemirror/manual.html

  • Committer: David Coles
  • Date: 2010-05-31 10:38:53 UTC
  • Revision ID: coles.david@gmail.com-20100531103853-8xypjpracvwy0qt4
Editor: Added CodeMirror-0.67 Javascript code editor source from 
http://marijn.haverbeke.nl/codemirror/ (zlib-style licence)

Show diffs side-by-side

added added

removed removed

Lines of Context:
ivle/webapp/filesystem/browser/media/codemirror/manual.html
 
1
<html xmlns="http://www.w3.org/1999/xhtml">
 
2
  <head>
 
3
    <title>CodeMirror user manual</title>
 
4
    <link rel="stylesheet" type="text/css" href="css/docs.css"/>
 
5
  </head>
 
6
  <body>
 
7
    <h1 class="underline">CodeMirror user manual</h1>
 
8
 
 
9
    <h2>Contents</h2>
 
10
 
 
11
    <ul>
 
12
      <li><a href="#useage">Basic Useage</a></li>
 
13
      <li><a href="#configuration">Configuration</a></li>
 
14
      <li><a href="#parsers">Parsers</a></li>
 
15
      <li><a href="#programming">Programming Interface</a></li>
 
16
      <li><a href="#writeparser">Writing a Parser</a></li>
 
17
    </ul>
 
18
 
 
19
    <h2 id="useage">Basic Usage</h2>
 
20
 
 
21
    <p>Inside the editor, the tab key is used to re-indent the current
 
22
    selection (or the current line when nothing is selected), and
 
23
    pressing enter will, apart from inserting a line break,
 
24
    automatically indent the new line. Pressing control-enter will
 
25
    cause the whole buffer to be re-coloured, which can be helpful
 
26
    when some colouring has become out-of-date without the editor
 
27
    noticing it.</p>
 
28
 
 
29
    <p>The editor sports an undo/redo system, accessible with
 
30
    control-z (undo) and control-y (redo). Safari will not allow
 
31
    client scripts to capture control-z presses, but you can use
 
32
    control-backspace instead on that browser.</p>
 
33
 
 
34
    <p>The key-combination control-[ triggers a paren-blink: If the
 
35
    cursor is directly after a '(', ')', '[', ']', '{', or '}', the
 
36
    editor looks for the matching character, and highlights these
 
37
    characters for a moment. There is an option to enable this to
 
38
    happen any time the user types something or moves the cursor.</p>
 
39
 
 
40
    <p>To use CodeMirror in a document, you should add a script tag to
 
41
    load <a href="js/codemirror.js"><code>codemirror.js</code></a>. This
 
42
    adds two objects to your environment, <code>CodeMirror</code> and
 
43
    <code>CodeMirrorConfig</code>. The first is the interface to the
 
44
    editor, the second can be used to configure it. (Note that this is
 
45
    the only name-space pollution you can expect from CodeMirror --
 
46
    all other cruft is kept inside the IFRAMEs that it creates when
 
47
    you open an editor.)</p>
 
48
 
 
49
    <p>To add an editor to a document, you must choose a place, a
 
50
    parser, and a style-sheet for it. For example, to append an
 
51
    XML editor to the body of the document, you do:</p>
 
52
 
 
53
    <pre class="code">var editor = new CodeMirror(document.body, {
 
54
  parserfile: "parsexml.js",
 
55
  stylesheet: "xmlcolors.css"
 
56
});</pre>
 
57
 
 
58
    <p>The first argument to the <code>CodeMirror</code> constructor
 
59
    can be a DOM node, in which case the editor gets appended to that
 
60
    node, or a function, which will be called with the IFRAME node as
 
61
    argument, and which is expected to place that node somewhere in
 
62
    the document.</p>
 
63
 
 
64
    <p>The second (optional) argument is an object that specifies
 
65
    options. A set of default options (see below) is present in the
 
66
    <code>CodeMirrorConfig</code> object, but each instance of the
 
67
    editor can be given a set of specific options to override these
 
68
    defaults. In this case, we specified that the parser should be
 
69
    loaded from the <a
 
70
    href="js/parsexml.js"><code>"parsexml.js"</code></a> file, and
 
71
    that <a href="css/xmlcolors.css"><code>"xmlcolors.css"</code></a>
 
72
    should be used to specify the colours of the code.</p>
 
73
 
 
74
    <p>Another example:</p>
 
75
 
 
76
    <pre class="code">var editor = new CodeMirror(CodeMirror.replace("inputfield"), {
 
77
  parserfile: ["tokenizejavascript.js", "parsejavascript.js"],
 
78
  path: "lib/codemirror/js/",
 
79
  stylesheet: "lib/codemirror/css/jscolors.css",
 
80
  content: document.getElementById("inputfield").value
 
81
});</pre>
 
82
 
 
83
    <p>Here we use the utility function
 
84
    <code>CodeMirror.replace</code> to create a function that will
 
85
    replace a node in the current document (given either directly or
 
86
    by ID) with the editor. We also select the JavaScript parser this
 
87
    time, and give a <code>path</code> option to tell the editor that
 
88
    its files are not located in the same directory as the current
 
89
    HTML page, but in <code>"lib/codemirror/"</code>.</p>
 
90
 
 
91
    <p>There is a function
 
92
    <code>CodeMirror.isProbablySupported()</code> that causes some
 
93
    1998-style browser detection to happen, returning
 
94
    <code>false</code> if CodeMirror is probably not supported on the
 
95
    browser, <code>true</code> if it probably is, and
 
96
    <code>null</code> if it has no idea. As the name suggests, this is
 
97
    not something you can rely on, but it's usually better than
 
98
    nothing.</p>
 
99
 
 
100
    <p>Another utility function, <code>CodeMirror.fromTextArea</code>,
 
101
    will, given a textarea node or the id of such a node, hide the
 
102
    textarea and replace it with a CodeMirror frame. If the textarea
 
103
    was part of a form, an <code>onsubmit</code> handler will be
 
104
    registered with this form, which will load the content of the
 
105
    editor into the textarea, so that it can be submitted as normal.
 
106
    This function optionally takes a configuration object as second
 
107
    argument.</p>
 
108
 
 
109
    <pre class="code">var editor = CodeMirror.fromTextArea("inputfield", {
 
110
  parserfile: ["tokenizejavascript.js", "parsejavascript.js"],
 
111
  path: "lib/codemirror/js/",
 
112
  stylesheet: "lib/codemirror/css/jscolors.css"
 
113
});</pre>
 
114
 
 
115
    <p>The reason that the script path has to be configured is that
 
116
    CodeMirror will load in a bunch of extra files when an editor is
 
117
    created (the parser script, among others). To be able to do this,
 
118
    it has to know where to find them. These are all the JavaScript
 
119
    files that are part of CodeMirror itself:</p>
 
120
 
 
121
    <dl>
 
122
      <dt><a href="js/codemirror.js"><code>codemirror.js</code></a></dt>
 
123
      <dd>Main interface, takes care of default configuration and the
 
124
      definition of editor frames. Include this in your HTML
 
125
      document.</dd>
 
126
      <dt><a href="js/editor.js"><code>editor.js</code></a></dt> <dd>The
 
127
      code that takes care of reacting to user input, colouring text,
 
128
      and indenting lines.</dd>
 
129
      <dt><a href="js/util.js"><code>util.js</code></a></dt> <dd>A few
 
130
      generic utility functions.</dd>
 
131
      <dt><a
 
132
      href="js/undo.js"><code>undo.js</code></a></dt>
 
133
      <dd>Implements the undo history for the editor.</dd>
 
134
      <dt><a
 
135
      href="js/stringstream.js"><code>stringstream.js</code></a></dt>
 
136
      <dd>Objects for wrapping the textual input to the parser.</dd>
 
137
      <dt><a href="js/select.js"><code>select.js</code></a></dt> <dd>Some
 
138
      helper utilities for working with selected text and cursor
 
139
      positions.</dd>
 
140
      <dt><a href="js/tokenize.js"><code>tokenize.js</code></a></dt>
 
141
      <dd>Helper framework for writing tokenisers.</dd>
 
142
    </dl>
 
143
 
 
144
    <p>Most of these are rather full of comments, which can be useful
 
145
    when you are trying to figure out how they work, but wastes a lot
 
146
    of bandwidth in a production system. Take a look at the
 
147
    description of the <code>basefiles</code> option below if you want
 
148
    to concatenate and minimise the library.</p>
 
149
 
 
150
    <p>Apart from these, there are files that implement the various
 
151
    parsers. These all start with either <code>parse</code> or
 
152
    <code>tokenize</code>.</p>
 
153
 
 
154
    <h2 id="configuration">Configuration</h2>
 
155
 
 
156
    <p>There are three ways to configure CodeMirror:</p>
 
157
 
 
158
    <ul>
 
159
      <li>If you define a global <code>CodeMirrorConfig</code> object
 
160
      before loading <a
 
161
      href="js/codemirror.js"><code>codemirror.js</code></a>, the
 
162
      configuration options in that object will override the
 
163
      defaults.</li>
 
164
      <li>By assigning to the properties of the
 
165
      <code>CodeMirrorConfig</code> object, configuration defaults can
 
166
      be overridden after loading <a
 
167
      href="js/codemirror.js"><code>codemirror.js</code></a>.</li>
 
168
      <li>The <code>CodeMirror</code> constructor can be given a second
 
169
      argument, an object, which will override some options for just
 
170
      that editor. Options not mentioned in this object will default to
 
171
      the values in the <code>CodeMirrorConfig</code> object.</li>
 
172
    </ul>
 
173
 
 
174
    <p>The options that can be specified are these (most have sensible
 
175
    defaults specified in <a
 
176
    href="js/codemirror.js"><code>codemirror.js</code></a>):</p>
 
177
 
 
178
    <dl>
 
179
 
 
180
      <dt><code>stylesheet</code></dt><dd>The file name of the
 
181
      style-sheet, or style-sheets, that should be used to colour the
 
182
      code in the editor frame. Can be a string or an array of
 
183
      strings. See <a
 
184
      href="css/jscolors.css"><code>jscolors.css</code></a> for an
 
185
      example. The set of active stylesheets can be changed in a
 
186
      running editor with the <code>setStylesheet</code> method, which
 
187
      also takes a string or array of strings as argument.</dd>
 
188
 
 
189
      <dt><code>path</code></dt><dd>The path that is prefixed to
 
190
      script file names when they are loaded into an IFRAME. (Note that
 
191
      this is not applied to the style-sheet file name.)</dd>
 
192
 
 
193
      <dt><code>parserfile</code></dt><dd>A file name string, or an
 
194
      array of strings that name the files containing the parser. See
 
195
      below for the interface that such a parser should
 
196
      implement.</dd>
 
197
 
 
198
      <dt><code>basefiles</code></dt><dd>An array of strings naming
 
199
      the files containing the base CodeMirror functionality. Defaults
 
200
      to <code>["util.js", "stringstream.js", "select.js", "undo.js",
 
201
      "editor.js", "tokenize.js"]</code>, but if you put them all into
 
202
      a single file to reduce latency, or add some functionality, you
 
203
      might have to adjust that.</dd>
 
204
 
 
205
      <dt><code>iframeClass</code></dt><dd>Set this to a string to
 
206
      give the IFRAME node created for the editor a custom CSS class.
 
207
      Defaults to <code>null</code>.</dd>
 
208
      
 
209
      <dt><code>passDelay</code></dt><dd>Gives the amount of
 
210
      milliseconds between colouring passes. Defaults to 200.</dd>
 
211
 
 
212
      <dt><code>passTime</code></dt><dd>Specifies the maximum amount
 
213
      of time that the highlighter will spend in one shot. Setting
 
214
      this too high will cause the editor to 'freeze' the browser for
 
215
      noticeable intervals. Defaults to 50.</dd>
 
216
 
 
217
      <dt><code>continuousScanning</code></dt><dd>Configure continuous
 
218
      scanning of the document. When <code>false</code>, scanning is
 
219
      disabled. When set to a number, say <code>N</code>, a
 
220
      'background' process will scan the document for
 
221
      <code>passTime</code> (see above) milliseconds every
 
222
      <code>N</code> milliseconds, regardless of whether anything
 
223
      changed. This makes sure non-local changes propagate through the
 
224
      document, and will help keep everything consistent. It does add
 
225
      extra processing cost, even for an idle editor. Default value is
 
226
      <code>false</code>.</dd>
 
227
 
 
228
      <dt><code>autoMatchParens</code></dt><dd>When <code>true</code>,
 
229
      will cause parens to be matched every time a key is pressed or
 
230
      the user clicks on the document. Defaults to <code>false</code>.
 
231
      Might be expensive for big documents.</dd>
 
232
 
 
233
      <dt><code>markParen</code>,
 
234
      <code>unmarkParen</code></dt><dd>Functions. Can be used to
 
235
      customise the way brackets are marked (and unmarked) when
 
236
      matched. Both take the bracket's <code>SPAN</code> node as their
 
237
      first argument, and <code>markParen</code> takes a second
 
238
      boolean argument indicating whether a successful match was
 
239
      found. The default is to make the brackets bold and green (or
 
240
      red, if not matched).</dd>
 
241
 
 
242
      <dt><code>saveFunction</code></dt><dd>If given a function
 
243
      value, that function will be invoked when the user presses
 
244
      control-s. You should advise your Opera users to use
 
245
      control-shift-s instead, since plain control-s will bring up the
 
246
      'save page' dialog. Defaults to <code>null</code>.</dd>
 
247
 
 
248
      <dt><code>undoDepth</code></dt><dd>Maximum length of the undo
 
249
      history. Default is 50. This setting is changeable with the
 
250
      <code>setUndoDepth(depth)</code> method on CodeMirror
 
251
      instances.</dd>
 
252
 
 
253
      <dt><code>onChange</code></dt><dd>An optional function of zero
 
254
      arguments that gets called whenever the document is changed.
 
255
      Happens at undo-commit time, not instantaniously.</dd>
 
256
 
 
257
      <dt><code>undoDelay</code></dt><dd>When nothing is done in the
 
258
      editor for this amount of milliseconds, pending changes get
 
259
      added to the undo history. Setting this lower will give the undo
 
260
      functionality a finer granularity. Defaults to 800.</dd>
 
261
 
 
262
      <dt><code>width</code>, <code>height</code></dt><dd>The size of
 
263
      the editor frame, given as a style-sheet quantities (for example
 
264
      <code>"600px"</code> or <code>"100%"</code>).</dd>
 
265
 
 
266
      <dt><code>disableSpellcheck</code></dt><dd>Should the editor
 
267
      disable spell-checking on browsers that support it (Firefox 2+).
 
268
      Default is <code>true</code>, since for most code spell-checking
 
269
      is useless. Can be changed with the
 
270
      <code>setSpellCheck(on)</code> method.</dd>
 
271
 
 
272
      <dt><code>textWrapping</code></dt><dd>Can be used to disable or
 
273
      enable text-wrapping in the editor frame. Default is
 
274
      <code>true</code>. Changeable with the
 
275
      <code>setTextWrapping(on)</code> method.</dd>
 
276
 
 
277
      <dt><code>lineNumbers</code></dt><dd>Show line numbers to the
 
278
      left of the editor. This requires you to specify a style for the
 
279
      <code>CodeMirror-line-numbers</code> CSS class (in the outer
 
280
      document) to configure the width, font, colors, etcetera for the
 
281
      line-number DIV. You have to make sure that lines in the
 
282
      numbering element have the same height as lines in the editor.
 
283
      This is most easily done by giving them both the same font and
 
284
      an absolute ('pt' or 'px') font size. This option defaults to
 
285
      <code>false</code>. Changeable with the
 
286
      <code>setLineNumbers(on)</code> method.</dd>
 
287
 
 
288
      <dt><code>lineNumberDelay</code>,
 
289
      <code>lineNumberTime</code></dt><dd>When both line numbers are
 
290
      and text wrapping are turned on, updating line numbers can be
 
291
      expensive. These settings can be used to control how fast the
 
292
      updating happens &#x2015; they work in the same way as
 
293
      <code>passDelay</code> and <code>passTime</code>.</dd>
 
294
 
 
295
      <dt><code>indentUnit</code></dt><dd>An integer that specifies
 
296
      the amount of spaces one 'level' of indentation should add.
 
297
      Default is <code>2</code>. Changeable in a running editor using
 
298
      the <code>setIndentUnit(spaces)</code> method.</dd>
 
299
 
 
300
      <dt><code>tabMode</code></dt><dd>Determines what the effect of
 
301
      pressing tab is. Possibilities are:
 
302
      <dl>
 
303
        <dt><code>"indent"</code></dt><dd>The default. Causes tab to
 
304
        adjust the indentation of the selection or current line using
 
305
        the parser's rules.</dd>
 
306
        <dt><code>"spaces"</code></dt><dd>Pressing tab simply inserts
 
307
        four spaces.</dd>
 
308
        <dt><code>"default"</code></dt><dd>CodeMirror does not
 
309
        interfere with the tab key, but leaves it to the browser to
 
310
        handle it. Binds shift-space to regular indentation
 
311
        behaviour.</dd>
 
312
        <dt><code>"shift"</code></dt><dd>Pressing tab indents the
 
313
        current line (or selection) one <code>indentUnit</code>
 
314
        deeper, pressing shift-tab, un-indents it.</dd>
 
315
      </dl>
 
316
      This option can be changed at run-time using the
 
317
      <code>setTabMode(mode)</code> method.</dd>
 
318
 
 
319
      <dt><code>reindentOnLoad</code></dt><dd>When <code>true</code>,
 
320
      this causes the content of the editor to be reindented
 
321
      immediately when the editor loads. Defaults to
 
322
      <code>false</code>.</dd>
 
323
 
 
324
      <dt><code>readOnly</code></dt><dd>When set to <code>true</code>,
 
325
      the document is not editable.</dd>
 
326
 
 
327
      <dt><code>domain</code></dt><dd>Can be set to the value
 
328
      <code>document.domain</code> should have inside of the iframe.
 
329
      Used to prevent access issues in IE, where this value isn't
 
330
      automatically inherited by iframes.</dd>
 
331
 
 
332
      <dt><code>initCallback</code></dt><dd>If set to a function, this
 
333
      will be called (with the editor object as its argument) after
 
334
      the editor has finished initialising.</dd>
 
335
      
 
336
      <dt><code>cursorActivity</code></dt><dd>A function that is
 
337
      called every time the cursor moves, with the top-level node that
 
338
      the cursor is inside or next to as an argument. Can be used to
 
339
      have some controls react to the context of the cursor.</dd>
 
340
 
 
341
      <dt><code>activeTokens</code></dt><dd>Can be set to a function
 
342
      that will be called with <code>(spanNode, tokenObject,
 
343
      editor)</code> arguments whenever a new token node is being
 
344
      added to the document. Can be used to do things like add event
 
345
      handlers to nodes. Should <em>not</em> change the DOM structure
 
346
      of the node (so no turning the span into a link), since this
 
347
      will greatly confuse the editor.</dd>
 
348
 
 
349
      <dt id="parserConfig"><code>parserConfig</code></dt><dd>An
 
350
      object value that is passed along to the parser to configure it.
 
351
      What this object should look like depends on the parser
 
352
      used.</dd>
 
353
 
 
354
      <dt><code>content</code></dt><dd>The starting content of the
 
355
      editor. You'll probably not want to provide a global default for
 
356
      this, but add it to the <code>options</code> object passed to
 
357
      individual editors as they are created.</dd>
 
358
 
 
359
    </dl>
 
360
 
 
361
    <h2 id="parsers">Parsers</h2>
 
362
 
 
363
    <p>(If you want to use a CodeMirror parser to highlight a piece of
 
364
    text, without creating an editor, see <a
 
365
    href="highlight.html">this example</a>, and the <code><a
 
366
    href="js/highlight.js">highlight.js</a></code> script.)</p>
 
367
 
 
368
    <p>The following parsers come with the distribution of CodeMirror:</p>
 
369
 
 
370
    <dl>
 
371
      <dt><code><a href="js/parsexml.js">parsexml.js</a></code> (<a
 
372
      href="htmltest.html">demo</a>)</dt><dd>A HTML/XML parser. Takes
 
373
      a <code>useHTMLKludges</code> configuration option (see the
 
374
      <code><a href="#parserConfig">parserConfig</a></code> option
 
375
      above), which specifies whether the content of the editor is
 
376
      HTML or XML, and things like self-closing tags (<code>br</code>,
 
377
      <code>img</code>) exist. This defaults to <code>true</code>.
 
378
      Example colours for the styles that this parser uses are defined
 
379
      in <code><a
 
380
      href="css/xmlcolors.css">css/xmlcolors.css</a></code>.</dd>
 
381
 
 
382
      <dt><code><a
 
383
      href="js/tokenizejavascript.js">tokenizejavascript.js</a></code>,
 
384
      <code><a
 
385
      href="js/parsejavascript.js">parseejavascript.js</a></code> (<a
 
386
      href="jstest.html">demo</a>)</dt><dd>The JavaScript parser.
 
387
      Example colours in <code><a
 
388
      href="css/jscolors.css">css/jscolors.css</a></code>. Takes one
 
389
      configuration option, <code>json</code>, that can be set when
 
390
      the editor content is JSON data. It causes every opening brace
 
391
      to be treated as the start of an object, rather than a
 
392
      block.</dd>
 
393
 
 
394
      <dt><code><a href="js/parsecss.js">parsecss.js</a></code> (<a
 
395
      href="csstest.html">demo</a>)</dt><dd>A CSS parser. Styles in
 
396
      <code><a
 
397
      href="css/csscolors.css">css/csscolors.css</a></code></dd>
 
398
 
 
399
      <dt><code><a
 
400
      href="js/parsehtmlmixed.js">parsehtmlmixed.js</a></code> (<a
 
401
      href="mixedtest.html">demo</a>)</dt><dd>A mixed-mode HTML
 
402
      parser. Requires the XML, JavaScript, and CSS parsers to also be
 
403
      loaded, so your <code>parserfile</code> option looks something
 
404
      like <code>["parsexml.js", "parsecss.js",
 
405
      "tokenizejavascript.js", "parsejavascript.js",
 
406
      "parsehtmlmixed.js"]</code>.</dd>
 
407
 
 
408
      <dt><code><a href="js/parsesparql.js">parsesparql.js</a></code>
 
409
      (<a href="sparqltest.html">demo</a>)</dt><dd>Parses the <a
 
410
      href="http://en.wikipedia.org/wiki/SPARQL">SPARQL</a> query
 
411
      language. Example styles in <code><a
 
412
      href="css/sparqlcolors.css">css/sparqlcolors.css</a></code></dd>
 
413
 
 
414
      <dt><code><a
 
415
      href="js/parsedummy.js">parsedummy.js</a></code></dt><dd>A
 
416
      'dummy' parser to make it possible to edit plain text, or
 
417
      documents for which no suitable parser exists.</dd>
 
418
 
 
419
      <dt><code><a
 
420
      href="contrib/php/js/parsephp.js">contrib/php/js/parsephp.js</a></code>
 
421
      (<a href="contrib/php/index.html">demo</a>)</dt><dd>PHP
 
422
      parser.</dd>
 
423
 
 
424
      <dt><code><a
 
425
      href="contrib/python/js/parsepython.js">contrib/python/js/parsepython.js</a></code>
 
426
      (<a href="contrib/python/index.html">demo</a>)</dt><dd>Python
 
427
      parser.</dd>
 
428
 
 
429
      <dt><code><a href="contrib/lua/js/parselua.js">contrib/lua/js/parselua.js</a></code>
 
430
      (<a href="contrib/lua/index.html">demo</a>)</dt><dd>Lua
 
431
      parser.</dd>
 
432
 
 
433
    </dl>
 
434
 
 
435
    <h2 id="programming">Programming Interface</h2>
 
436
 
 
437
    <p>To be as flexible as possible, CodeMirror implements a very
 
438
    plain editable field, without any accompanying buttons, bells, and
 
439
    whistles. <code>CodeMirror</code> objects do, however, provide a
 
440
    number of methods and properties that make it possible to add
 
441
    extra functionality around the editor. <a
 
442
    href="js/mirrorframe.js"><code>mirrorframe.js</code></a> provides
 
443
    a basic example of their usage.</p>
 
444
 
 
445
    <h3>Properties</h3>
 
446
 
 
447
    <dl>
 
448
      <dt><code>frame</code></dt><dd>The editable frame.</dd>
 
449
      <dt><code>win</code></dt><dd>The window of the editable frame.
 
450
      Mostly useful for attaching event handlers.</dd>
 
451
      <dt><code>wrapping</code></dt><dd>The <code>DIV</code> element
 
452
      wrapped around the frame. This always has a CSS class of
 
453
      <code>CodeMirror-wrapping</code>.</dd>
 
454
    </dl>
 
455
 
 
456
    <h3>Methods</h3>
 
457
 
 
458
    <dl>
 
459
      <dt><code>getCode()</code> &#8594;
 
460
      <code>string</code></dt><dd>Returns the current content of the
 
461
      editor, as a string.</dd>
 
462
 
 
463
      <dt><code>setCode(string)</code></dt><dd>Replaces the current
 
464
      content of the editor with the given value.</dd>
 
465
 
 
466
      <dt><code>focus()</code></dt><dd>Gives focus to the editor
 
467
      frame.</dd>
 
468
 
 
469
      <dt><code>selection()</code> &#8594;
 
470
      <code>string</code></dt><dd>Returns the text that is currently
 
471
      selected in the editor.</dd>
 
472
 
 
473
      <dt><code>replaceSelection(string)</code></dt><dd>Replaces the
 
474
      currently selected text with the given string. Will also cause
 
475
      the editor frame to gain focus.</dd>
 
476
 
 
477
      <dt><code>reindent()</code></dt><dd>Automatically re-indent the
 
478
      whole document.</dd>
 
479
 
 
480
      <dt><code>reindentSelection()</code></dt><dd>Automatically
 
481
      re-indent the selected lines.</dd>
 
482
 
 
483
      <dt><code>getSearchCursor(string, atCursor, caseFold)</code>
 
484
      &#8594; <code>cursor</code></dt><dd>The first argument indicates
 
485
      the string that should be searched for, and the second indicates
 
486
      whether searching should start at the cursor (<code>true</code>)
 
487
      or at the start of the document (<code>false</code>). When
 
488
      <code>caseFold</code> is true, the search will be
 
489
      case-insensivive. Returns an object that provides an interface
 
490
      for searching. Call its <code>findNext()</code> method to search
 
491
      for an occurrence of the given string. This returns
 
492
      <code>true</code> if something is found, or <code>false</code>
 
493
      if the end of document is reached. When an occurrence has been
 
494
      found, you can call <code>select()</code> to select it, or
 
495
      <code>replace(string)</code> to replace it with a given string.
 
496
      Note that letting the user change the document, or
 
497
      programmatically changing it in any way except for calling
 
498
      <code>replace</code> on the cursor itself, might cause a cursor
 
499
      object to skip back to the beginning of the document.</dd>
 
500
 
 
501
      <dt><code>undo()</code></dt><dd>Undo one changeset, if available.</dd>
 
502
      <dt><code>redo()</code></dt><dd>Redo one changeset, if available.</dd>
 
503
      <dt><code>historySize() &#8594; object</code></dt><dd>Get a
 
504
      <code>{undo, redo}</code> object holding the sizes of the undo
 
505
      and redo histories.</dd>
 
506
      <dt><code>clearHistory()</code></dt><dd>Drop all history
 
507
      information.</dd>
 
508
 
 
509
      <dt><code>grabKeys(callback, filter)</code></dt><dd>Route
 
510
      keyboard input in the editor to a callback function. This
 
511
      function is given a slightly normalised (see
 
512
      <code>normalizeEvent</code> in <a
 
513
      href="js/util.js"><code>util.js</code></a>) <code>keydown</code>
 
514
      event object. If a second argument is given, this will be used
 
515
      to determine which events to apply the callback to. It should
 
516
      take a key code (as in <code>event.keyCode</code>), and return a
 
517
      boolean, where <code>true</code> means the event should be
 
518
      routed to the callback, and <code>false</code> leaves the key to
 
519
      perform its normal behaviour.</dd>
 
520
      <dt><code>ungrabKeys()</code></dt><dd>Revert the effect of
 
521
      <code>grabKeys</code>.</dd>
 
522
 
 
523
      <dt><code>setParser(name)</code></dt><dd>Change the active
 
524
      parser. To use this you'll have to load more than one parser
 
525
      (put the one you want to use as default at the end of the list).
 
526
      Then call this function with a string containing the name of the
 
527
      parser you want to switch to (see the parser script file to find
 
528
      the name, it'll be something like <code>CSSParser</code>).</dd>
 
529
    </dl>
 
530
 
 
531
    <p>For detailed interaction with the content of the editor,
 
532
    CodeMirror exposes a line-oriented interface, which allows you to
 
533
    inspect and manipulate the document line by line. Line handles
 
534
    should be considered opaque (they are in fact the <code>BR</code>
 
535
    nodes at the start of the line), except that the value
 
536
    <code>false</code> (but <em>not</em> <code>null</code>) always
 
537
    denotes an invalid value. Since changing the document might cause
 
538
    some line handles to become invalid, every function that takes
 
539
    them as argument can throw
 
540
    <code>CodeMirror.InvalidLineHandle</code>. These are the relevant
 
541
    methods:</p>
 
542
 
 
543
    <dl>
 
544
      <dt><code>cursorPosition(start)</code> &#8594;
 
545
      <code>object</code></dt><dd>Retrieve a <code>{line,
 
546
      character}</code> object representing the cursor position.
 
547
      <code>start</code> defaults to <code>true</code> and determines
 
548
      if the startpoint or the endpoint of the selection is used.</dd>
 
549
      <dt><code>cursorLine()</code> &#8594;
 
550
      <code>handle</code></dt><dd>Returns the line on which the cursor
 
551
      is currently sitting.</dd>
 
552
      <dt><code>firstLine()</code> &#8594;
 
553
      <code>handle</code></dt><dd>Get the first line of the
 
554
      document.</dd>
 
555
      <dt><code>lastLine()</code> &#8594;
 
556
      <code>handle</code></dt><dd>The last line.</dd>
 
557
      <dt><code>nextLine(handle)</code> &#8594;
 
558
      <code>handle</code></dt><dd>Get the line after the given one, or
 
559
      <code>false</code> if that was the last line.</dd>
 
560
      <dt><code>prevLine(handle)</code> &#8594;
 
561
      <code>handle</code></dt><dd>Find the line before the given one,
 
562
      return <code>false</code> if that was the first line.</dd>
 
563
      <dt><code>nthLine(number)</code> &#8594;
 
564
      <code>handle</code></dt><dd>Find the Nth line of the document.
 
565
      Note that the first line counts as one, not zero. Returns
 
566
      <code>false</code> if there is no such line.</dd>
 
567
      <dt><code>lineContent(handle)</code> &#8594;
 
568
      <code>string</code></dt><dd>Retrieve the content of the
 
569
      line.</dd>
 
570
      <dt><code>setLineContent(handle, string)</code></dt><dd>Replace
 
571
      the content of the line with the given string.</dd>
 
572
      <dt><code>removeLine(handle)</code></dt><dd>Remove the given
 
573
      line from the editor. The handle will stay valid after this
 
574
      operation, and now refers to the next line.</dd>
 
575
      <dt><code>lineNumber(handle)</code> &#8594;
 
576
      <code>number</code></dt><dd>Ask which line of the document
 
577
      (1-based) the given line is.</dd>
 
578
      <dt><code>jumpToLine(handle)</code></dt><dd>Moves the cursor to
 
579
      the start of the given line.</dd>
 
580
      <dt><code>selectLines(startHandle, startOffset,
 
581
      endHandle, endOffset)</code></dt><dd>Move the selection to a
 
582
      specific point. <code>endHandle</code> and
 
583
      <code>endOffset</code> can be omitted to just place the cursor
 
584
      somewhere without selecting any text.</dd>
 
585
      <dt><code>insertIntoLine(handle, position,
 
586
      text)</code></dt><dd>Insert a piece of text into a line.
 
587
      <code>position</code> can be an integer, specifying the position
 
588
      in the line where the text should be inserted, or the string
 
589
      <code>"end"</code>, for the end of the line.</dd>
 
590
    </dl>
 
591
 
 
592
    <h2 id="writeparser">Writing a Parser</h2>
 
593
 
 
594
    <p>A parser is implemented by one or more files (see
 
595
    <code>parserfile</code> above) which, when loaded, add a
 
596
    <code>Parser</code> property to the <code>Editor</code> object
 
597
    defined by <a href="js/editor.js"><code>editor.js</code></a>. This
 
598
    object must support the following interface:</p>
 
599
 
 
600
    <dl>
 
601
 
 
602
      <dt><code>make(stream)</code></dt><dd>A function that, given a
 
603
      string stream (see <a
 
604
      href="js/stringstream.js"><code>stringstream.js</code></a>),
 
605
      creates a parser. The behaviour of this parser is described
 
606
      below.</dd>
 
607
 
 
608
      <dt><code>electricChars</code></dt><dd>An optional string
 
609
      containing the characters that, when typed, should cause the
 
610
      indentation of the current line to be recomputed (for example
 
611
      <code>"{}"</code> for c-like languages).</dd>
 
612
 
 
613
      <dt><code>configure(object)</code></dt><dd>An optional function
 
614
      that can be used to configure the parser. If it exists, and an
 
615
      editor is given a <code>parserConfig</code> option, it will be
 
616
      called with the value of that option.</dd>
 
617
 
 
618
      <dt><code>firstIndentation(chars, current,
 
619
      direction)</code></dt><dd>An optional function that is used to
 
620
      determine the proper indentation of the first line of a
 
621
      document. When not provided, <code>0</code> is used.</dd>
 
622
    </dl>
 
623
 
 
624
    <p>When the <code>make</code> method is called with a string
 
625
    stream, it should return a MochiKit-style iterator: an object with
 
626
    a <code>next</code> method, which will raise
 
627
    <code>StopIteration</code> when it is at its end (see <a
 
628
    href="http://bob.pythonmac.org/archives/2005/07/06/iteration-in-javascript/">this</a>
 
629
    for details). This iterator, when called, will consume input from
 
630
    the string stream, and produce a token object.</p>
 
631
 
 
632
    <p>Token objects represent a single significant piece of the text
 
633
    that is being edited. A token object must have a
 
634
    <code>value</code> property holding the text it stands for, and a
 
635
    <code>style</code> property with the CSS class that should be used
 
636
    to colour this element. This can be anything, except that any
 
637
    whitespace at the start of a line should <em>always</em> have
 
638
    class <code>"whitespace"</code>: The editor must be able to
 
639
    recognize these when it indents lines. Furthermore, each newline
 
640
    character <em>must</em> have its own separate token, which has an
 
641
    <code>indentation</code> property holding a function that can be
 
642
    used to determine the proper indentation level for the next line.
 
643
    This function optionally takes the text in the first token of the
 
644
    next line, the current indentation of the line, and the
 
645
    'direction' of the indentation as arguments, which it can use to
 
646
    adjust the indentation level. The direction argument is only
 
647
    useful for modes in which lines do not have a fixed indentation,
 
648
    and can be modified by multiple tab presses. It is
 
649
    <code>null</code> for 'default' indentations (like what happens
 
650
    when the user presses enter), <code>true</code> for regular tab
 
651
    presses, and <code>false</code> for control-tab or shift-tab.</p>
 
652
 
 
653
    <p>So far this should be pretty easy. The hard part is that this
 
654
    iterator must also have a <code>copy</code> method. This method,
 
655
    called without arguments, returns a function representing the
 
656
    current state of the parser. When this state function is later
 
657
    called with a string stream as its argument, it returns a parser
 
658
    object that resumes parsing using the old state and the new input
 
659
    stream. It may assume that only one parser is active at a time,
 
660
    and can clobber the state of the old parser if it wants.</p>
 
661
 
 
662
    <p>For examples, see <a
 
663
    href="js/parsejavascript.js"><code>parsejavascript.js</code></a>,
 
664
    <a href="js/parsexml.js"><code>parsexml.js</code></a>, and <a
 
665
    href="js/parsecss.js"><code>parsecss.js</code></a>.</p>
 
666
 
 
667
  </body>
 
668
</html>