oreilly.comSafari Books Online.Conferences.


Rich Web Text Editing with Kupu
Pages: 1, 2, 3

Using Kupu with PUT

The first approach for integrating Kupu is to use the PUT method to upload files to your web server. PUT is the neglected sibling of GET and POST, the most frequently used methods in the http protocol. It allows you to upload complete files onto a web server, placing them into a web tree with defined names. Of course you can do this using HTML forms and CGI scripts, but the intent of PUT is to simplify this process. Publishing Pages with PUT, from 1997, provides some background.

Perhaps the main reason that PUT has seen little use is its inherent insecurity. It has the potential to allow anyone to upload any kind of file to your site. You need to pay close attention to your configuration to close off any potential security hole. Making a simple error can create a major vulnerability. In contrast, you can think of using the POST method as starting out with a closed, secure system to which you explicitly allow access through your CGI scripts. It involves more programming effort, but the risk is easier to manage.

A PUT request sends two header lines ahead of the real content. CONTENT_LENGTH tells the server how much data to expect. PATH_TRANSLATED gives the path of the file into which to write that data. Think of this as the reverse of a browser fetching a page from the server. The default Apache httpd configuration accepts PUT requests, but in order for it to work you need to specify a CGI script that will handle the file. Do so with this directive, replacing the script name with your own:

Script PUT /cgi-bin/kupu/handle_put.cgi

Here is a simple CGI script that implements this. Note that this has no security checks built into it. Anyone could upload any file to a site that runs this script. Add your own restrictions before you install this on a public web site. You have been warned! (This example is not a live application on my site.)

#!/usr/bin/perl -w
# handle_put.cgi
# Basic PUT Handling routine with NO SECURITY!

  errorMsg("Request method is not PUT");

my $filename = $ENV{'PATH_TRANSLATED'};

if(not $filename) {
  errorMsg("PATH_TRANSLATED was empty");

my $length = $ENV{'CONTENT_LENGTH'};

if(not $length) {
  errorMsg("CONTENT_LENGTH was empty");

# Add Security Checks Here! Limit access to certain
# directories and limit size and/or type of file.  E.g.

if($length > 100000) {
  errorMsg("CONTENT_LENGTH is too large");

# Read in the uploaded data
my $content = '';

my $nread = read(STDIN, $content, $length);
# Make the output more readable by adding newlines
$content =~ s/\>\</\>\n\</g;

# Write the file on the web server

open OUT, "> $filename" || errorMsg("Unable to open $filename");
print OUT $content;
close OUT;

# The 204 code signals the transfer was OK but does not 
# update the current page - so you stay in the editor
print qq[Status: 204\n];
print qq[Content-type: text/html\n\n];
print $content;

sub errorMsg {
  my $msg = shift;
  print qq[Content-type: text/html\n\n];
  print qq[<html><head><title>Error</title></head>\n];
  print qq[<body>\nError: $msg<br>\n</body></html>\n];

That is all the server needs. Now set up Kupu to use PUT. You don't need to specify the CGI script in the web page, as the Apache config file has preconfigured this. All you need to specify in the page is the filename on the server at which to write the content. Make a copy of kupu/common/kupu.html into your working directory and add a <base> tag, as described above, so that it can load in the JavaScript libraries from the distribution directory.

Take a look at the source of this page. With more than 300 lines, it's not for the faint of heart. What's more, a lot of it does not look like regular HTML. Fortunately, only two of these lines matter now, one near the top of the page and one near the bottom. As for the rest, leave it untouched for now. Specify the page to load into the editor on startup in the <iframe> at the bottom of kupu.html. Here I have it set to a blank page (kupublank.html):

<iframe id="kupu-editor" frameborder="0" src="kupublank.html" scrolling="auto">

Next, specify where to write the completed page on the server. Look for the <kupuconfig> block, about 30 lines down from the top of the page:


Put the complete URL of the target file between the <dst> tag pairs. This directory needs to be writable by the web server, typically user apache. Note that you are specifying a single file. In these examples, you don't have the option of defining the filename at runtime.

Load the editor that you just configured into your browser, enter some text, and play around with the formatting. To save the file, click on the disk icon in the Kupu toolbar. It will appear that nothing has happened, as Figure 2 shows.

freshly-edited text
Figure 2. Freshly edited text

Now go to the URL that you defined as the target. You should see your newly defined page exactly as you defined it, but without all the toolbars. Figure 3 shows an example.

the newly created page
Figure 3. The newly created page

This is a simple example, and you will quickly see several shortcomings. You overwrite the target file every time you save, for example. Although the Kupu developers favor the PUT method, if you embed the editor into your own applications, especially a CMS, you will probably find that using it within a form will offer more control.

Pages: 1, 2, 3

Next Pagearrow

Sponsored by: