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 guide about JavaScript, this chapter doesn't
go into detail about CGI -it's complicated enough to have merited
a few guides 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 guides 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
|
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:
- JavaScript executes on the client (like Java), and CGI executes
on the server.
- CGI returns an entire document, and JavaScript may act on
a tiny part of the page, such as a text field or the status line.
- CGI has access to information, such as the user's IP address,
which JavaScript cannot access.
- JavaScript has access to information that CGI can't access-the
links and anchors in the current page, for example.
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:
- My CGI version has about 20,000 quotes available, all stored
in a database on the server. This wouldn't be practical with JavaScript,
because all the possible quotations would have to be loaded with
the Web page.
- The JavaScript version is much, much faster, and it places
no more load on the server than an ordinary Web page.
- The CGI version requires a server that supports CGI, access
to it, and available disk space-things a low-priced Internet account
may not provide. The JavaScript version, on the other hand, works
even without a server-for example, you can load the file directly
from the CD-ROM included with this guide.
- The CGI version will work with any browser, but the JavaScript
version requires Netscape, MSIE, or another JavaScript-compatible
browser.
- If the quotation was displayed in a text field, the JavaScript
version could update it at the touch of a button, without even
reloading the page. CGI can't update part of a page.
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.
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:
- You can access it directly with an URL. The URL will often
end in .cgi or .pl, although this is not a requirement.
- You can press the SUBMIT button on an HTML form. This sends
the data you have entered in the form's elements to the CGI program
on the server.
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.
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:
- The GET method sends data in the URL itself. If you
enter the URL of a CGI program directly, you are accessing it
with the GET method. Forms can also use this method.
- The POST method sends data in a stream (standard
input) after the request. This method enables larger amounts of
data to be sent. The POST method is used exclusively
by 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:
- ACTION specifies the URL of the CGI program that
will receive the data when the SUBMIT button is pressed. You can
also specify a mailto action here.
- METHOD specifies the request method and can be either
GET or POST. Your CGI program will need to read
the data using the same method.
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.
|
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:
- For the GET method, the data is stored in an environmental
variable called QUERY_STRING.
- For the POST method, the data is sent via the standard
input.
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:
- The escape() function converts a string to URL-encoded
form.
- The unescape() function converts a URL-encoded string
to normal text.
With either function, simply use the text to be converted as the
function's parameter.
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:
- SERVER_SOFTWARE is the version of the Web server
in use.
- REMOTE_ADDR is the user's IP address.
- REMOTE_HOST is the user's host name.
- REQUEST_METHOD is the form's method, either GET
or POST.
- QUERY_STRING is used to store the name/value pairs
if the GET method is used.
- HTTP_USER_AGENT is the name of the browser the user
is using (similar to JavaScript's Navigator object).
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.
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/guides/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.
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.
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:
- echo displays the value of an environmental variable.
- include adds the contents of another HTML document
to the current document.
- fsize displays the size of a file; this is handy
for images or downloadable programs.
- fLastMod displays the last-modified date for the
current page.
- exec executes a CGI program.
- email sends an e-mail message.
- if enables you to include different text depending
on the contents of a variable.
- goto, label, and break enable you
to transfer control within a page.
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:
- Use a command in the server's configuration file, or a local
.htaccess file, to enable server-side includes.
- Make the HTML document executable, as with the UNIX command
chmod o+x document.
- Consult your administrator to see whether the feature is available
for your documents.
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 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 guides 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 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.
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.
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.
|
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:
- 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.
- 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.
- 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.
- Determine the URL for the program. This will depend on your
server's configuration and the directory in which you have placed
the program.
- 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.
|
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.asp) 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.
In this chapter you learned about CGI and SSI, and how they can
work with JavaScript:
- The basics of the CGI specification
- The environmental variables and name/value pairs sent to a
CGI program
- The basics of the SSI specification
- How to write a simple CGI program and install it on the server
- How to use SSI and JavaScript together to expand JavaScript's
capabilities
Move on with one of the following:
- To learn to use JavaScript to validate a form before sending
it to a CGI program, see Chapter 6 "Using Interactive Forms."
- To learn about another Web language-Java-and how it can work
with JavaScript, see Chapter 16, "Integrating JavaScript
with Java."
- To see examples of the techniques in this chapter, see Chapter
19, "Real-life Examples IV."
- To learn how JavaScript's capabilities may improve in the
future, see Chapter 20, "The Future of JavaScript."
| 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.
|
|
Learn HTML
