loncom/html/htmlarea/reference.html - view

File: [LON-CAPA] / loncom / html / htmlarea / Attic / reference.html
Revision 1.2: download - view: text, annotated - select for diffs
Tue Jun 1 23:46:10 2004 UTC (20 years, 1 month ago) by www
Branches: MAIN
CVS tags: version_2_5_X, version_2_5_99_0, version_2_5_2, version_2_5_1, version_2_5_0, version_2_4_X, version_2_4_99_0, version_2_4_2, version_2_4_1, version_2_4_0, version_2_3_X, version_2_3_99_0, version_2_3_2, version_2_3_1, version_2_3_0, version_2_2_X, version_2_2_99_1, version_2_2_99_0, version_2_2_2, version_2_2_1, version_2_2_0, version_2_1_X, version_2_1_99_3, version_2_1_99_2, version_2_1_99_1, version_2_1_99_0, version_2_1_3, version_2_1_2, version_2_1_1, version_2_1_0, version_2_0_X, version_2_0_99_1, version_2_0_2, version_2_0_1, version_2_0_0, version_1_99_3, version_1_99_2, version_1_99_1_tmcc, version_1_99_1, version_1_99_0_tmcc, version_1_99_0, version_1_3_X, version_1_3_3, version_1_3_2, version_1_3_1, version_1_3_0, version_1_2_X, version_1_2_99_1, version_1_2_99_0, version_1_2_1, version_1_2_0, version_1_1_99_5, version_1_1_99_4, version_1_1_99_3, version_1_1_99_2, version_1_1_99_1, version_1_1_99_0, HEAD

Next version HTMLArea.

