Chapter 17

Combining JavaScript, CGI, and SSI


CONTENTS

In the beginning, the Web was a read-only medium-you could browse all sorts of information and link from site to site, but you couldn't really contribute anything yourself, except by clicking on an e-mail address.

The Common Gateway Interface (CGI) specification was the first step in making the Web more interactive. With new languages such as JavaScript and Java adding interactivity, you might wonder whether CGI has become obsolete. At the moment, this is far from true-CGI bears little resemblance to these languages, and can perform tasks impossible to other languages.

Because this is a book about JavaScript, this chapter doesn't go into detail about CGI -it's complicated enough to have merited a few books of its own. You will take a look at the basics of how CGI works, along with its close relative, SSI. This chapter presents a few examples of simple CGI scripts and explains how you can install scripts on your server. Finally, you'll learn how CGI, SSI, and JavaScript can work together to improve your Web pages.

NOTE
There are many books about CGI. I recommend Teach Yourself CGI Programming in Perl by Herrmann, and HTML & CGI Unleashed by December, Ginsburg et al., both published by Sams.net

Choosing the Right Tool for the Job

Although CGI may become obsolete in the future, it won't be JavaScript that replaces it-they're very different things, and each has its uses. Here are the main differences:

Comparing JavaScript with CGI

To illustrate the difference between JavaScript and CGI programs, let's look at one program that could be written using either-a program to display a random quotation when you load the page. I happen to have examples of both handy:

Using these pages as an example, here are a few comparisons of the capabilities of JavaScript and CGI:

As you can see, both JavaScript and CGI have advantages and disadvantages. Which you choose for a particular job will depend on what you need to do and what resources you and your users will have available.

The Basics of CGI

CGI is a specification that enables programs to run on a Web server, accept data from the browser, and send data back in the form of a Web page. CGI programs can be written in any language the server understands.

TIP
CGI programs are sometimes referred to as CGI scripts, because many of the languages used for CGI are considered scripting languages.

When you're browsing the Web, you can access a CGI program in one of two ways:

In technical terms, a request is being sent to the HTTP server to run the CGI program. After you send your request using either method, the CGI program can send output back to you in the form of a Web document. An entire document is always sent.

GET and POST Requests

The requests sent to the server are sent using one of two methods. The difference between these lies in the way that data from your browser, or from form elements you filled out, are sent to the server. The two methods are the following:

Defining Requests in Forms

When you define an HTML form, you specify a CGI script to process the information and the method that will be used. You can do this using the following attributes to the <FORM> tag in HTML:

As an example, the following <FORM> definition uses the POST method and sends the data to a program called data.cgi:

<FORM NAME="form1" ACTION = "data.cgi" METHOD = "POST">

NOTE
A JavaScript program cannot be used as the ACTION of a form, but it can work with the data before it is sent to the CGI program. Chapter 6describes the use of JavaScript with forms.

Name and Value Pairs

A CGI program receives the data from the form as a group of name and value pairs. Each of these includes a name for the item and the item's value. For example, if the user entered "Fred" into a text field called text1, the name/value pair would have the name text1 and the value Fred.

Part of the work of a CGI program is to decipher these name/value pairs. Depending on the method used, the program receives the data in one of two ways:

In both cases, the data appears as a single large string, and you must separate it into names and values. For example, the following is how a request with two variable values might appear:

name=Fred&Address=123+Elm+Street

The & characters separate each name/value pair, and the = symbol separates each name from its value. In addition, notice that the spaces the user entered were replaced by + symbols. This is called URL encoding, and a CGI program must also take this into account. Along with replacing spaces with +, URL encoding replaces nonalphanumeric characters with escape codes; for example, the tilde (~) character becomes %7E.

Using URL Encoding and Decoding

CGI sends data to the server using URL encoding, and you may need to encode data you are sending. You may also run into this encoding using JavaScript; for example, data you send using the mailto: method is encoded this way. URLs sometimes include encoded characters, and you may need to decode them.

JavaScript includes two functions to let you work with encoding:

With either function, simply use the text to be converted as the function's parameter.

Environmental Variables

Along with the name/value pairs, a CGI program also receives information in environment variables. These include a variety of items about the server and the browser. Here are a few of the most common ones:

As you can see, these include some information that is not available to JavaScript. You'll see a way to make this information available to JavaScript in the task Creating JavaScript Functions with SSI, later in this chapter.

