oreilly.comSafari Books Online.Conferences.


Rich Web Text Editing with Kupu

by Robert Jones

Over the years that I've been writing web applications, I have always lacked a good way for users to enter and upload arbitrary blocks of text. A TEXTAREA tag in an HTML form handles basic text, but most of my applications have involved richer content. Having users write whatever they want in a word processor and then upload their documents to the server is a way to capture rich text, but it doesn't let you do much with the information once you have it. What I really needed was a WYSIWG editor that I could embed into an arbitrary web page. Now I've found one: Kupu.

Kupu is an open source application, written in JavaScript, that implements a flexible, full-featured HTML editor that runs in a web page without any special plugins. Its primary use is as an embedded editor in content management systems (CMS), like Zope or Plone, where it allows users to create their own web pages. Its design is flexible enough so that you can embed it into pretty much any web application without too much difficulty.

Without too much difficulty, that is, once you've figured out how it works. Like many other wonderful pieces of software, Kupu does itself a disservice with limited documentation and minimal or no comments in the source code. I understand why this happens. The developers want to use their limited time to write new code rather than create documentation. However, in doing so they severely limit the impact their work will have on the community. Open source software is not just about availability, it's also about accessibility.

In this article I want to make Kupu more accessible and show how easy it is to embed in your applications. It's a great application, and it deserves a wider audience.


Kupu was written by Paul Everitt, Guido Wesdorp, Philipp von Weitershausen, and colleagues, and it represents a remarkable feat of JavaScript programming. Speaking as one who struggles with that language for even the simplest of applications, I have the greatest admiration for the work that's gone into this project.

JavaScript seems to be experiencing a bit of a renaissance at the moment as people figure out the value of XMLHttpRequest. Kupu uses it, as does Google Maps, which has recently made its impressive debut, and Google Suggest. XMLHttpRequest is a way for the browser and server to communicate in the background without having to rebuild the entire page every time any data changes. Read more about that in Drew McLellan's article Very Dynamic Web Interfaces. Additionally, Joel Webber has dissected the technology used in Google Maps.

Unfortunately, using the full power of JavaScript, and XMLHttpRequest in particular, means that you run into compatibility issues with certain browsers. Right now, Kupu runs only on these browsers or higher versions thereof: Mozilla 1.3.1, Internet Explorer 5.5, and Netscape Navigator 7.1. It does not run on Konqueror, Opera, or Safari. Hopefully, upcoming releases will provide the missing features.

Installing Kupu

Basic installation is easy. Download the tar file from (450K), and unpack it in a directory that is accessible from your web site. It creates and populates a directory called kupu/. You'll see a number of files and subdirectories. The beginner can happily ignore the vast majority of these. You don't need to run make or any of that business. At this stage I suggest that you actively avoid the documentation in the doc/ subdirectory.

To see what the editor looks like, start up a suitable browser and type in the path to this file on your web site <your path>/kupu/common/kupu.html (in other words, you supply everything before the kupu/ directory name). You can look at an installation on my Kupu editor test page. You will see something like the page shown in Figure 1.

Kupu example page
Figure 1. A Kupu example page

There are three parts to this page. The toolbar at the top contains icons for the standard functions people expect to find in an editor. The panel to the right contains blocks for certain functions that require additional information. The panel on the left is the actual document you are editing. In this case it preloads a default document that explains a little about the design philosophy of Kupu.

To edit the text, click somewhere in the text and start typing. If you are using Firefox and that doesn't do anything, press F7 on your keyboard. That enables something called caret browsing, which should fix the problem. Take it for a spin. The interface has a few quirks, but it's pretty intuitive. Select some text and change its color and format. Create some links. Insert an image from a URL and resize it. Best of all, insert a table and add and delete rows and columns. If you try to save your changes from this demo you will trigger an error, but I'll show how to fix that soon.

In its current release, Kupu may not do everything you want from a WYSIWYG editor. You can't change the fonts, for example, and you can only insert images that are already available on the Web. A couple of other features don't seem to work, at least in my hands. Its capabilities are more than enough for a lot of applications, though. Kupu is an amazing achievement when you consider that no plugin or Java applet is involved. This is just a web page with JavaScript.

Kupu's real value comes from its ability to be embedded in other applications. You can do this in one of two ways. The easiest is to have it upload its content to the server as a parameter to a CGI script, using the POST method. Less conventional, but the preference of the Kupu team, is to use the PUT method, along with a simple CGI script, to upload the content into a specific file on the web site.

Working with the Kupu Distribution

All of these features come at the price of a lot of JavaScript code in files that you need to include in pages that have Kupu embedded in them. Even a basic page like common/kupu.html contains some pretty daunting code. What's more, all of those links to the included files are relative, which can cause all sorts of headaches if you want to mess around with the structure of the distribution directory. You really don't want to touch the distribution, but you need a way to link your custom content to it and still have everything work. Fortunately, there is a simple solution in the form of the <base> tag.

Place the distribution into a subdirectory under your web tree. Now create a directory elsewhere under the tree for your own pages. Copy over a template page (kupu/common/kupu.html or kupu/common/kupuform.html) and add a <base> tag in the <head> section of the web page that points to the common subdirectory in the distribution. For example:

<base href="">

This has the effect in your browser of prepending that URL to any relative links it encounters. Note that it has to be the complete URL path to the directory, including the host name, and that this will apply to all relative URLs in this page, not just the Kupu-related ones. Bear this in mind if you include any images, style sheets, or links to other pages on your site.

Pages: 1, 2, 3

Next Pagearrow

Sponsored by: