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

Using Kupu Within an HTML Form

The second approach is to wrap a form around the Kupu code. This requires more effort on the back end, as it needs a CGI script to handle the data. However, it gives you more control over what you do with the data than did the PUT technique, which simply mirrored what was in the editor.

Start with an example HTML form called kupuform.html, which you can find in the kupu/common/ directory. In a browser, the page looks the same as the kupu.html from the previous example. The source for the page is very similar but with some critical differences. About 20 lines down from the top, you should find a <form> tag:

<form action="http://debris.demon.nl/printpost" method="POST">

The URL defines the script that will process the uploaded content. Replace it with your own script. Now go to the bottom of the file and look back eight or so lines for an <iframe> tag:

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

The src attribute specifies the document to load into the editor when it starts. In this case, it's the one shown in the screen dump, called fulldoc.html.

To make this form your own, change these lines. First of all, make a copy of kupuform.html in your working directory, and add a <base> tag so you can access the JavaScript libraries as before. Start with a blank page in the editor by specifying an empty file in the <iframe> tag, using the file kupublank.html in the distribution directory.

You need to have a CGI script on the server that can do something with the uploaded data. Here is a simple script (kupu_echo.cgi) that reads the content posted by the form, in the parameter kupu, and gives it straight back to the user. Kupu generates HTML with no newlines, which makes viewing the source difficult, so the script inserts a newline character after each tag.

#!/usr/bin/perl -w
# kupu_echo.cgi

use CGI;
my $cgi = CGI->new();

my $text = $cgi->param('kupu');
$text =~ s/\>/\>\n/g;

print $cgi->header();
print $text;

Put this into the cgi-bin/ directory on your web site, make it executable with chmod a+x kupu_echo.cgi, and put the URL for it into the <form> tag. The two tags to change should now look something like this:

<form action="http://www.craic.com/cgi-bin/kupu/kupu_echo.cgi" method="POST">

...

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

Give it a try. Go to kupuform.html and you should see a blank panel in the editor. Add some text and format it to your tastes. Click on the disk icon in the toolbar to upload it to the CGI script. If you need instant gratification, see the blank Kupu editing demo on my site.

That wasn't too painful. You had to change two lines in the template web page and write a small CGI script. Most importantly, you didn't have to touch a single line of JavaScript! This is a simple example, of course, but it gets you through the first phase in the learning curve.

A Larger Example

For a slightly more involved example, I've written a very basic blogging application using Kupu within a form as the way to create new records.

It consists of a template HTML file, which contains all the Kupu code, and a CGI script that modifies this on the fly, handles new entries submitted to the blog, and displays the titles of existing entries and the links to them. It's pretty basic, but it shows one way to integrate the editor into a form with other data-entry widgets. It also serves as a gentle introduction to modifying the Kupu template page.

Figure 4 is a screenshot of the application with a few entries already added to the blog. To make it realistic, I've tried to make the entries match the exciting content of those in most of the blogs out there today.

Figure 4. Kupu as a weblog editor

In addition to the editor, there is a regular text <input> widget used to enter a title for the entry. Using a form lets you combine your own data-entry widgets with the full power of the editor. I've made some changes to the template page so as to rearrange the Kupu toolbar a little. Look at some of the screenshots on the Kupu homepage for examples of how different CMSes have customized. To really get into that, you need to understand the JavaScript that makes up the application and come to grips with the XML it uses to configure itself. That is far beyond the scope of this article, however.

The complete source code of this application is too long to include here, but you can retrieve it as well as the other code examples from my Kupu site.

View the source of my template Kupu page and you will see comment lines of the form <!-- ### --> that indicate where I have modified the original kupuform.html template. The CGI script replaces any Perl-like variables in the template, like $srcFile, on the fly. (Yes, I know this would be easier in PHP!) I've also included the source for the Perl CGI script.

You can also try the simple Kupu-based blogging application on my site. (I delete all entries on a regular basis.)

Final Thoughts

The examples shown here merely scratch the surface of the Kupu software, but they lay the foundation for your own experiments and, for the brave among you, for understanding the XML and JavaScript magic that makes Kupu work. The technology used here and in other applications that use XMLHttpRequest is an important emerging force in web development. It's well worth your attention.

Robert Jones runs Craic Computing, a small bioinformatics company in Seattle that provides advanced software and data analysis services to the biotechnology industry. He was a bench molecular biologist for many years before programming got the better of him.

Return to ONLamp.com.