Annotation of loncom/html/htmlarea/reference.html, revision 1.2

1.1       www         1: <!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.2//EN">
                      2: <html> <head>
1.2     ! www         3: <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
1.1       www         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: 
1.2     ! www        71: <script type="text/javascript">
        !            72:   _editor_url = './';
        !            73:   _editor_lang = 'en';
        !            74: </script>
1.1       www        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>&lt;textarea&gt;</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>
1.2     ! www       124:   <li>It degrades gracefully to older or non-supported browsers
1.1       www       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> &gt;= 5.5</span>
                    148: (Windows only), or <span class="browser"><a
                    149: href="http://mozilla.org">Mozilla</a> &gt;= 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
1.2     ! www       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
1.1       www       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
1.2     ! www       179: the <a href="http://dynarch.com/htmlarea/">HTMLArea
1.1       www       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 (&lt;h1&gt; .. &lt;h6&gt;)</li>
1.2     ! www       200:   <li>CTRL-0 (zero) -- clean content pasted from Word</li>
1.1       www       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>
1.2     ! www       220:   <li>Open the example page /htmlarea/examples/core.html with your browser to make
1.1       www       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: 
1.2     ! www       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">&lt;</span><span class="html-tag">script</span> <span class="variable-name">type=</span><span class="string">&quot;text/javascript&quot;</span><span class="function-name">&gt;</span>
        !           238:    _editor_url = <span class="string">&quot;/htmlarea/&quot;</span>;
        !           239:    _editor_lang = <span class="string">&quot;en&quot;</span>;
        !           240: <span class="function-name">&lt;</span><span class="html-tag">/script</span><span class="function-name">&gt;</span></pre>
        !           241: 
1.1       www       242:   <li>Include the "htmlarea.js" script:
                    243:   <pre class="code"
                    244:   ><span class="function-name">&lt;</span><span class="html-tag">script</span> <span class="variable-name">type=</span><span class="string">&quot;text/javascript&quot;</span> <span class="variable-name">src=</span><span class="string">&quot;/htmlarea/htmlarea.js&quot;</span><span class="function-name">&gt;</span><span class="paren-face-match">&lt;</span><span class="html-tag">/script</span><span class="paren-face-match">&gt;</span></pre>
                    245:   </li>
                    246: 
                    247:   <li><p>If you want to change all your &lt;textarea&gt;-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">&lt;</span><span class="html-tag">script</span> <span class="variable-name">type=</span><span class="string">&quot;text/javascript&quot;</span> <span class="variable-name">defer=</span><span class="string">&quot;1&quot;</span><span class="function-name">&gt;</span>
                    251:     HTMLArea.replaceAll<span class="function-name">()</span>;
                    252: <span class="paren-face-match">&lt;</span><span class="html-tag">/script</span><span class="paren-face-match">&gt;</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: 
1.2     ! www       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: 
1.1       www       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
1.2     ! www       295: that when we release a new official version of HTMLArea you'll have less
1.1       www       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: [ &quot;<span class="string">fontname</span>&quot;, &quot;<span class="string">space</span>&quot;,
                    320:   &quot;<span class="string">fontsize</span>&quot;, &quot;<span class="string">space</span>&quot;,
                    321:   &quot;<span class="string">formatblock</span>&quot;, &quot;<span class="string">space</span>&quot;,
                    322:   &quot;<span class="string">bold</span>&quot;, &quot;<span class="string">italic</span>&quot;, &quot;<span class="string">underline</span>&quot;, &quot;<span class="string">separator</span>&quot;,
                    323:   &quot;<span class="string">strikethrough</span>&quot;, &quot;<span class="string">subscript</span>&quot;, &quot;<span class="string">superscript</span>&quot;, &quot;<span class="string">separator</span>&quot;,
                    324:   &quot;<span class="string">copy</span>&quot;, &quot;<span class="string">cut</span>&quot;, &quot;<span class="string">paste</span>&quot;, &quot;<span class="string">space</span>&quot;, &quot;<span class="string">undo</span>&quot;, &quot;<span class="string">redo</span>&quot; ],
                    325: 		
                    326: [ &quot;<span class="string">justifyleft</span>&quot;, &quot;<span class="string">justifycenter</span>&quot;, &quot;<span class="string">justifyright</span>&quot;, &quot;<span class="string">justifyfull</span>&quot;, &quot;<span class="string">separator</span>&quot;,
                    327:   &quot;<span class="string">insertorderedlist</span>&quot;, &quot;<span class="string">insertunorderedlist</span>&quot;, &quot;<span class="string">outdent</span>&quot;, &quot;<span class="string">indent</span>&quot;, &quot;<span class="string">separator</span>&quot;,
                    328:   &quot;<span class="string">forecolor</span>&quot;, &quot;<span class="string">hilitecolor</span>&quot;, &quot;<span class="string">textindicator</span>&quot;, &quot;<span class="string">separator</span>&quot;,
                    329:   &quot;<span class="string">inserthorizontalrule</span>&quot;, &quot;<span class="string">createlink</span>&quot;, &quot;<span class="string">insertimage</span>&quot;, &quot;<span class="string">inserttable</span>&quot;, &quot;<span class="string">htmlmode</span>&quot;, &quot;<span class="string">separator</span>&quot;,
                    330:   &quot;<span class="string">popupeditor</span>&quot;, &quot;<span class="string">separator</span>&quot;, &quot;<span class="string">showhelp</span>&quot;, &quot;<span class="string">about</span>&quot; ]
                    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
