[2] | 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> |
---|