| 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 | <p>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:</p> |
|---|
| 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 | <p>Some of the interesting features of HTMLArea that set's it apart from |
|---|
| 118 | other web based WYSIWYG editors are as follows:</p> |
|---|
| 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 | <p>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.</p> |
|---|
| 143 | |
|---|
| 144 | <h3>What are the browser requirements?</h3> |
|---|
| 145 | |
|---|
| 146 | <p>HTMLArea requires <span class="browser"><a |
|---|
| 147 | href="http://www.microsoft.com/ie">Internet Explorer</a> >= 5.5</span> |
|---|
| 148 | (Windows only), or <span class="browser"><a |
|---|
| 149 | href="http://mozilla.org">Mozilla</a> >= 1.3-Beta</span> 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.</p> |
|---|
| 156 | |
|---|
| 157 | <h3>Can I see an example of what it looks like?</h3> |
|---|
| 158 | |
|---|
| 159 | <p>Just make sure you're using one of the browsers mentioned above and see |
|---|
| 160 | below.</p> |
|---|
| 161 | |
|---|
| 162 | <form onsubmit="return false;"> |
|---|
| 163 | <textarea id="TA" style="width: 100%; height: 15em;"> |
|---|
| 164 | <p>Here is some sample text in textarea that's been transformed with <font |
|---|
| 165 | color="#0000CC"><b>HTMLArea</b></font>.<br /> |
|---|
| 166 | You can make things <b>bold</b>, <i>italic</i>, <u>underline</u>. You can change the |
|---|
| 167 | <font size="3">size</font> and <b><font color="#0000CC">c</font><font color="#00CC00">o</font><font color="#00CCCC">l</font><font color="#CC0000">o</font><font color="#CC00CC">r</font><font color="#CCCC00">s</font><font color="#CCCCCC">!</font></b> |
|---|
| 168 | And lots more...</p> |
|---|
| 169 | |
|---|
| 170 | <p align="center"><font size="4" color="#ff0000"><b><u>Try HTMLArea |
|---|
| 171 | today!</u></b></font><br /></p> |
|---|
| 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 | <p>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>.</p> |
|---|
| 184 | |
|---|
| 185 | <h2>Keyboard shortcuts</h2> |
|---|
| 186 | |
|---|
| 187 | <p>The editor provides the following key combinations:</p> |
|---|
| 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 | <p>It's easy. First you need to upload HTMLArea files to your website. |
|---|
| 208 | Just follow these steps.</p> |
|---|
| 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 | <p>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.</p> |
|---|
| 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 | ><span class="function-name"><</span><span class="html-tag">script</span> <span class="variable-name">type=</span><span class="string">"text/javascript"</span><span class="function-name">></span> |
|---|
| 238 | _editor_url = <span class="string">"/htmlarea/"</span>; |
|---|
| 239 | _editor_lang = <span class="string">"en"</span>; |
|---|
| 240 | <span class="function-name"><</span><span class="html-tag">/script</span><span class="function-name">></span></pre> |
|---|
| 241 | |
|---|
| 242 | <li>Include the "htmlarea.js" script: |
|---|
| 243 | <pre class="code" |
|---|
| 244 | ><span class="function-name"><</span><span class="html-tag">script</span> <span class="variable-name">type=</span><span class="string">"text/javascript"</span> <span class="variable-name">src=</span><span class="string">"/htmlarea/htmlarea.js"</span><span class="function-name">></span><span class="paren-face-match"><</span><span class="html-tag">/script</span><span class="paren-face-match">></span></pre> |
|---|
| 245 | </li> |
|---|
| 246 | |
|---|
| 247 | <li><p>If you want to change all your <textarea>-s into |
|---|
| 248 | HTMLArea-s then you can use the simplest way to create HTMLArea:</p> |
|---|
| 249 | <pre class="code" |
|---|
| 250 | ><span class="function-name"><</span><span class="html-tag">script</span> <span class="variable-name">type=</span><span class="string">"text/javascript"</span> <span class="variable-name">defer=</span><span class="string">"1"</span><span class="function-name">></span> |
|---|
| 251 | HTMLArea.replaceAll<span class="function-name">()</span>; |
|---|
| 252 | <span class="paren-face-match"><</span><span class="html-tag">/script</span><span class="paren-face-match">></span></pre> |
|---|
| 253 | <p><span class="note">Note:</span> 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.</p> |
|---|
| 256 | |
|---|
| 257 | <p>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!</p> |
|---|
| 261 | |
|---|
| 262 | </ol> |
|---|
| 263 | |
|---|
| 264 | <p>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? ;-)</p> |
|---|
| 269 | |
|---|
| 270 | <h3>I want to change the editor settings, how do I do that?</h3> |
|---|
| 271 | |
|---|
| 272 | <p>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:</p> |
|---|
| 276 | |
|---|
| 277 | <pre class="code" |
|---|
| 278 | ><span class="keyword">var</span> <span class="variable-name">config</span> = <span class="keyword">new</span> HTMLArea.Config(); <span class="comment">// create a new configuration object |
|---|
| 279 | </span> <span class="comment">// having all the default values |
|---|
| 280 | </span>config.width = '<span class="string">90%</span>'; |
|---|
| 281 | config.height = '<span class="string">200px</span>'; |
|---|
| 282 | |
|---|
| 283 | <span class="comment">// the following sets a style for the page body (black text on yellow page) |
|---|
| 284 | // and makes all paragraphs be bold by default |
|---|
| 285 | </span>config.pageStyle = |
|---|
| 286 | '<span class="string">body { background-color: yellow; color: black; font-family: verdana,sans-serif } </span>' + |
|---|
| 287 | '<span class="string">p { font-width: bold; } </span>'; |
|---|
| 288 | |
|---|
| 289 | <span class="comment">// the following replaces the textarea with the given id with a new |
|---|
| 290 | // HTMLArea object having the specified configuration |
|---|
| 291 | </span>HTMLArea.replace('<span class="string">id</span>', config);</pre> |
|---|
| 292 | |
|---|
| 293 | <p><span class="warning">Important:</span> 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.</p> |
|---|
| 297 | |
|---|
| 298 | <h3>How do I customize the toolbar?</h3> |
|---|
| 299 | |
|---|
| 300 | <p>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:</p> |
|---|
| 303 | |
|---|
| 304 | <pre class="code" |
|---|
| 305 | ><span class="keyword">var</span> <span class="variable-name">config</span> = <span class="keyword">new</span> HTMLArea.Config(); |
|---|
| 306 | config.toolbar = [ |
|---|
| 307 | ['<span class="string">fontname</span>', '<span class="string">space</span>', |
|---|
| 308 | '<span class="string">fontsize</span>', '<span class="string">space</span>', |
|---|
| 309 | '<span class="string">formatblock</span>', '<span class="string">space</span>', |
|---|
| 310 | '<span class="string">bold</span>', '<span class="string">italic</span>', '<span class="string">underline</span>'] |
|---|
| 311 | ]; |
|---|
| 312 | HTMLArea.replace('<span class="string">id</span>', config);</pre> |
|---|
| 313 | |
|---|
| 314 | <p>The toolbar is an Array of Array objects. Each array in the toolbar |
|---|
| 315 | defines a new line. The default toolbar looks like this:</p> |
|---|
| 316 | |
|---|
| 317 | <pre class="code" |
|---|
| 318 | >config.toolbar = [ |
|---|
| 319 | [ "<span class="string">fontname</span>", "<span class="string">space</span>", |
|---|
| 320 | "<span class="string">fontsize</span>", "<span class="string">space</span>", |
|---|
| 321 | "<span class="string">formatblock</span>", "<span class="string">space</span>", |
|---|
| 322 | "<span class="string">bold</span>", "<span class="string">italic</span>", "<span class="string">underline</span>", "<span class="string">separator</span>", |
|---|
| 323 | "<span class="string">strikethrough</span>", "<span class="string">subscript</span>", "<span class="string">superscript</span>", "<span class="string">separator</span>", |
|---|
| 324 | "<span class="string">copy</span>", "<span class="string">cut</span>", "<span class="string">paste</span>", "<span class="string">space</span>", "<span class="string">undo</span>", "<span class="string">redo</span>" ], |
|---|
| 325 | |
|---|
| 326 | [ "<span class="string">justifyleft</span>", "<span class="string">justifycenter</span>", "<span class="string">justifyright</span>", "<span class="string">justifyfull</span>", "<span class="string">separator</span>", |
|---|
| 327 | "<span class="string">insertorderedlist</span>", "<span class="string">insertunorderedlist</span>", "<span class="string">outdent</span>", "<span class="string">indent</span>", "<span class="string">separator</span>", |
|---|
| 328 | "<span class="string">forecolor</span>", "<span class="string">hilitecolor</span>", "<span class="string">textindicator</span>", "<span class="string">separator</span>", |
|---|
| 329 | "<span class="string">inserthorizontalrule</span>", "<span class="string">createlink</span>", "<span class="string">insertimage</span>", "<span class="string">inserttable</span>", "<span class="string">htmlmode</span>", "<span class="string">separator</span>", |
|---|
| 330 | "<span class="string">popupeditor</span>", "<span class="string">separator</span>", "<span class="string">showhelp</span>", "<span class="string">about</span>" ] |
|---|
| 331 | ];</pre> |
|---|
| 332 | |
|---|
| 333 | <p>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>:</p> |
|---|
| 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 | <p><span class="warning">Important:</span> 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.</p> |
|---|
| 353 | |
|---|
| 354 | <h3>How do I create custom buttons?</h3> |
|---|
| 355 | |
|---|
| 356 | <p>By design, the toolbar is easily extensible. For adding a custom button |
|---|
| 357 | one needs to follow two steps.</p> |
|---|
| 358 | |
|---|
| 359 | <h4 id="regbtn">1. Register the button in <code>config.btnList</code>.</h4> |
|---|
| 360 | |
|---|
| 361 | <p>For each button in the toolbar, HTMLArea needs to know the following |
|---|
| 362 | information:</p> |
|---|
| 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 | <p>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).</p> |
|---|
| 375 | |
|---|
| 376 | <p class="note">Register button example #1</p> |
|---|
| 377 | |
|---|
| 378 | <pre class="code" |
|---|
| 379 | ><span class="comment">// get a default configuration |
|---|
| 380 | </span><span class="keyword">var</span> <span class="variable-name">config</span> = <span class="keyword">new</span> HTMLArea.Config(); |
|---|
| 381 | <span class="comment">// register the new button using Config.registerButton. |
|---|
| 382 | // parameters: button ID, tooltip, image, textMode, |
|---|
| 383 | </span>config.registerButton("<span class="string">my-hilite</span>", "<span class="string">Highlight text</span>", "<span class="string">my-hilite.gif</span>", <span class="keyword">false</span>, |
|---|
| 384 | <span class="comment">// function that gets called when the button is clicked |
|---|
| 385 | </span> <span class="keyword">function</span>(editor, id) { |
|---|
| 386 | editor.surroundHTML('<span class="string"><span class="hilite"></span>', '<span class="string"></span></span>'); |
|---|
| 387 | } |
|---|
| 388 | );</pre> |
|---|
| 389 | |
|---|
| 390 | <p>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.</p> |
|---|
| 393 | |
|---|
| 394 | <p class="note">Register button example #2</p> |
|---|
| 395 | |
|---|
| 396 | <pre class="code" |
|---|
| 397 | ><span class="keyword">var</span> <span class="variable-name">config</span> = <span class="keyword">new</span> HTMLArea.Config(); |
|---|
| 398 | config.registerButton({ |
|---|
| 399 | id : "<span class="string">my-hilite</span>", |
|---|
| 400 | tooltip : "<span class="string">Highlight text</span>", |
|---|
| 401 | image : "<span class="string">my-hilite.gif</span>", |
|---|
| 402 | textMode : <span class="keyword">false</span>, |
|---|
| 403 | action : <span class="keyword">function</span>(editor, id) { |
|---|
| 404 | editor.surroundHTML('<span class="string"><span class="hilite"></span>', '<span class="string"></span></span>'); |
|---|
| 405 | } |
|---|
| 406 | });</pre> |
|---|
| 407 | |
|---|
| 408 | <p>You might notice that the "action" function receives two parameters: |
|---|
| 409 | <b>editor</b> and <b>id</b>. In the examples above we only used the |
|---|
| 410 | <b>editor</b> parameter. But it could be helpful for you to understand |
|---|
| 411 | both:</p> |
|---|
| 412 | |
|---|
| 413 | <ul> |
|---|
| 414 | <li><b>editor</b> 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><b>id</b> 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 | <p>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.</p> |
|---|
| 433 | |
|---|
| 434 | <p>For the sake of completion, following there are another examples.</p> |
|---|
| 435 | |
|---|
| 436 | <p class="note">Append your button to the default toolbar</p> |
|---|
| 437 | |
|---|
| 438 | <pre class="code" |
|---|
| 439 | >config.toolbar.push([ "<span class="string">my-hilite</span>" ]);</pre> |
|---|
| 440 | |
|---|
| 441 | <p class="note">Customized toolbar</p> |
|---|
| 442 | |
|---|
| 443 | <pre class="code" |
|---|
| 444 | >config.toolbar = [ |
|---|
| 445 | ['<span class="string">fontname</span>', '<span class="string">space</span>', |
|---|
| 446 | '<span class="string">fontsize</span>', '<span class="string">space</span>', |
|---|
| 447 | '<span class="string">formatblock</span>', '<span class="string">space</span>', |
|---|
| 448 | '<span class="string">separator</span>', '<span class="string">my-hilite</span>', '<span class="string">separator</span>', '<span class="string">space</span>', <span class="comment">// here's your button |
|---|
| 449 | </span> '<span class="string">bold</span>', '<span class="string">italic</span>', '<span class="string">underline</span>', '<span class="string">space</span>'] |
|---|
| 450 | ];</pre> |
|---|
| 451 | |
|---|
| 452 | <p><span class="note">Note:</span> 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.</p> |
|---|
| 457 | |
|---|
| 458 | <p><span class="warning">Important:</span> 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.</p> |
|---|
| 462 | |
|---|
| 463 | <h4 id="btnex">A complete example</h4> |
|---|
| 464 | |
|---|
| 465 | <p>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 <em>from outside files</em>, 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. ;)</p> |
|---|
| 472 | |
|---|
| 473 | <pre class="code" |
|---|
| 474 | ><span class="comment">// All our custom buttons will call this function when clicked. |
|---|
| 475 | // We use the <b>buttonId</b> parameter to determine what button |
|---|
| 476 | // triggered the call. |
|---|
| 477 | </span><span class="keyword">function</span> <span class="function-name">clickHandler</span>(editor, buttonId) { |
|---|
| 478 | <span class="keyword">switch</span> (buttonId) { |
|---|
| 479 | <span class="keyword">case</span> "<span class="string">my-toc</span>": |
|---|
| 480 | editor.insertHTML("<span class="string"><h1>Table Of Contents</h1></span>"); |
|---|
| 481 | <span class="keyword">break</span>; |
|---|
| 482 | <span class="keyword">case</span> "<span class="string">my-date</span>": |
|---|
| 483 | editor.insertHTML((<span class="keyword">new</span> Date()).toString()); |
|---|
| 484 | <span class="keyword">break</span>; |
|---|
| 485 | <span class="keyword">case</span> "<span class="string">my-bold</span>": |
|---|
| 486 | editor.execCommand("<span class="string">bold</span>"); |
|---|
| 487 | editor.execCommand("<span class="string">italic</span>"); |
|---|
| 488 | <span class="keyword">break</span>; |
|---|
| 489 | <span class="keyword">case</span> "<span class="string">my-hilite</span>": |
|---|
| 490 | editor.surroundHTML("<span class="string"><span class=\"hilite\"></span>", "<span class="string"></span></span>"); |
|---|
| 491 | <span class="keyword">break</span>; |
|---|
| 492 | } |
|---|
| 493 | }; |
|---|
| 494 | |
|---|
| 495 | <span class="comment">// Create a new configuration object |
|---|
| 496 | </span><span class="keyword">var</span> <span class="variable-name">config</span> = <span class="keyword">new</span> HTMLArea.Config(); |
|---|
| 497 | |
|---|
| 498 | <span class="comment">// Register our custom buttons |
|---|
| 499 | </span>config.registerButton("<span class="string">my-toc</span>", "<span class="string">Insert TOC</span>", "<span class="string">my-toc.gif</span>", <span class="keyword">false</span>, clickHandler); |
|---|
| 500 | config.registerButton("<span class="string">my-date</span>", "<span class="string">Insert date/time</span>", "<span class="string">my-date.gif</span>", <span class="keyword">false</span>, clickHandler); |
|---|
| 501 | config.registerButton("<span class="string">my-bold</span>", "<span class="string">Toggle bold/italic</span>", "<span class="string">my-bold.gif</span>", <span class="keyword">false</span>, clickHandler); |
|---|
| 502 | config.registerButton("<span class="string">my-hilite</span>", "<span class="string">Hilite selection</span>", "<span class="string">my-hilite.gif</span>", <span class="keyword">false</span>, clickHandler); |
|---|
| 503 | |
|---|
| 504 | <span class="comment">// Append the buttons to the default toolbar |
|---|
| 505 | </span>config.toolbar.push(["<span class="string">linebreak</span>", "<span class="string">my-toc</span>", "<span class="string">my-date</span>", "<span class="string">my-bold</span>", "<span class="string">my-hilite</span>"]); |
|---|
| 506 | |
|---|
| 507 | <span class="comment">// Replace an existing textarea with an HTMLArea object having the above config. |
|---|
| 508 | </span>HTMLArea.replace("<span class="string">textAreaID</span>", config);</pre> |
|---|
| 509 | |
|---|
| 510 | |
|---|
| 511 | <hr /> |
|---|
| 512 | <address>© <a href="http://interactivetools.com" title="Visit our website" |
|---|
| 513 | >InteractiveTools.com</a> 2002-2004. |
|---|
| 514 | <br /> |
|---|
| 515 | © <a href="http://dynarch.com">dynarch.com</a> 2003-2004<br /> |
|---|
| 516 | HTMLArea v3.0 developed by <a |
|---|
| 517 | href="http://dynarch.com/mishoo/">Mihai Bazon</a>. |
|---|
| 518 | <br /> |
|---|
| 519 | Documentation written by Mihai Bazon. |
|---|
| 520 | </address> |
|---|
| 521 | <!-- hhmts start --> Last modified: Wed Jan 28 12:18:23 EET 2004 <!-- hhmts end --> |
|---|
| 522 | <!-- doc-lang: English --> |
|---|
| 523 | </body> </html> |
|---|