Rich Web Text Editing with Kupu

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.

JavaScript

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 http://kupu.oscom.org/download/
(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.

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:

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.