HTMLArea-3.1 - 4.x Documentation

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:

• Format text to bold, italicized, or underlined.
• Change the font family, size, style, and color.
• Align your text left, center, or right, or justified.
• Create bulleted, or numbered lists.
• Indent or outdent paragraphs.
• Insert a horizontal line.
• Insert hyperlinks and images.
• View the raw HTML source of what you're editing.
• and much, much more...

Some of the more interesting features that set HTMLArea apart from other web based WYSIWYG editors are as follows:

• It's lightweight, fast loading and can transform a regular textarea into a rich-text editor with a single line of JavaScript.
• Generates clean, valid (X)HTML.
• It degrades gracefully in older, unsupported browsers (they get the original textarea field).
• It's free and can be incorporated into any free or commercial product, or project.
• It works with any server-side languages (PHP, Perl, Java, ASP, etc).
• It's written in JavaScript and can be easily viewed, modified or extended.
• It remembers entered content when a user navigates away and then hits <-- back in their browser.
• Since it replaces existing textareas it doesn't require a lot of code to add it to your pages (just one line).
• Have we mentioned it's free?

Is it really free? What's the catch?

No catch, 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 version 5.5, or greater (Windows only), or any Geko based browser that is newer than Mozilla 1.3-Beta (any platform). Any browser based on Gecko will work, provided that the Gecko version is at least the one included in Mozilla-1.3-Beta (for example, Galeon-1.2.8). However, it degrades gracefully for other, older browsers. They will simply see a regular textarea field instead of a WYSIWYG editor. It will also work in Opera browsers greater that (?) - need to get more data. I'll update this shortly.

Can I see an example of what it looks like?

Sure. 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:

• CTRL-A -- select all
• CTRL-B -- bold
• CTRL-I -- italic
• CTRL-U -- underline
• CTRL-S -- strikethrough
• CTRL-L -- justify left
• CTRL-E -- justify center
• CTRL-R -- justify right
• CTRL-J -- justify full
• CTRL-1 .. CTRL-6 -- headings (<h1> .. <h6>)
• CTRL-0 (zero) -- clean content pasted from Word

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, or it's SourceForge project page.
2. Unpack the files in the archive onto your local computer (making sure to maintain the directory structure contained in the archive).
3. Create a new folder on your website called /htmlarea/ (make sure it's NOT inside the cgi-bin directory).
4. Transfer all the HTMLArea files from your local computer into the /htmlarea/ folder on your website.
5. Open the example page /htmlarea/examples/core.html with your browser to make sure everything works.

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:

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. If you want to change all your <textarea>’s into HTMLAreas, the simplest way to create an HTMLArea is:

   <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 the htmlarea.js file. Nice, eh? ;–)

I want to change the editor settings, how can 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 the paragraphs 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:

• 'space' — Inserts a space of 5 pixels (the width is configurable by external CSS) at the current position in the toolbar.
• 'separator' — Inserts a small vertical separator, for visually grouping related buttons.
• 'linebreak' — Starts a new line in the toolbar. Subsequent controls will be inserted on the new line.

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:

• a name for it (we call it the ID of the button);
• the path to an image to be displayed in the toolbar;
• a tooltip for it;
• whether the button is enabled or not in text mode;
• what to do when the button is clicked;

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"#62;', '</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:

• editor is a reference to the HTMLArea object. Since our entire code now has an OOP-like design, you need to have a reference to the editor object in order to do things with it. In previous versions of HTMLArea, in order to identify the object an ID was used — the ID of the HTML element. In this version ID-s are no longer necessary.
• id is the button ID. Wondering why is this useful? Well, you could use the same handler function (presuming that it's not an anonymous function like in the examples above) for more buttons. You can see an example a bit later in this document.

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