loncom/html/htmlarea/reference.html - view

File: [LON-CAPA] / loncom / html / htmlarea / Attic / reference.html
Revision 1.1: download - view: text, annotated - select for diffs
Wed Feb 18 08:07:15 2004 UTC (20 years, 5 months ago) by www
Branches: MAIN
CVS tags: HEAD

Install HTMLArea

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