1.2     ! www       351: that when we release a new official version of HTMLArea you'll have less
1.1       www       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(&quot;<span class="string">my-hilite</span>&quot;, &quot;<span class="string">Highlight text</span>&quot;, &quot;<span class="string">my-hilite.gif</span>&quot;, <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">&lt;span class=&quot;hilite&quot;&gt;</span>', '<span class="string">&lt;/span&gt;</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        : &quot;<span class="string">my-hilite</span>&quot;,
                    400:   tooltip   : &quot;<span class="string">Highlight text</span>&quot;,
                    401:   image     : &quot;<span class="string">my-hilite.gif</span>&quot;,
                    402:   textMode  : <span class="keyword">false</span>,
                    403:   action    : <span class="keyword">function</span>(editor, id) {
                    404:                 editor.surroundHTML('<span class="string">&lt;span class=&quot;hilite&quot;&gt;</span>', '<span class="string">&lt;/span&gt;</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([ &quot;<span class="string">my-hilite</span>&quot; ]);</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
1.2     ! www       460: that when we release a new official version of HTMLArea you'll have less
1.1       www       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> &quot;<span class="string">my-toc</span>&quot;:
                    480:       editor.insertHTML(&quot;<span class="string">&lt;h1&gt;Table Of Contents&lt;/h1&gt;</span>&quot;);
                    481:       <span class="keyword">break</span>;
                    482:     <span class="keyword">case</span> &quot;<span class="string">my-date</span>&quot;:
                    483:       editor.insertHTML((<span class="keyword">new</span> Date()).toString());
                    484:       <span class="keyword">break</span>;
                    485:     <span class="keyword">case</span> &quot;<span class="string">my-bold</span>&quot;:
                    486:       editor.execCommand(&quot;<span class="string">bold</span>&quot;);
                    487:       editor.execCommand(&quot;<span class="string">italic</span>&quot;);
                    488:       <span class="keyword">break</span>;
                    489:     <span class="keyword">case</span> &quot;<span class="string">my-hilite</span>&quot;:
                    490:       editor.surroundHTML(&quot;<span class="string">&lt;span class=\&quot;hilite\&quot;&gt;</span>&quot;, &quot;<span class="string">&lt;/span&gt;</span>&quot;);
                    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(&quot;<span class="string">my-toc</span>&quot;,  &quot;<span class="string">Insert TOC</span>&quot;, &quot;<span class="string">my-toc.gif</span>&quot;, <span class="keyword">false</span>, clickHandler);
                    500: config.registerButton(&quot;<span class="string">my-date</span>&quot;, &quot;<span class="string">Insert date/time</span>&quot;, &quot;<span class="string">my-date.gif</span>&quot;, <span class="keyword">false</span>, clickHandler);
                    501: config.registerButton(&quot;<span class="string">my-bold</span>&quot;, &quot;<span class="string">Toggle bold/italic</span>&quot;, &quot;<span class="string">my-bold.gif</span>&quot;, <span class="keyword">false</span>, clickHandler);
                    502: config.registerButton(&quot;<span class="string">my-hilite</span>&quot;, &quot;<span class="string">Hilite selection</span>&quot;, &quot;<span class="string">my-hilite.gif</span>&quot;, <span class="keyword">false</span>, clickHandler);
                    503: 
                    504: <span class="comment">// Append the buttons to the default toolbar
                    505: </span>config.toolbar.push([&quot;<span class="string">linebreak</span>&quot;, &quot;<span class="string">my-toc</span>&quot;, &quot;<span class="string">my-date</span>&quot;, &quot;<span class="string">my-bold</span>&quot;, &quot;<span class="string">my-hilite</span>&quot;]);
                    506: 
                    507: <span class="comment">// Replace an existing textarea with an HTMLArea object having the above config.
                    508: </span>HTMLArea.replace(&quot;<span class="string">textAreaID</span>&quot;, config);</pre>
                    509: 
                    510: 
                    511: <hr />
                    512: <address>&copy; <a href="http://interactivetools.com" title="Visit our website"
1.2     ! www       513: >InteractiveTools.com</a> 2002-2004.
1.1       www       514: <br />
1.2     ! www       515: © <a href="http://dynarch.com">dynarch.com</a> 2003-2004<br />
1.1       www       516: HTMLArea v3.0 developed by <a
1.2     ! www       517: href="http://dynarch.com/mishoo/">Mihai Bazon</a>.
1.1       www       518: <br />
                    519: Documentation written by Mihai Bazon.
                    520: </address>
1.2     ! www       521: <!-- hhmts start --> Last modified: Wed Jan 28 12:18:23 EET 2004 <!-- hhmts end -->
1.1       www       522: <!-- doc-lang: English -->
                    523: </body> </html>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>