1: <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.2//EN"> 2: <html> <head> 3: <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> 4: <title>HTMLArea-3.0 Reference</title> 5: 6: <style type="text/css"> 7: @import url(htmlarea.css); 8: body { font: 14px verdana,sans-serif; background: #fff; color: #000; } 9: h1, h2 { font-family:tahoma,sans-serif; } 10: h1 { border-bottom: 2px solid #000; } 11: h2 { border-bottom: 1px solid #aaa; } 12: h3, h4 { margin-bottom: 0px; font-family: Georgia,serif; font-style: italic; } 13: h4 { font-size: 90%; margin-left: 1em; } 14: acronym { border-bottom: 1px dotted #063; color: #063; } 15: p { margin-left: 2em; margin-top: 0.3em; } 16: li p { margin-left: 0px; } 17: .abstract { padding: 5px; margin: 0px 10em; font-size: 90%; border: 1px dashed #aaa; background: #eee;} 18: li { margin-left: 2em; } 19: em { color: #042; } 20: a { color: #00f; } 21: a:hover { color: #f00; } 22: a:active { color: #f80; } 23: span.browser { font-weight: bold; color: #864; } 24: .fixme { font-size: 20px; font-weight: bold; color: red; background: #fab; 25: padding: 5px; text-align: center; } 26: .code { 27: background: #e4efff; padding: 5px; border: 1px dashed #abc; margin-left: 2em; margin-right: 2em; 28: font-family: fixed,"lucidux mono","andale mono","courier new",monospace; 29: } 30: .note, .warning { font-weight: bold; color: #0a0; font-variant: small-caps; } 31: .warning { color: #a00; } 32: 33: .string { 34: color: #06c; 35: } /* font-lock-string-face */ 36: .comment { 37: color: #840; 38: } /* font-lock-comment-face */ 39: .variable-name { 40: color: #000; 41: } /* font-lock-variable-name-face */ 42: .type { 43: color: #008; 44: font-weight: bold; 45: } /* font-lock-type-face */ 46: .reference { 47: color: #048; 48: } /* font-lock-reference-face */ 49: .preprocessor { 50: color: #808; 51: } /* font-lock-preprocessor-face */ 52: .keyword { 53: color: #00f; 54: font-weight: bold; 55: } /* font-lock-keyword-face */ 56: .function-name { 57: color: #044; 58: } /* font-lock-function-name-face */ 59: .html-tag { 60: font-weight: bold; 61: } /* html-tag-face */ 62: .html-helper-italic { 63: font-style: italic; 64: } /* html-helper-italic-face */ 65: .html-helper-bold { 66: font-weight: bold; 67: } /* html-helper-bold-face */ 68: 69: </style> 70: 71: <script type="text/javascript"> 72: _editor_url = './'; 73: _editor_lang = 'en'; 74: </script> 75: <script type="text/javascript" src="htmlarea.js"></script> 76: <script type="text/javascript" src="dialog.js"></script> 77: <script tyle="text/javascript" src="lang/en.js"></script> 78: 79: </head> 80: 81: <body onload="HTMLArea.replace('TA')"> 82: 83: 84: <h1>HTMLArea-3.0 Documentation</h1> 85: 86: <div class="abstract" style="color: red; font-weight: bold"> 87: 88: This documentation contains valid information, but is outdated in the 89: terms that it does not covers all the features of HTMLArea. A new 90: documentation project will be started, based on LaTeX. 91: 92: </div> 93: 94: 95: <h2>Introduction</h2> 96: 97: <h3>What is HTMLArea?</h3> 98: 99: HTMLArea is a free <acronym title="What You See Is What You Get" 100: >WYSIWYG</acronym> editor replacement for <code><textarea></code> 101: fields. By adding a few simple lines of JavaScript code to your web page 102: you can replace a regular textarea with a rich text editor that lets your 103: users do the following: 104: 105: <ul> 106: <li>Format text to be bold, italicized, or underlined.</li> 107: <li>Change the face, size, style and color.</li> 108: <li>Left, center, or right-justify paragraphs.</li> 109: <li>Make bulleted or numbered lists.</li> 110: <li>Indent or un-indent paragraphs.</li> 111: <li>Insert a horizontal line.</li> 112: <li>Insert hyperlinks and images.</li> 113: <li>View the raw HTML source of what they're editing.</li> 114: <li>and much more...</li> 115: </ul> 116: 117: Some of the interesting features of HTMLArea that set's it apart from 118: other web based WYSIWYG editors are as follows: 119: 120: <ul> 121: <li>It's lightweight, fast loading and can transform a regular textarea 122: into a rich-text editor with a single line of JavaScript.</li> 123: <li>Generates clean, valid HTML.</li> 124: <li>It degrades gracefully to older or non-supported browsers 125: (they get the original textarea field).</li> 126: <li>It's free and can be incorporated into any free or commercial 127: program.</li> 128: <li>It works with any server-side languages (ASP, PHP, Perl, Java, 129: etc).</li> 130: <li>It's written in JavaScript and can be easily viewed, modified or 131: extended.</li> 132: <li>It remembers entered content when a user navigates away and then hits 133: "back" in their browser.</li> 134: <li>Since it replaces existing textareas it doesn't require a lot of code 135: to add it to your pages (just one line).</li> 136: <li>Did we mention it was free? ;-)</li> 137: </ul> 138: 139: <h3>Is it really free? What's the catch?</h3> 140: 141: Yes! It's really free. You can use it, modify it, distribute it with your 142: software, or do just about anything you like with it. 143: 144: <h3>What are the browser requirements?</h3> 145: 146: HTMLArea requires <a 147: href="http://www.microsoft.com/ie">Internet Explorer</a> >= 5.5 148: (Windows only), or <a 149: href="http://mozilla.org">Mozilla</a> >= 1.3-Beta on any platform. 150: Any browser based on <a href="http://mozilla.org/newlayout">Gecko</a> will 151: also work, provided that Gecko version is at least the one included in 152: Mozilla-1.3-Beta (for example, <a 153: href="http://galeon.sf.net">Galeon-1.2.8</a>). However, it degrades 154: gracefully to other browsers. They will get a regular textarea field 155: instead of a WYSIWYG editor. 156: 157: <h3>Can I see an example of what it looks like?</h3> 158: 159: Just make sure you're using one of the browsers mentioned above and see 160: below. 161: 162: <form onsubmit="return false;"> 163: <textarea id="TA" style="width: 100%; height: 15em;"> 164: Here is some sample text in textarea that's been transformed with HTMLArea. 166: You can make things bold, italic, underline. You can change the 167: size and colors! 168: And lots more... 169: 170: Try HTMLArea 171: today! 172: </textarea> 173: </form> 174: 175: <h3>Where can I find out more info, download the latest version and talk to 176: other HTMLArea users?</h3> 177: 178: You can find out more about HTMLArea and download the latest version on 179: the <a href="http://dynarch.com/htmlarea/">HTMLArea 180: homepage</a> and you can talk to other HTMLArea users and post any comments 181: or suggestions you have in the <a 182: href="http://www.interactivetools.com/iforum/Open_Source_C3/htmlArea_v3.0_-_Alpha_Release_F14/" 183: >HTMLArea forum</a>. 184: 185: <h2>Keyboard shortcuts</h2> 186: 187: The editor provides the following key combinations: 188: 189: <ul> 190: <li>CTRL-A -- select all</li> 191: <li>CTRL-B -- bold</li> 192: <li>CTRL-I -- italic</li> 193: <li>CTRL-U -- underline</li> 194: <li>CTRL-S -- strikethrough</li> 195: <li>CTRL-L -- justify left</li> 196: <li>CTRL-E -- justify center</li> 197: <li>CTRL-R -- justify right</li> 198: <li>CTRL-J -- justify full</li> 199: <li>CTRL-1 .. CTRL-6 -- headings (<h1> .. <h6>)</li> 200: <li>CTRL-0 (zero) -- clean content pasted from Word</li> 201: </ul> 202: 203: <h2>Installation</h2> 204: 205: <h3>How do I add HTMLArea to my web page?</h3> 206: 207: It's easy. First you need to upload HTMLArea files to your website. 208: Just follow these steps. 209: 210: <ol> 211: <li>Download the latest version from the <a 212: href="http://www.interactivetools.com/products/htmlarea/">htmlArea 213: homepage</a>.</li> 214: <li>Unzip the files onto your local computer (making sure to maintain the 215: directory structure contained in the zip).</li> 216: <li>Create a new folder on your website called /htmlarea/ (make sure it's 217: NOT inside the cgi-bin).</li> 218: <li>Transfer all the HTMLArea files from your local computer into the 219: /htmlarea/ folder on your website.</li> 220: <li>Open the example page /htmlarea/examples/core.html with your browser to make 221: sure everything works.</li> 222: </ol> 223: 224: Once htmlArea is on your website all you need to do is add some 225: JavaScript to any pages that you want to add WYSIWYG editors to. Here's how 226: to do that. 227: 228: <ol> 229: 230: <li>Define some global variables. "_editor_url" has to be the absolute 231: URL where HTMLArea resides within your 232: website; as we discussed, this would be “/htmlarea/”. "_editor_lang" must 233: be the language code in which you want HTMLArea to appear. This defaults 234: to "en" (English); for a list of supported languages, please look into 235: the "lang" subdirectory in the distribution. 236: <pre class="code" 237: ><script type="text/javascript"> 238: _editor_url = "/htmlarea/"; 239: _editor_lang = "en"; 240: </script></pre> 241: 242: <li>Include the "htmlarea.js" script: 243: <pre class="code" 244: ><script type="text/javascript" src="/htmlarea/htmlarea.js"></script></pre> 245: </li> 246: 247: <li>If you want to change all your <textarea>-s into 248: HTMLArea-s then you can use the simplest way to create HTMLArea: 249: <pre class="code" 250: ><script type="text/javascript" defer="1"> 251: HTMLArea.replaceAll(); 252: </script></pre> 253: Note: you can also add the 254: <code>HTMLArea.replaceAll()</code> code to the <code>onload</code> 255: event handler for the <code>body</code> element, if you find it more appropriate. 256: 257: A different approach, if you have more than one textarea and only want 258: to change one of them, is to use <code>HTMLArea.replace("id")</code> -- 259: pass the <code>id</code> of your textarea. Do not use the 260: <code>name</code> attribute anymore, it's not a standard solution! 261: 262: </ol> 263: 264: This section applies to HTMLArea-3.0 release candidate 1 or later; prior 265: to this version, one needed to include more files; however, now HTMLArea is 266: able to include other files too (such as stylesheet, language definition 267: file, etc.) so you only need to define the editor path and load 268: "htmlarea.js". Nice, eh? ;-) 269: 270: <h3>I want to change the editor settings, how do I do that?</h3> 271: 272: While it's true that all you need is one line of JavaScript to create an 273: htmlArea WYSIWYG editor, you can also specify more config settings in the 274: code to control how the editor works and looks. Here's an example of some of 275: the available settings: 276: 277: <pre class="code" 278: >var config = new HTMLArea.Config(); // create a new configuration object 279: // having all the default values 280: config.width = '90%'; 281: config.height = '200px'; 282: 283: // the following sets a style for the page body (black text on yellow page) 284: // and makes all paragraphs be bold by default 285: config.pageStyle = 286: 'body { background-color: yellow; color: black; font-family: verdana,sans-serif } ' + 287: 'p { font-width: bold; } '; 288: 289: // the following replaces the textarea with the given id with a new 290: // HTMLArea object having the specified configuration 291: HTMLArea.replace('id', config);</pre> 292: 293: Important: It's recommended that you add 294: custom features and configuration to a separate file. This will ensure you 295: that when we release a new official version of HTMLArea you'll have less 296: trouble upgrading it. 297: 298: <h3>How do I customize the toolbar?</h3> 299: 300: Using the configuration object introduced above allows you to completely 301: control what the toolbar contains. Following is an example of a one-line, 302: customized toolbar, much simpler than the default one: 303: 304: <pre class="code" 305: >var config = new HTMLArea.Config(); 306: config.toolbar = [ 307: ['fontname', 'space', 308: 'fontsize', 'space', 309: 'formatblock', 'space', 310: 'bold', 'italic', 'underline'] 311: ]; 312: HTMLArea.replace('id', config);</pre> 313: 314: The toolbar is an Array of Array objects. Each array in the toolbar 315: defines a new line. The default toolbar looks like this: 316: 317: <pre class="code" 318: >config.toolbar = [ 319: [ "fontname", "space", 320: "fontsize", "space", 321: "formatblock", "space", 322: "bold", "italic", "underline", "separator", 323: "strikethrough", "subscript", "superscript", "separator", 324: "copy", "cut", "paste", "space", "undo", "redo" ], 325: 326: [ "justifyleft", "justifycenter", "justifyright", "justifyfull", "separator", 327: "insertorderedlist", "insertunorderedlist", "outdent", "indent", "separator", 328: "forecolor", "hilitecolor", "textindicator", "separator", 329: "inserthorizontalrule", "createlink", "insertimage", "inserttable", "htmlmode", "separator", 330: "popupeditor", "separator", "showhelp", "about" ] 331: ];</pre> 332: 333: Except three strings, all others in the examples above need to be defined 334: in the <code>config.btnList</code> object (detailed a bit later in this 335: document). The three exceptions are: 'space', 'separator' and 'linebreak'. 336: These three have the following meaning, and need not be present in 337: <code>btnList</code>: 338: 339: <ul> 340: <li>'space' -- Inserts a space of 5 pixels (the width is configurable by external 341: <acronym title="Cascading Style Sheets">CSS</acronym>) at the current 342: position in the toolbar.</li> 343: <li>'separator' -- Inserts a small vertical separator, for visually grouping related 344: buttons.</li> 345: <li>'linebreak' -- Starts a new line in the toolbar. Subsequent controls will be 346: inserted on the new line.</li> 347: </ul> 348: 349: Important: It's recommended that you add 350: custom features and configuration to a separate file. This will ensure you 351: that when we release a new official version of HTMLArea you'll have less 352: trouble upgrading it. 353: 354: <h3>How do I create custom buttons?</h3> 355: 356: By design, the toolbar is easily extensible. For adding a custom button 357: one needs to follow two steps. 358: 359: <h4 id="regbtn">1. Register the button in <code>config.btnList</code>.</h4> 360: 361: For each button in the toolbar, HTMLArea needs to know the following 362: information: 363: <ul> 364: <li>a name for it (we call it the ID of the button);</li> 365: <li>the path to an image to be displayed in the toolbar;</li> 366: <li>a tooltip for it;</li> 367: <li>whether the button is enabled or not in text mode;</li> 368: <li>what to do when the button is clicked;</li> 369: </ul> 370: You need to provide all this information for registering a new button 371: too. The button ID can be any string identifier and it's used when 372: defining the toolbar, as you saw above. We recommend starting 373: it with "my-" so that it won't clash with the standard ID-s (those from 374: the default toolbar). 375: 376: Register button example #1 377: 378: <pre class="code" 379: >// get a default configuration 380: var config = new HTMLArea.Config(); 381: // register the new button using Config.registerButton. 382: // parameters: button ID, tooltip, image, textMode, 383: config.registerButton("my-hilite", "Highlight text", "my-hilite.gif", false, 384: // function that gets called when the button is clicked 385: function(editor, id) { 386: editor.surroundHTML('', ''); 387: } 388: );</pre> 389: 390: An alternate way of calling registerButton is exemplified above. Though 391: the code might be a little bit larger, using this form makes your code more 392: maintainable. It doesn't even needs comments as it's pretty clear. 393: 394: Register button example #2 395: 396: <pre class="code" 397: >var config = new HTMLArea.Config(); 398: config.registerButton({ 399: id : "my-hilite", 400: tooltip : "Highlight text", 401: image : "my-hilite.gif", 402: textMode : false, 403: action : function(editor, id) { 404: editor.surroundHTML('', ''); 405: } 406: });</pre> 407: 408: You might notice that the "action" function receives two parameters: 409: editor and id. In the examples above we only used the 410: editor parameter. But it could be helpful for you to understand 411: both: 412: 413: <ul> 414: <li>editor is a reference to the HTMLArea object. Since our entire 415: code now has an <acronym title="Object Oriented Programming">OOP</acronym>-like 416: design, you need to have a reference to 417: the editor object in order to do things with it. In previous versions of 418: HTMLArea, in order to identify the object an ID was used -- the ID of the 419: HTML element. In this version ID-s are no longer necessary.</li> 420: 421: <li>id is the button ID. Wondering why is this useful? Well, you 422: could use the same handler function (presuming that it's not an anonymous 423: function like in the examples above) for more buttons. You can <a 424: href="#btnex">see an example</a> a bit later in this document.</li> 425: </ul> 426: 427: <h4>2. Inserting it into the toolbar</h4> 428: 429: At this step you need to specify where in the toolbar to insert the 430: button, or just create the whole toolbar again as you saw in the previous 431: section. You use the button ID, as shown in the examples of customizing the 432: toolbar in the previous section. 433: 434: For the sake of completion, following there are another examples. 435: 436: Append your button to the default toolbar 437: 438: <pre class="code" 439: >config.toolbar.push([ "my-hilite" ]);</pre> 440: 441: Customized toolbar 442: 443: <pre class="code" 444: >config.toolbar = [ 445: ['fontname', 'space', 446: 'fontsize', 'space', 447: 'formatblock', 'space', 448: 'separator', 'my-hilite', 'separator', 'space', // here's your button 449: 'bold', 'italic', 'underline', 'space'] 450: ];</pre> 451: 452: Note: in the example above our new button is 453: between two vertical separators. But this is by no means required. You can 454: put it wherever you like. Once registered in the btnList (<a 455: href="#regbtn">step 1</a>) your custom button behaves just like a default 456: button. 457: 458: Important: It's recommended that you add 459: custom features and configuration to a separate file. This will ensure you 460: that when we release a new official version of HTMLArea you'll have less 461: trouble upgrading it. 462: 463: <h4 id="btnex">A complete example</h4> 464: 465: Please note that it is by no means necessary to include the following 466: code into the htmlarea.js file. On the contrary, it might not work there. 467: The configuration system is designed such that you can always customize the 468: editor from outside files, thus keeping the htmlarea.js file 469: intact. This will make it easy for you to upgrade your HTMLArea when we 470: release a new official version. OK, I promise it's the last time I said 471: this. ;) 472: 473: <pre class="code" 474: >// All our custom buttons will call this function when clicked. 475: // We use the buttonId parameter to determine what button 476: // triggered the call. 477: function clickHandler(editor, buttonId) { 478: switch (buttonId) { 479: case "my-toc": 480: editor.insertHTML("<h1>Table Of Contents</h1>"); 481: break; 482: case "my-date": 483: editor.insertHTML((new Date()).toString()); 484: break; 485: case "my-bold": 486: editor.execCommand("bold"); 487: editor.execCommand("italic"); 488: break; 489: case "my-hilite": 490: editor.surroundHTML("", ""); 491: break; 492: } 493: }; 494: 495: // Create a new configuration object 496: var config = new HTMLArea.Config(); 497: 498: // Register our custom buttons 499: config.registerButton("my-toc", "Insert TOC", "my-toc.gif", false, clickHandler); 500: config.registerButton("my-date", "Insert date/time", "my-date.gif", false, clickHandler); 501: config.registerButton("my-bold", "Toggle bold/italic", "my-bold.gif", false, clickHandler); 502: config.registerButton("my-hilite", "Hilite selection", "my-hilite.gif", false, clickHandler); 503: 504: // Append the buttons to the default toolbar 505: config.toolbar.push(["linebreak", "my-toc", "my-date", "my-bold", "my-hilite"]); 506: 507: // Replace an existing textarea with an HTMLArea object having the above config. 508: HTMLArea.replace("textAreaID", config);</pre> 509: 510: 511: <hr /> 512: <address>© <a href="http://interactivetools.com" title="Visit our website" 513: >InteractiveTools.com</a> 2002-2004. 514: 515: © <a href="http://dynarch.com">dynarch.com</a> 2003-2004 516: HTMLArea v3.0 developed by <a 517: href="http://dynarch.com/mishoo/">Mihai Bazon</a>. 518: 519: Documentation written by Mihai Bazon. 520: </address> 521:  Last modified: Wed Jan 28 12:18:23 EET 2004  522:  523: </body> </html>