Index: openacs-4/packages/acs-templating/www/resources/htmlarea/reference.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-templating/www/resources/htmlarea/reference.html,v diff -u -r1.1 -r1.2 --- openacs-4/packages/acs-templating/www/resources/htmlarea/reference.html 4 Mar 2004 18:32:10 -0000 1.1 +++ openacs-4/packages/acs-templating/www/resources/htmlarea/reference.html 30 Jan 2005 16:13:26 -0000 1.2 @@ -1,522 +1,523 @@ - - -HTMLArea-3.0 Reference - - - - - - - - - - - - -

HTMLArea-3.0 Documentation

- -
- - This documentation contains valid information, but is outdated in the - terms that it does not covers all the features of HTMLArea. A new - documentation project will be started, based on LaTeX. - -
- - -

Introduction

- -

What is HTMLArea?

- -

HTMLArea is a free WYSIWYG editor replacement for <textarea> -fields. By adding a few simple lines of JavaScript code to your web page -you can replace a regular textarea with a rich text editor that lets your -users do the following:

- - - -

Some of the interesting features of HTMLArea that set's it apart from -other web based WYSIWYG editors are as follows:

- - - -

Is it really free? What's the catch?

- -

Yes! It's really free. You can use it, modify it, distribute it with your -software, or do just about anything you like with it.

- -

What are the browser requirements?

- -

HTMLArea requires Internet Explorer >= 5.5 -(Windows only), or Mozilla >= 1.3-Beta on any platform. -Any browser based on Gecko will -also work, provided that Gecko version is at least the one included in -Mozilla-1.3-Beta (for example, Galeon-1.2.8). However, it is backwards -compatible with other browsers. They will get a regular textarea field -instead of a WYSIWYG editor.

- -

Can I see an example of what it looks like?

- -

Just make sure you're using one of the browsers mentioned above and see -below.

- -
- -
- -

Where can I find out more info, download the latest version and talk to -other HTMLArea users?

- -

You can find out more about HTMLArea and download the latest version on -the HTMLArea -homepage and you can talk to other HTMLArea users and post any comments -or suggestions you have in the HTMLArea forum.

- -

Keyboard shortcuts

- -

The editor provides the following key combinations:

- - - -

Installation

- -

How do I add HTMLArea to my web page?

- -

It's easy. First you need to upload HTMLArea files to your website. -Just follow these steps.