How CGI Programs Generate Output

The final step in a CGI program is to display data back to the user. This may be as simple as a confirmation that the data was received, or it could be a complete Web page that is created based on the form data. The output of a CGI program is always displayed on a new, blank Web page.

Before a CGI program sends its output to the client, it must specify the type of document that will be created. These are MIME document types, and they can be of any type. Most CGI programs return an HTML document, using the text/html type.

The first line a CGI program outputs is a header that indicates the MIME type. The following header indicates an HTML document:

Content-type: text/html

NOTE
The Content-type header must always be followed by a blank line, before the actual output of the program begins

Optionally, a CGI program can send the user to an existing Web page, rather than outputting a document of its own. This is done using the Location: header, as in this example:

Location: http://www.starlingtech.com/books/javascript/

You should now have an understanding of the basics of CGI programming. You'll look at the specific languages a CGI program can use later in this chapter and also see an example of a CGI program.

SSI: CGI Within a Web Page

An alternative to CGI is Server-Side Includes (SSI). These are special directives recognized by some Web servers, which enable you to execute a program or perform another function at any point within a Web page. SSI enables you to produce output as part of a Web page-in this way, it's similar to JavaScript.

An SSI program is similar to a CGI program-in some cases, the same program can be used. The main difference is in the way the program is called. An SSI program is called using an SSI directive in the HTML of the page. You'll look at the various directives that can be used in the next section.

Another difference between CGI and SSI is that an SSI program does not have access to form elements. It executes while the page is being sent to the client. An SSI program does, however, have access to the same environmental variables as CGI, as listed in the section titled Environmental Variables, earlier in this chapter.

Server-Side Include Directives

SSI directives are interpreted by the server before being sent to the browser. Thus, they will be invisible to the user; only the output of an SSI program shows up in the HTML source.

Here is an example of an SSI directive that executes a program:

<-#exec program.ssi>

The following are the available commands for the latest SSI specification, called SSI+ 1.0:

Enabling Server-Side Includes

To use SSI in a Web page, you need to enable the feature in the Web server. Because the server must preparse each document and interpret the SSI commands, the server can be slowed down, so it is usually not enabled by default.

The exact process to enable SSI for your pages will depend on the server software and on how the administrator has configured it. You may have to do one of the following:

Languages for CGI and SSI

As mentioned before, CGI isn't a language in itself-just a specification. CGI and SSI programs can be in any language the server (and the page developer) understands.

Several languages are commonly used for CGI and SSI. You'll look at a few of the most common ones in the sections that follow.

Perl

Perl is by far the most common language used for CGI programs today. Perl is a versatile scripting language available for UNIX, DOS, and Windows NT platforms; practically every Web server has Perl available.

Like JavaScript, Perl is an interpreted language, so programs you download or create in Perl will not require compiling.

Perl's syntax is unique and can be confusing; however, you'll find that it has much in common with JavaScript. Many books are available that explain Perl fully; you can also refer to appendix C, "Online JavaScript Resources," for Web pages with information about Perl.

C and C++

C and its object-oriented counterpart, C++, are also a popular choice for CGI. Unlike Perl, these languages must be compiled. If you download a public-domain program in these languages, you need to compile it to run on your particular server.

Other Languages

Simple shell languages, such as sh and csh, are a common choice for simple CGI programs on UNIX platforms. Other possibilities include Python and TCL. Any language you know can be used, provided it's available on your server.

Creating a Simple CGI Program

Although we won't explain every detail about Perl and CGI in this chapter, you may find this example helpful. The program in Listing 17.1 is a Perl program that sends the data entered in a form via e-mail.


Listing 17.1. (EMAIL.PL) An example of a Perl CGI program to e-mail a form's data.
#!/usr/bin/perl

