| 1 |
4
|
ryan
|
<!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>
|