- -
    -
  1. Download the latest version from the htmlArea - homepage.
  2. -
  3. Unzip the files onto your local computer (making sure to maintain the - directory structure contained in the zip).
  4. -
  5. Create a new folder on your website called /htmlarea/ (make sure it's - NOT inside the cgi-bin).
  6. -
  7. Transfer all the HTMLArea files from your local computer into the - /htmlarea/ folder on your website.
  8. -
  9. Open the example page /htmlarea/example.html with your browser to make - sure everything works.
  10. -
- -

Once htmlArea is on your website all you need to do is add some -JavaScript to any pages that you want to add WYSIWYG editors to. Here's how -to do that.

- -
    - -
  1. Include the "htmlarea.js" script: -
    <script type="text/javascript" src="/htmlarea/htmlarea.js"></script>
    -
  2. - -
  3. If you are using popup dialogs, i.e. for insert table, insert image, - select color, then you need to include the "dialog.js" file. This is - recommended anyway. -
    <script type="text/javascript" src="/htmlarea/dialog.js"></script>
    -
  4. - -
  5. Include the corresponding language definition file. Note: - internationalization is available only since version 3.0. Check the files - containing "lang" in the distribution ZIP. If your preferred language is - not there yet and you decide to write it, please consider sending it to - us so that it gets included in the next release. -
    <script type="text/javascript" src="/htmlarea/lang/en.js"></script>
    - -
  6. Include the stylesheet (be sure to put this inside the HEAD tag): -
    <style type="text/css">@import url(/htmlarea/htmlarea.css)</style>
    -
  7. - -
  8. If you want to change all your <textarea>-s into - HTMLArea-s then you can use the simplest way to create HTMLArea:

    -
    <script type="text/javascript" defer="1">
    -    HTMLArea.replaceAll();
    -</script>
    -

    Note: you can also add the - HTMLArea.replaceAll() code to the onload - event handler for the body element, if you find it more appropriate.

    - -

    A different approach, if you have more than one textarea and only want - to change one of them, is to use HTMLArea.replace("id") -- - pass the id of your textarea. Do not use the - name attribute anymore, it's not a standard solution!

    - -
- -

I want to change the editor settings, how do I do that?

- -

While it's true that all you need is one line of JavaScript to create an -htmlArea WYSIWYG editor, you can also specify more config settings in the -code to control how the editor works and looks. Here's an example of some of -the available settings:

- -
var config = new HTMLArea.Config(); // create a new configuration object
-                                    // having all the default values
-config.width = '90%';
-config.height = '200px';
-
-// the following sets a style for the page body (black text on yellow page)
-// and makes all paragraphs be bold by default
-config.pageStyle =
-  'body { background-color: yellow; color: black; font-family: verdana,sans-serif } ' +
-  'p { font-width: bold; } ';
-
-// the following replaces the textarea with the given id with a new
-// HTMLArea object having the specified configuration
-HTMLArea.replace('id', config);
- -

Important: It's recommended that you add -custom features and configuration to a separate file. This will ensure you -that when we release a new official version of HTMLArea you'll have no -trouble upgrading it.

- -

How do I customize the toolbar?

- -

Using the configuration object introduced above allows you to completely -control what the toolbar contains. Following is an example of a one-line, -customized toolbar, much simpler than the default one:

- -
var config = new HTMLArea.Config();
-config.toolbar = [
-  ['fontname', 'space',
-   'fontsize', 'space',
-   'formatblock', 'space',
-   'bold', 'italic', 'underline']
-];
-HTMLArea.replace('id', config);
- -

The toolbar is an Array of Array objects. Each array in the toolbar -defines a new line. The default toolbar looks like this:

- -
config.toolbar = [
-[ "fontname", "space",
-  "fontsize", "space",
-  "formatblock", "space",
-  "bold", "italic", "underline", "separator",
-  "strikethrough", "subscript", "superscript", "separator",
-  "copy", "cut", "paste", "space", "undo", "redo" ],
-		
-[ "justifyleft", "justifycenter", "justifyright", "justifyfull", "separator",
-  "insertorderedlist", "insertunorderedlist", "outdent", "indent", "separator",
-  "forecolor", "hilitecolor", "textindicator", "separator",
-  "inserthorizontalrule", "createlink", "insertimage", "inserttable", "htmlmode", "separator",
-  "popupeditor", "separator", "showhelp", "about" ]
-];
- -

Except three strings, all others in the examples above need to be defined -in the config.btnList object (detailed a bit later in this -document). The three exceptions are: 'space', 'separator' and 'linebreak'. -These three have the following meaning, and need not be present in -btnList:

- - - -

Important: It's recommended that you add -custom features and configuration to a separate file. This will ensure you -that when we release a new official version of HTMLArea you'll have no -trouble upgrading it.

- -

How do I create custom buttons?

- -

By design, the toolbar is easily extensible. For adding a custom button -one needs to follow two steps.

- -

1. Register the button in config.btnList.

- -

For each button in the toolbar, HTMLArea needs to know the following -information:

- -

You need to provide all this information for registering a new button -too. The button ID can be any string identifier and it's used when -defining the toolbar, as you saw above. We recommend starting -it with "my-" so that it won't clash with the standard ID-s (those from -the default toolbar).

- -

Register button example #1

- -
// get a default configuration
-var config = new HTMLArea.Config();
-// register the new button using Config.registerButton.
-// parameters:        button ID,   tooltip,          image,           textMode,
-config.registerButton("my-hilite", "Highlight text", "my-hilite.gif", false,
-// function that gets called when the button is clicked
-  function(editor, id) {
-    editor.surroundHTML('<span class="hilite">', '</span>');
-  }
-);
- -

An alternate way of calling registerButton is exemplified above. Though -the code might be a little bit larger, using this form makes your code more -maintainable. It doesn't even needs comments as it's pretty clear.

- -

Register button example #2

- -
var config = new HTMLArea.Config();
-config.registerButton({
-  id        : "my-hilite",
-  tooltip   : "Highlight text",
-  image     : "my-hilite.gif",
-  textMode  : false,
-  action    : function(editor, id) {
-                editor.surroundHTML('<span class="hilite">', '</span>');
-              }
-});
- -

You might notice that the "action" function receives two parameters: -editor and id. In the examples above we only used the -editor parameter. But it could be helpful for you to understand -both:

- - - -

2. Inserting it into the toolbar

- -

At this step you need to specify where in the toolbar to insert the -button, or just create the whole toolbar again as you saw in the previous -section. You use the button ID, as shown in the examples of customizing the -toolbar in the previous section.

- -

For the sake of completion, following there are another examples.

- -

Append your button to the default toolbar

- -
config.toolbar.push([ "my-hilite" ]);
- -

Customized toolbar

- -
config.toolbar = [
-  ['fontname', 'space',
-   'fontsize', 'space',
-   'formatblock', 'space',
-   'separator', 'my-hilite', 'separator', 'space', // here's your button
-   'bold', 'italic', 'underline', 'space']
-];
- -

Note: in the example above our new button is -between two vertical separators. But this is by no means required. You can -put it wherever you like. Once registered in the btnList (step 1) your custom button behaves just like a default -button.

- -

Important: It's recommended that you add -custom features and configuration to a separate file. This will ensure you -that when we release a new official version of HTMLArea you'll have no -trouble upgrading it.

- -

A complete example

- -

Please note that it is by no means necessary to include the following -code into the htmlarea.js file. On the contrary, it might not work there. -The configuration system is designed such that you can always customize the -editor from outside files, thus keeping the htmlarea.js file -intact. This will make it easy for you to upgrade your HTMLArea when we -release a new official version. OK, I promise it's the last time I said -this. ;)

- -
// All our custom buttons will call this function when clicked.
-// We use the buttonId parameter to determine what button
-// triggered the call.
-function clickHandler(editor, buttonId) {
-  switch (buttonId) {
-    case "my-toc":
-      editor.insertHTML("<h1>Table Of Contents</h1>");
-      break;
-    case "my-date":
-      editor.insertHTML((new Date()).toString());
-      break;
-    case "my-bold":
-      editor.execCommand("bold");
-      editor.execCommand("italic");
-      break;
-    case "my-hilite":
-      editor.surroundHTML("<span class=\"hilite\">", "</span>");
-      break;
-  }
-};
-
-// Create a new configuration object
-var config = new HTMLArea.Config();
-
-// Register our custom buttons
-config.registerButton("my-toc",  "Insert TOC", "my-toc.gif", false, clickHandler);
-config.registerButton("my-date", "Insert date/time", "my-date.gif", false, clickHandler);
-config.registerButton("my-bold", "Toggle bold/italic", "my-bold.gif", false, clickHandler);
-config.registerButton("my-hilite", "Hilite selection", "my-hilite.gif", false, clickHandler);
-
-// Append the buttons to the default toolbar
-config.toolbar.push(["linebreak", "my-toc", "my-date", "my-bold", "my-hilite"]);
-
-// Replace an existing textarea with an HTMLArea object having the above config.
-HTMLArea.replace("textAreaID", config);
- - -
-
© InteractiveTools.com 2002, 2003. -
-HTMLArea v3.0 developed by Mihai Bazon for -InteractiveTools.com. -
-Documentation written by Mihai Bazon. -
- -Last modified on Sun Aug 3 16:11:23 2003 - - - + + + +HTMLArea-3.0 Reference + + + + + + + + + + + + + +

HTMLArea-3.0 Documentation

+ +
+ + This documentation contains valid information, but is outdated in the + terms that it does not covers all the features of HTMLArea. A new + documentation project will be started, based on LaTeX. + +
+ + +

Introduction

+ +

What is HTMLArea?

+ +

HTMLArea is a free WYSIWYG editor replacement for <textarea> +fields. By adding a few simple lines of JavaScript code to your web page +you can replace a regular textarea with a rich text editor that lets your +users do the following:

+ + + +

Some of the interesting features of HTMLArea that set's it apart from +other web based WYSIWYG editors are as follows:

+ + + +

Is it really free? What's the catch?

+ +

Yes! It's really free. You can use it, modify it, distribute it with your +software, or do just about anything you like with it.

+ +

What are the browser requirements?

+ +

HTMLArea requires Internet Explorer >= 5.5 +(Windows only), or Mozilla >= 1.3-Beta on any platform. +Any browser based on Gecko will +also work, provided that Gecko version is at least the one included in +Mozilla-1.3-Beta (for example, Galeon-1.2.8). However, it degrades +gracefully to other browsers. They will get a regular textarea field +instead of a WYSIWYG editor.

+ +

Can I see an example of what it looks like?

+ +

Just make sure you're using one of the browsers mentioned above and see +below.

+ +
+ +
+ +

Where can I find out more info, download the latest version and talk to +other HTMLArea users?

+ +

You can find out more about HTMLArea and download the latest version on +the HTMLArea +homepage and you can talk to other HTMLArea users and post any comments +or suggestions you have in the HTMLArea forum.

+ +

Keyboard shortcuts

+ +

The editor provides the following key combinations:

+ + + +

Installation

+ +

How do I add HTMLArea to my web page?

+ +

It's easy. First you need to upload HTMLArea files to your website. +Just follow these steps.

+ +
    +
  1. Download the latest version from the htmlArea + homepage.
  2. +
  3. Unzip the files onto your local computer (making sure to maintain the + directory structure contained in the zip).
  4. +
  5. Create a new folder on your website called /htmlarea/ (make sure it's + NOT inside the cgi-bin).
  6. +
  7. Transfer all the HTMLArea files from your local computer into the + /htmlarea/ folder on your website.
  8. +
  9. Open the example page /htmlarea/examples/core.html with your browser to make + sure everything works.
  10. +
+ +

Once htmlArea is on your website all you need to do is add some +JavaScript to any pages that you want to add WYSIWYG editors to. Here's how +to do that.

+ +
    + +
  1. Define some global variables. "_editor_url" has to be the absolute + URL where HTMLArea resides within your + website; as we discussed, this would be “/htmlarea/”. "_editor_lang" must + be the language code in which you want HTMLArea to appear. This defaults + to "en" (English); for a list of supported languages, please look into + the "lang" subdirectory in the distribution. +
    <script type="text/javascript">
    +   _editor_url = "/htmlarea/";
    +   _editor_lang = "en";
    +</script>
    + +
  2. Include the "htmlarea.js" script: +
    <script type="text/javascript" src="/htmlarea/htmlarea.js"></script>
    +
  3. + +
  4. If you want to change all your <textarea>-s into + HTMLArea-s then you can use the simplest way to create HTMLArea:

    +
    <script type="text/javascript" defer="1">
    +    HTMLArea.replaceAll();
    +</script>
    +

    Note: you can also add the + HTMLArea.replaceAll() code to the onload + event handler for the body element, if you find it more appropriate.

    + +

    A different approach, if you have more than one textarea and only want + to change one of them, is to use HTMLArea.replace("id") -- + pass the id of your textarea. Do not use the + name attribute anymore, it's not a standard solution!

    + +
+ +

This section applies to HTMLArea-3.0 release candidate 1 or later; prior +to this version, one needed to include more files; however, now HTMLArea is +able to include other files too (such as stylesheet, language definition +file, etc.) so you only need to define the editor path and load +"htmlarea.js". Nice, eh? ;-)

+ +

I want to change the editor settings, how do I do that?

+ +

While it's true that all you need is one line of JavaScript to create an +htmlArea WYSIWYG editor, you can also specify more config settings in the +code to control how the editor works and looks. Here's an example of some of +the available settings:

+ +
var config = new HTMLArea.Config(); // create a new configuration object
+                                    // having all the default values
+config.width = '90%';
+config.height = '200px';
+
+// the following sets a style for the page body (black text on yellow page)
+// and makes all paragraphs be bold by default
+config.pageStyle =
+  'body { background-color: yellow; color: black; font-family: verdana,sans-serif } ' +
+  'p { font-width: bold; } ';
+
+// the following replaces the textarea with the given id with a new
+// HTMLArea object having the specified configuration
+HTMLArea.replace('id', config);
+ +

Important: It's recommended that you add +custom features and configuration to a separate file. This will ensure you +that when we release a new official version of HTMLArea you'll have less +trouble upgrading it.

+ +

How do I customize the toolbar?

+ +

Using the configuration object introduced above allows you to completely +control what the toolbar contains. Following is an example of a one-line, +customized toolbar, much simpler than the default one:

+ +
var config = new HTMLArea.Config();
+config.toolbar = [
+  ['fontname', 'space',
+   'fontsize', 'space',
+   'formatblock', 'space',
+   'bold', 'italic', 'underline']
+];
+HTMLArea.replace('id', config);
+ +

The toolbar is an Array of Array objects. Each array in the toolbar +defines a new line. The default toolbar looks like this:

+ +
config.toolbar = [
+[ "fontname", "space",
+  "fontsize", "space",
+  "formatblock", "space",
+  "bold", "italic", "underline", "separator",
+  "strikethrough", "subscript", "superscript", "separator",
+  "copy", "cut", "paste", "space", "undo", "redo" ],
+
+[ "justifyleft", "justifycenter", "justifyright", "justifyfull", "separator",
+  "insertorderedlist", "insertunorderedlist", "outdent", "indent", "separator",
+  "forecolor", "hilitecolor", "textindicator", "separator",
+  "inserthorizontalrule", "createlink", "insertimage", "inserttable", "htmlmode", "separator",
+  "popupeditor", "separator", "showhelp", "about" ]
+];
+ +

Except three strings, all others in the examples above need to be defined +in the config.btnList object (detailed a bit later in this +document). The three exceptions are: 'space', 'separator' and 'linebreak'. +These three have the following meaning, and need not be present in +btnList:

+ + + +

Important: It's recommended that you add +custom features and configuration to a separate file. This will ensure you +that when we release a new official version of HTMLArea you'll have less +trouble upgrading it.

+ +

How do I create custom buttons?

+ +

By design, the toolbar is easily extensible. For adding a custom button +one needs to follow two steps.

+ +

1. Register the button in config.btnList.

+ +

For each button in the toolbar, HTMLArea needs to know the following +information:

+ +

You need to provide all this information for registering a new button +too. The button ID can be any string identifier and it's used when +defining the toolbar, as you saw above. We recommend starting +it with "my-" so that it won't clash with the standard ID-s (those from +the default toolbar).

+ +

Register button example #1

+ +
// get a default configuration
+var config = new HTMLArea.Config();
+// register the new button using Config.registerButton.
+// parameters:        button ID,   tooltip,          image,           textMode,
+config.registerButton("my-hilite", "Highlight text", "my-hilite.gif", false,
+// function that gets called when the button is clicked
+  function(editor, id) {
+    editor.surroundHTML('<span class="hilite">', '</span>');
+  }
+);
+ +

An alternate way of calling registerButton is exemplified above. Though +the code might be a little bit larger, using this form makes your code more +maintainable. It doesn't even needs comments as it's pretty clear.

+ +

Register button example #2

+ +
var config = new HTMLArea.Config();
+config.registerButton({
+  id        : "my-hilite",
+  tooltip   : "Highlight text",
+  image     : "my-hilite.gif",
+  textMode  : false,
+  action    : function(editor, id) {
+                editor.surroundHTML('<span class="hilite">', '</span>');
+              }
+});
+ +

You might notice that the "action" function receives two parameters: +editor and id. In the examples above we only used the +editor parameter. But it could be helpful for you to understand +both:

+ + + +

2. Inserting it into the toolbar

+ +

At this step you need to specify where in the toolbar to insert the +button, or just create the whole toolbar again as you saw in the previous +section. You use the button ID, as shown in the examples of customizing the +toolbar in the previous section.

+ +

For the sake of completion, following there are another examples.

+ +

Append your button to the default toolbar

+ +
config.toolbar.push([ "my-hilite" ]);
+ +

Customized toolbar

+ +
config.toolbar = [
+  ['fontname', 'space',
+   'fontsize', 'space',
+   'formatblock', 'space',
+   'separator', 'my-hilite', 'separator', 'space', // here's your button
+   'bold', 'italic', 'underline', 'space']
+];
+ +

Note: in the example above our new button is +between two vertical separators. But this is by no means required. You can +put it wherever you like. Once registered in the btnList (step 1) your custom button behaves just like a default +button.

+ +

Important: It's recommended that you add +custom features and configuration to a separate file. This will ensure you +that when we release a new official version of HTMLArea you'll have less +trouble upgrading it.

+ +

A complete example

+ +

Please note that it is by no means necessary to include the following +code into the htmlarea.js file. On the contrary, it might not work there. +The configuration system is designed such that you can always customize the +editor from outside files, thus keeping the htmlarea.js file +intact. This will make it easy for you to upgrade your HTMLArea when we +release a new official version. OK, I promise it's the last time I said +this. ;)

+ +
// All our custom buttons will call this function when clicked.
+// We use the buttonId parameter to determine what button
+// triggered the call.
+function clickHandler(editor, buttonId) {
+  switch (buttonId) {
+    case "my-toc":
+      editor.insertHTML("<h1>Table Of Contents</h1>");
+      break;
+    case "my-date":
+      editor.insertHTML((new Date()).toString());
+      break;
+    case "my-bold":
+      editor.execCommand("bold");
+      editor.execCommand("italic");
+      break;
+    case "my-hilite":
+      editor.surroundHTML("<span class=\"hilite\">", "</span>");
+      break;
+  }
+};
+
+// Create a new configuration object
+var config = new HTMLArea.Config();
+
+// Register our custom buttons
+config.registerButton("my-toc",  "Insert TOC", "my-toc.gif", false, clickHandler);
+config.registerButton("my-date", "Insert date/time", "my-date.gif", false, clickHandler);
+config.registerButton("my-bold", "Toggle bold/italic", "my-bold.gif", false, clickHandler);
+config.registerButton("my-hilite", "Hilite selection", "my-hilite.gif", false, clickHandler);
+
+// Append the buttons to the default toolbar
+config.toolbar.push(["linebreak", "my-toc", "my-date", "my-bold", "my-hilite"]);
+
+// Replace an existing textarea with an HTMLArea object having the above config.
+HTMLArea.replace("textAreaID", config);
+ + +
+
© InteractiveTools.com 2002-2004. +
dynarch.com 2003-2004
+HTMLArea v3.0 developed by Mihai Bazon. +
+Documentation written by Mihai Bazon. +
+ Last modified: Wed Jan 28 12:18:23 EET 2004 + +