MAIN:  {
    $sendmail = "|/usr/bin/sendmail user@address";
    open(MAIL, $sendmail);
# Read POST data from standard input.
# The CONTENT_LENGTH variable tells us how
# many bytes to read.
    read(STDIN, $request, $ENV{ÔCONTENT_LENGTH'});
# Split request into name/value pairs
    %rqpairs = split(/[&=]/, $request));
# Convert URL syntax to ASCII
    foreach (%rqpairs) {
        tr/+/ /;
        s/%(..)/pack("c",hex($1))/ge;
    }
# headers for mail message
     print MAIL "From: web@server\n";
     print MAIL "To: user@address\n";
     print MAIL "Subject: Form submission\n";
# Add each name/value pair to mail message
    while (($key,$value) = each %rqpairs) {
        print MAIL "$key = $value\n";
    }
close MAIL;
# Output an HTML document
print "Content-type: text/html\n\n";
    print "<HTML><HEAD><TITLE>Mail sent</TITLE>";
    print "</HEAD><BODY>";
    print "<H1>Mail sent</H1>";
    print "Your mail was sent successfully.";
    print "</BODY></HTML>";
exit 0;
}

This program reads the name and value pairs from a POST request and decodes them, then sends them in an e-mail message. This program may require minor changes to work on your server. You'll look at the process of installing a CGI program on a server in the next section.

TIP
Like JavaScript, Perl allows comments. The lines beginning with # in Listing 17.1 are comments, and they describe the purpose of each section of the program.

Installing a CGI Script

Whether you learn to write CGI programs yourself or decide to use one of the many available public-domain CGI programs, you'll need to install it on your Web server to use it. This section explores the steps you follow to do this.

Depending on your situation, you might need to cooperate with the administrator of your server to perform these tasks. Some Internet providers do not allow CGI programs at all; you should check with the staff if you have any doubts or if the following steps don't work.

Here are the steps for installing a CGI program:

  1. After creating or downloading the program, transfer it to the server. You will use an FTP program to do this. Depending on your Internet provider, the administrator may need to do this for you.
  2. You may need to place the program in a specific directory, such as cgi-bin, to make it work. In addition, you may need to rename it with an extension such as .cgi. Again, this will depend on your Web server.
  3. You will need to set the permissions correctly so that users can run the program. The UNIX command chmod a+x filename will usually work for this purpose.
  4. Determine the URL for the program. This will depend on your server's configuration and the directory in which you have placed the program.
  5. Place the correct URL in your HTML form and test the CGI program by submitting the form.

NOTE
Additional steps may be necessary, depending on the configuration of your Web server. Check with your administrator if the previous steps don't work.

Creating JavaScript Functions with SSI

Here's an example of how SSI and JavaScript can work together. This case uses an SSI directive to create JavaScript "on the fly," in much the same way that JavaScript can create HTML "on the fly."

You learned earlier in this chapter that the CGI variables, such as REMOTE_HOST, are not available in JavaScript; using SSI, though, you can make them available to JavaScript. Listing 17.2 shows an HTML document that uses this feature.


Listing 17.2. (SSIVAR.htm) Combining SSI and JavaScript.
<HTML>
<HEAD><TITLE>SSI and JavaScript</TITLE>
</HEAD>
<BODY>
<H1>CGI variables in JavaScript</H1>
<HR>
This program displays your current host in a
JavaScript dialog box.
<HR>
<SCRIPT LANGUAGE="JavaScript">
Host = "<-#echo var=REMOTE_HOST->";
window.alert("Your host is: " + Host);
</SCRIPT>
</BODY>
</HTML>

This JavaScript program simply sets a variable to the host name and displays it to the user by using the window.alert() method. The tricky part is that you have assigned the Host variable using an SSI echo directive.

The SSI will be interpreted by the host before sending the HTML document to the browser, so when the browser interprets it, the actual host will be in place of the #echo directive.

Workshop Wrap-Up

In this chapter you learned about CGI and SSI, and how they can work with JavaScript:

Next Steps

Move on with one of the following:

Q&A

Q:Can I use JavaScript to create SSI commands depending on a variable?
A:No. By the time the browser sees the page, the SSI commands have already been parsed by the server. You can use SSI to create JavaScript, but not the other way around.
Q:When I install a CGI script and try to use it, I get an error indicating that the program doesn't exist. What's the solution?
A:This is a common error in CGI, but it can have many causes. It can mean that your program actually doesn't exist, that it has the wrong permissions or is in the wrong place, or that the Content-type: header is not being sent correctly by the script.
Q:Can I include a JavaScript program in the output of a CGI program?
A:Yes. This can be useful for creating JavaScript programs based on data entered in a form.
Q:Aside from using a form, is there any other way to send data to a CGI program from JavaScript?
A:You could also send data in the URL. Use the escape() function to convert it, then add it to the CGI program's URL as a query using a question mark: prog.cgi?var1=John+Smith sends the name var1 and the value John Smith to the program. Set the location.href property to activate the script. CGI programs can also set cookie values you set using JavaScript.