editor/docs/midas-spec.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3 <head>
   4   <meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
   5   <title>Midas Specification</title>
   6   <meta name="author" content="Kathleen Brade">
   7   <style type="text/css">
   8   td { vertical-align: top;  }
   9   </style>
  10 </head>
  11 <body>
  12 Last revised:&nbsp; August 23, 2005<br>
  13 <br>
  14 This document describes the rich text editing controls for web pages
  15 available in recent mozilla browsers.<br>
  16 <br>
  17 <h1> Enabling Rich Text Editing in your web page:</h1>
  18 <div style="margin-left: 40px;">Given a document, you can add the
  19 attribute "designMode" and set it to "on" to get an editable document.&nbsp;
  20 For example, in JavaScript, if you have an iframe with an id of 'edit', you
  21 can get its contentDocument and set designMode to "on" like this:<br>
  22 <div style="margin-left: 40px;"><code>document.getElementById("edit").contentDocument.designMode="on";</code></div>
  23 <br>
  24 Right now, you can't completely turn off editing by setting designMode
  25 to "off."&nbsp; Setting designMode to "off" will prevent certain operations
  26 from being handled but typing and other actions are still possible.<br>
  27 </div>
  28 <br>
  29 <h1>Invoking Commands:</h1>
  30 <h2>execCommand</h2>
  31 <div style="margin-left: 40px;">Given a document that has rich text
  32 editing enabled (see above), you can invoke specific commands on the
  33 document by calling execCommand with 3 parameters.&nbsp; For example,
  34 in JavaScript, if you have an editable document,
  35 you can invoke the bold command by calling this:<br>
  36 <div style="margin-left: 40px;"><code>editableDocument.execCommand("Bold",
  37 false, null);</code></div><br>
  38 Notes:&nbsp; If you haven't set designMode to "On", you will get an
  39 error.&nbsp; This could also happen if you call execCommand with the wrong
  40 document.<br>
  41 <br>
  42 There are 3 required parameters for execCommand:<br>
  43 <ol>
  44   <li>command string</li>
  45   <li>boolean flag for showing UI</li>
  46   <li>value string</li>
  47 </ol>
  48 The first parameter is a string which contains the command.&nbsp; The
  49 second parameter is a boolean flag. &nbsp;If it is set to true, you will
  50 get an error (NS_ERROR_NOT_IMPLEMENTED). &nbsp;The third parameter is a
  51 string which is the value.&nbsp; Some commands will require details such
  52 as the particular size you want to set when setting a font size.<br>
  53 <br>
  54 The section on Supported Commands will document each command and any
  55 corresponding values needed.<br>
  56 </div>
  57 <div style="margin-left: 40px;"> </div>
  58 <br>
  59 <h2>queryCommandEnabled</h2>
  60 <blockquote>This command operates on the editable document.&nbsp; There
  61 is one required parameter (the command string). &nbsp;The result is a
  62 boolean which is true if the command is can be done given the current
  63 selection and/or caret position. &nbsp;The result is false if the command
  64 should not be invoked (execCommand) given the current selection and/or
  65 caret position.<br>
  66 </blockquote>
  67 <br>
  68 <h2>queryCommandState</h2>
  69 <blockquote>This section needs to be written.&nbsp; It can be called
  70 similarly to IE implementation.<br>
  71 </blockquote>
  72 <br>
  73 <h2>queryCommandValue</h2>
  74 <blockquote> This section needs to be written.&nbsp; It can be called
  75 similarly to IE implementation.
  76 </blockquote>
  77 <br>
  78 <h1>Supported Commands:</h1>
  79 <div style="margin-left: 40px;">The following list of commands is
  80 presented in alphabetical order. &nbsp;The commands may be mixed case
  81 or whatever makes your code more readable.<br>
  82 <br>
  83 <table cellpadding="4" cellspacing="0" border="1"
  84  style="text-align: left; width: 100%;">
  85   <tbody>
  86     <tr>
  87       <td>command</td>
  88       <td>value</td>
  89       <td>explanation / behavior</td>
  90     </tr>
  91     <tr>
  92       <td>backcolor</td>
  93       <td>????</td>
  94       <td>This command will set the background color of the document.</td>
  95     </tr>
  96     <tr>
  97       <td>bold</td>
  98       <td>none</td>
  99       <td>If there is no selection, the insertion
 100 point will set bold for subsequently typed characters.<br>
 101       <br>
 102 If there is a selection and all of the characters are already bold, the
 103 bold will be removed. &nbsp;Otherwise, all selected characters will become
 104 bold.</td>
 105     </tr>
 106     <tr>
 107       <td>contentReadOnly</td>
 108       <td>true<br>false</td>
 109       <td>This command will make the editor readonly (true) or editable
 110 (false).&nbsp; Anticipated usage is for temporarily disabling input while
 111 something else is occurring elsewhere in the web page.</td>
 112     </tr>
 113     <tr>
 114       <td>copy</td>
 115       <td>none</td>
 116       <td>If there is a selection, this command will copy the selection
 117 to the clipboard.&nbsp; If there isn't a selection, nothing will happen.<br>
 118       <br>
 119 note: this command won't work without setting a pref or using signed
 120 JS.&nbsp; See: http://www.mozilla.org/editor/midasdemo/securityprefs.html<br>
 121       <br>
 122 note:&nbsp; the shortcut key will automatically trigger this command
 123 (typically accel-C) with or without the signed JS or any code on the page to
 124 handle it.</td>
 125     </tr>
 126     <tr>
 127       <td>createlink</td>
 128       <td>url (href)</td>
 129       <td>This command will not do anything if no selection
 130 is made. &nbsp;If there is a selection, a link will be inserted around
 131 the selection with the url parameter as the href of the link.</td>
 132     </tr>
 133     <tr>
 134       <td>cut</td>
 135       <td>none</td>
 136       <td>If there is a selection, this command will copy the selection
 137 to the clipboard and remove the selection from the edit control.&nbsp;
 138 If there isn't a selection, nothing will happen.<br>
 139       <br>
 140 note: this command won't work without setting a pref or using signed
 141 JS.&nbsp; See: http://www.mozilla.org/editor/midasdemo/securityprefs.html<br>
 142       <br>
 143 note: &nbsp;the shortcut key will automatically trigger this command
 144 (typically accel-X) with or without the signed JS or any code on the page to
 145 handle it.</td>
 146     </tr>
 147     <tr>
 148       <td>decreasefontsize</td>
 149       <td>none</td>
 150       <td>This command will add a &lt;small&gt; tag around selection or
 151 at insertion point.</td>
 152     </tr>
 153     <tr>
 154       <td>delete</td>
 155       <td>none</td>
 156       <td>This command will delete all text and objects that
 157 are selected.</td>
 158     </tr>
 159     <tr>
 160       <td>fontname</td>
 161       <td>????</td>
 162       <td>This command will set the fontface for a selection
 163 or at the insertion point if there is no selection.</td>
 164     </tr>
 165     <tr>
 166       <td>fontsize</td>
 167       <td>????</td>
 168       <td>This command will set the fontsize for a selection
 169 or at the insertion point if there is no selection.</td>
 170     </tr>
 171     <tr>
 172       <td>forecolor</td>
 173       <td>????</td>
 174       <td>This command will set the text color of the
 175 selection or at the insertion point.</td>
 176     </tr>
 177     <tr>
 178       <td>formatblock</td>
 179       <td>&lt;h1&gt;<br>
 180 &lt;h2&gt;<br>
 181 &lt;h3&gt;<br>
 182 &lt;h4&gt;<br>
 183 &lt;h5&gt;<br>
 184 &lt;h6&gt;<br>
 185 &lt;pre&gt;<br>
 186 &lt;address&gt;<br>
 187 &lt;p&gt;<br>
 188 p<br>
 189 [this list may not be complete]</td>
 190       <td><br></td>
 191     </tr>
 192     <tr>
 193       <td>heading</td>
 194       <td>&lt;h1&gt;<br>
 195 &lt;h2&gt;<br>
 196 &lt;h3&gt;<br>
 197 &lt;h4&gt;<br>
 198 &lt;h5&gt;<br>
 199 &lt;h6&gt;</td>
 200       <td><br></td>
 201     </tr>
 202     <tr>
 203       <td>hilitecolor</td>
 204       <td>????</td>
 205       <td>This command will set the hilite color of the selection or at
 206 the insertion point.&nbsp; It only works with usecss enabled.</td>
 207     </tr>
 208     <tr>
 209       <td>increasefontsize</td>
 210       <td>none</td>
 211       <td>This command will add a
 212 &lt;big&gt; tag around selection or at insertion point.</td>
 213     </tr>
 214     <tr>
 215       <td>indent</td>
 216       <td>none</td>
 217       <td>Indent the block where the caret is located.</td>
 218     </tr>
 219     <tr>
 220       <td>inserthorizontalrule</td>
 221       <td>none</td>
 222       <td>This command will insert a horizontal rule
 223 (line) at the insertion point.<br>
 224       <br>
 225 Does it delete the selection?</td>
 226     </tr>
 227     <tr>
 228       <td>inserthtml</td>
 229       <td>valid html string</td>
 230       <td>This command will insert the given html into the &lt;body&gt;
 231 in place of the current selection or at the caret location.</td>
 232     </tr>
 233     <tr>
 234       <td>insertimage</td>
 235       <td>url (src)</td>
 236       <td>This command will insert an image (referenced by
 237 url) at the insertion point.<br>
 238       <br>
 239 Does it delete the selection?</td>
 240     </tr>
 241     <tr>
 242       <td>insertorderedlist</td>
 243       <td>none</td>
 244       <td><br></td>
 245     </tr>
 246     <tr>
 247       <td>insertunorderedlist</td>
 248       <td>none</td>
 249       <td><br></td>
 250     </tr>
 251     <tr>
 252       <td>insertparagraph</td>
 253       <td>none</td>
 254       <td><br></td>
 255     </tr>
 256     <tr>
 257       <td>italic</td>
 258       <td>none</td>
 259       <td>If there is no selection, the insertion
 260 point will set italic for subsequently typed characters. &nbsp;<br>
 261       <br>
 262 If there is a selection and all of the characters are already italic,
 263 the italic will be removed. &nbsp;Otherwise, all selected characters will
 264 become italic.</td>
 265     </tr>
 266     <tr>
 267       <td>justifycenter</td>
 268       <td>none</td>
 269       <td><br></td>
 270     </tr>
 271     <tr>
 272       <td>justifyfull</td>
 273       <td>none</td>
 274       <td><br></td>
 275     </tr>
 276     <tr>
 277       <td>justifyleft</td>
 278       <td>none</td>
 279       <td><br></td>
 280     </tr>
 281     <tr>
 282       <td>justifyright</td>
 283       <td>none</td>
 284       <td><br></td>
 285     </tr>
 286     <tr>
 287       <td>outdent</td>
 288       <td>none</td>
 289       <td>Outdent the block where the caret is located.&nbsp; If the
 290 block is not indented prior to calling outdent, nothing will happen.<br>
 291       <br>
 292 note: &nbsp;is an error thrown if no outdenting is done?</td>
 293     </tr>
 294     <tr>
 295       <td>paste</td>
 296       <td>none</td>
 297       <td>This command will paste the contents of the clipboard at the
 298 location of the caret.&nbsp; If there is a selection, it will be deleted
 299 prior to the insertion of the clipboard's contents.<br>
 300       <br>
 301 note: this command won't work without setting a pref or using signed
 302 JS.<br>
 303       <tt>user_pref("capability.policy.policynames", "allowclipboard");</tt><tt>
 304 user_pref("capability.policy.allowclipboard.Clipboard.paste",
 305 "allAccess");</tt><br>
 306 See: http://www.mozilla.org/editor/midasdemo/securityprefs.html<br>
 307       <br>
 308 note:&nbsp; the shortcut key will automatically trigger this command
 309 (typically accel-V) with or without the signed JS or any code on the page to
 310 handle it.</td>
 311     </tr>
 312     <tr>
 313       <td>redo</td>
 314       <td>none</td>
 315       <td>This command will redo the previous undo action.&nbsp; If undo
 316 was not the most recent action, this command will have no effect.<br>
 317       <br>
 318 note: &nbsp;the shortcut key will automatically trigger this command
 319 (typically accel-shift-Z)</td>
 320     </tr>
 321     <tr>
 322       <td>removeformat</td>
 323       <td>none</td>
 324       <td><br></td>
 325     </tr>
 326     <tr>
 327       <td>selectall</td>
 328       <td>none</td>
 329       <td>This command will select all of the contents within the
 330 editable area.<br>
 331       <br>
 332 note: &nbsp;the shortcut key will automatically trigger this command
 333 (typically accel-A)</td>
 334     </tr>
 335     <tr>
 336       <td>strikethrough</td>
 337       <td>none</td>
 338       <td>If there is no selection, the insertion point
 339 will set strikethrough for subsequently typed characters.<br>
 340       <br>
 341 If there is a selection and all of the characters are already striked,
 342 the strikethrough will be removed. Otherwise, all selected characters
 343 will have a line drawn through them.</td>
 344     </tr>
 345     <tr>
 346       <td>styleWithCSS</td>
 347       <td>true<br>false</td>
 348       <td>This command is used for
 349 toggling the format of generated content.&nbsp; By default (at least
 350 today), this is true.&nbsp; An example of the differences is that the
 351 "bold" command will generate &lt;b&gt; if the styleWithCSS command is false
 352 and generate css style attribute if the styleWithCSS command is true.</td>
 353     </tr>
 354     <tr>
 355       <td>subscript</td>
 356       <td>none</td>
 357       <td>If there is no selection, the insertion point
 358 will set subscript for subsequently typed characters. &nbsp;<br>
 359       <br>
 360 If there is a selection and all of the characters are already
 361 subscripted, the subscript will be removed.&nbsp; Otherwise, all
 362 selected characters will be drawn slightly lower than normal text.</td>
 363     </tr>
 364     <tr>
 365       <td>superscript</td>
 366       <td>none</td>
 367       <td>If there is no selection, the insertion point
 368 will set superscript for subsequently typed characters.<br>
 369       <br>
 370 If there is a selection and all of the characters are already
 371 superscripted, the superscript will be removed.&nbsp; Otherwise, all
 372 selected characters will be drawn slightly higher than normal text.</td>
 373     </tr>
 374     <tr>
 375       <td>underline</td>
 376       <td>none</td>
 377       <td>If there is no selection, the insertion
 378 point will set underline for subsequently typed characters.<br>
 379       <br>
 380 If there is a selection and all of the characters are already
 381 underlined, the underline will be removed.&nbsp; Otherwise, all
 382 selected characters will become underlined.</td>
 383     </tr>
 384     <tr>
 385       <td>undo</td>
 386       <td>none</td>
 387       <td>This command will undo the previous action.&nbsp; If no action
 388 has occurred in the document, then this command will have no effect.<br>
 389       <br>
 390 note: &nbsp;the shortcut key will automatically trigger this command
 391 (typically accel-Z)</td>
 392     </tr>
 393     <tr>
 394       <td>unlink</td>
 395       <td>none</td>
 396       <td><br></td>
 397     </tr>
 398   </tbody>
 399 </table>
 400 <br>
 401 <table cellpadding="4" cellspacing="0" border="1"
 402  style="text-align: left; width: 100%;">
 403   <tbody>
 404     <tr>
 405       <td colspan="3">DEPRECATED COMMANDS</td>
 406     </tr>
 407     <tr>
 408       <td>readonly</td>
 409       <td>true<br>false</td>
 410       <td>This command has been replaced with contentReadOnly.&nbsp; It
 411 takes the same values as contentReadOnly, but the meaning of true and
 412 false are inversed.</td>
 413     </tr>
 414     <tr>
 415       <td>useCSS</td>
 416       <td>truefalse</td>
 417       <td>This command has been replaced with styleWithCSS.&nbsp; It takes
 418 the same values as styleWithCSS, but the meaning of true and false are
 419 inversed.</td>
 420     </tr>
 421   </tbody>
 422 </table>
 423 </div>
 424 <br>
 425 </body>
 426 </html>