Rich Web Text Editing with Kupuby 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.
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.
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
To see what the editor looks like, start up a suitable browser and type in
the path to this file on your web site
path>/kupu/common/kupu.html (in other words, you supply everything
before the kupu/ directory name). You can look at an installation on
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.
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
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
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
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
<base> tag in the
<head> section of
the web page that points to the common subdirectory in the distribution. For
<head> <base href="http://www.craic.com/oreilly/kupu/kupu/common/"> </head>
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.