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> |
---|