May 22, 2007

Setting up TinyMCE

Author: Bruce Byfield

Moxiecode's LGPL-licensed TinyMCE (Tiny Moxiecode Editor) is a JavaScript program that lets users enter formatted text in HTML forms without having to know HTML tags. It's bundled in many blogging and content management systems. If you want to use TinyMCE in your own Web applications, you'll find basic setup to be quick and easy, but advanced configuration can become complex as you sort out dependencies and conflicts. Here are some tips and advice on integrating TinyMCE with your Web pages.

TinyMCE is available as a package in many GNU/Linux distributions, or as zip or tar/gzip archive. To install the program, extract the TinyMCE directory structure to the root directory of your Web site, then add the script with all its customizations directly after the opening <head> tag on each page on which you want the program enabled.

Successful installation adds a toolbar to <textarea> HTML tags. By default, the toolbar is added to all textarea tags, but you can also configure it to use only designated ones. The results are viewable under GNU/Linux in Opera and Firefox and other Gecko-based browsers such as Epiphany when JavaScript is enabled. TinyMCE does not work in Konqueror, and may be incompatible with some Firefox extensions. In browsers in which TinyMCE does not work, plain input fields appear instead.

Fast configuration

To enable TinyMCE on the page, all you need to do is add the following lines after the opening <head> tag on a page:


<script language="javascript" type="text/javascript" src="../jscripts/tiny_mce/tiny_mce.js"></script>
<script language="javascript" type="text/javascript">
tinyMCE.init({
mode : "textareas"
});
</script>

This script adds TinyMCE to all forms on the page, with a well-rounded selection of tools, including icons for basic formatting, undo/redo, lists, special characters, and a drop-down list of basic HTML paragraph tags.

If you prefer a more basic set of tools, you can specify the Simple theme by adding another line below the mode field: theme : "simple". Change the theme to "advanced," and you get the same set of tools as when the theme is unspecified.

You can install other, more complex formats by looking at the page sources on TinyMCE's example page. Among them you'll find a full-featured example that includes virtually every configuration option that can be added to TinyMCE.

More detailed configuration

For those who require more granular control, TinyMCE includes more than 125 different configuration options. These options, together with their dependencies and conflicts, are sparsely but adequately documented on the program's Web page.

Each option is added to the script below the line that starts with tinyMCE.init, one option per line. When an option has more than one value, the values are listed in a comma-separated list. For example, if you added the theme_advanced_buttons1_add option to customize the buttons on the toolbar, the line in the script might read:


theme_advanced_buttons1_add : "separator,insertdate,inserttime,preview,zoom,separator,forecolor,backcolor"

The Web page divides the configuration options into 11 categories:

  • General: Options to use plugins, set languages, view debugging information, add a spellchecker for Gecko-based browsers such as Firefox, customize keyboard shortcuts, and many others.
  • Callbacks: Arguments that affect how TinyMCE operates and interacts with other programs, especially when the contents of a form are saved.
  • Cleanup: Settings for valid elements, .css classes, entities, doctypes, and HTML tags in input.
  • URLS: Settings for how TinyMCE displays and stores addresses.
  • Layout: Selections of which .css files TinyMCE uses in various circumstances, as well as the width and height of the TinyMCE toolbar.
  • Visual aids: Setup tools for guidelines for borderless tables.
  • Undo/redo: Options for the number of stored undos and redos, as well as keyboard shortcuts for the operations.
  • File lists: Adds lists of external links or images to the toolbar.
  • Tab specific: Options for setting how TinyMCE is used with tabs in Microsoft Internet Explorer.
  • Triggers/patches: Triggers that can be set to alter TinyMCE's behavior.
  • Advanced themes: Options for customizing the advanced theme with more formatting options, including many for adding additional tools. A complete list of the buttons that you can use to customize the advanced theme is available on the program's Web site.

Add configuration options and their dependencies one at a time for debugging purposes. In my experience, a single error in spelling, syntax, or positioning generally prevents all of TinyMCE from displaying properly. In some cases, adding an option that is already an assumed default in another setting will also keep TinyMCE from displaying.

Besides trial and error, another way to learn the correct setup for an option is often to keep the source code for the full-featured example open. Between this example and the Web site documentation, you should be able to solve most of your configuration problems with a little patience.

The site also includes a library of support documents, and a user forum. In addition, Moxiecode offers paid support.

Other configuration options and issues

A few details of TinyMCE configuration extend outside the JavaScript options. Font size, color, and other display elements can be configured either by altering the .css file for the theme being used or -- better yet -- by using the content_css option to specify a custom-written file.

More importantly, those building sites using PHP, Ruby on Rails, or other languages should look at the detailed information and examples on the project's wiki documentation page. The information on TinyMCE compression with different languages in order to reduce initialization time may be especially useful for high-traffic sites.

Unless your needs are simple, or can be answered by modifying one of Moxiecode's examples, setting up a customized version of TinyMCE may take some time. It's not that the program is difficult to use -- it's just that the options are so numerous that it takes time to know what's available and how your choices interact. However, once you have these issues sorted out, you'll understand why TinyMCE is so ubiquitous nowadays. It really is a program with something for every need.

Bruce Byfield is a computer journalist who writes regularly for NewsForge, Linux.com, and IT Manager's Journal.

Click Here!