 |
 |
|
Basic Applications · Two Small Programs · Content Negotiation · Redirection Manager · Generic Form Parser · Simple Parser · Customizable Parser (form.cgi) · Using form.cgi as a Guestbook · Summary You are now ready to begin the real learning process: programming useful CGI applications. In this and the other chapters in this section, the techniques and the CGI protocol from the first part of this book are demonstrated by developing and discussing real applications. This chapter begins with some very basic applications. Most of the examples are relatively small. The purpose is to show how you can apply your basic knowledge to perform powerful tasks. The chapter begins with two small programs written in Perl: a redirection manager and a content negotiation program. Finally, you move on to a larger application. You develop a generic program that parses any form and saves the content to a file, and then you extend it to perform flexible manipulation of the data. Two Small Programs In my two years developing Web sites and applications, I've found myself reusing some small, very simple CGI programs over and over again. Two small CGI programs are reproduced here: a redirection manager and a content negotiation application. These utilities are written in Perl to emphasize the CGI routines rather than the text processing routines; however, if you are running a heavily accessed server, you might want to rewrite these applications in C for more efficient responses.
Content Negotiation As an HTML author, you might want to use some of the unique HTML extensions certain browsers support; however, you might be afraid that the pages with extensions look bad on browsers that don't support those extensions. Or, you might have a graphics-heavy Web page, and you would like to send a text-only page to browsers such as lynx that don't support graphics. Ideally, you could write a program that would determine the capabilities of the browser and then send the appropriate page. This chapter shows a simple version of such a program called cn (which stands for content negotiation). Given the location and prefix of a document (index is the prefix of index.html, for example), cn does the following: · Checks to see what kind of HTML the browser supports · Sends the appropriate page In order to determine what the browser is capable of viewing, cn checks two environment variables: HTTP_ACCEPT and HTTP_USER_AGENT. If you recall from Chapter 5, "Input," HTTP_ACCEPT stores a list of MIME types the browser can view. You can use HTTP_ACCEPT to determine whether the browser is text-only or not by scanning the environment variable for the word image (as in image/gif or image/jpeg). If it finds this word, it assumes the browser is a graphical browser; otherwise, it assumes the browser is text-only. If the browser is graphical, cn then checks HTTP_USER_AGENT to determine the brand of the browser. This book primarily focuses on Netscape Navigator and Microsoft Internet Explorer. You can easily expand this program to fit your specific browser needs. Netscape and some versions of Internet Explorer store the word Mozilla in HTTP_USER_AGENT; other versions of Internet Explorer store Internet Explorer. After cn determines the browser type, it then tries to send the appropriate file. The proper HTML files are determined by filename extension. The default, global extension that cn will use if it cannot find any other files is .html. The other extensions are .thtml (for text HTML) and .mhtml (for Mozilla/Microsoft HTML, whatever suits your need). Cn reads the PATH_TRANSLATED environment variable to determine where to look for the files and what the filename prefix is. For example, suppose you have three different versions of the same HTML document: one standard document, one text-only document, and one that supports Mozilla/Microsoft extensions. The three filenames and locations are
/index.html In order to tell cn to send one of these three files according to browser type, you reference cn as follows: <a href="/cgi-bin/cn/index">Go to Index</a> Assume your document root is /usr/local/etc/httpd/htdocs/. When you click on the preceding link, you run cn with PATH_TRANSLATED /usr/local/etc/httpd/htdocs/index. Cn first checks the HTTP_ACCEPT variable to see if you have a text-only browser; if you do, it tries to send index.thtml. If you have a graphical browser, cn checks to see if you have either Netscape or Internet Explorer running. If you do, it tries to send index.mhtml. If cn can't find either index.thtml or index.mhtml, or if the browser is a non-Netscape/Microsoft graphical browser, cn tries to send index.html. If cn cannot find cn, it sends a File Not Found error message (status code 404). The following section summarizes the algorithm: · Check PATH_TRANSLATED for file location and prefix. If PATH_TRANSLATED isn't defined, send an error message. · Check HTTP_ACCEPT to see if the browser is text-only. If so, try to send filename.thtml. · If the browser is graphical, check to see if it is either Netscape or Internet Explorer. If it is either of these two, try to send filename.mhtml. · If the browser is none of these, or if cn fails to find either filename.thtml or filename.mhtml, cn should try and send filename.html. If it can't find filename.html, it should send an error message. The complete source code for cn is in Listing 10.1. ---------------------------------------------------- Listing 10.1. The cn source code.
#!/usr/local/bin/perl ------------------------------------------------- The Perl code for cn is about as straightforward as source code gets. All input was from environment variables. No parsing was necessary, so no external programming libraries such as cgi-lib.pl are needed. In order to send the appropriate HTML files, you could use the Location header rather than open the file. Opening the files yourself, however, enables you to check for the existence of files and then look for other files if the ones you wanted didn't already exist. Sending a Location header would have been inefficient because the server would have parsed the header and then once again checked to see whether the file existed or not, something cn had already determined. Redirection Manager Redirection operates similar to telephone call forwarding. With call forwarding, you dial a certain phone number that consequently dials and connects you to another phone number. If you restructure your Web site and move files around, you might want to specify a redirect for a file at its old location to its new location. For example, if the file mom.html moved from your document root to the directory /parents, you might want to redirect the request from the following: http://myserver.org/mom.html to: http://myserver.org/parents/mom.html A few options exist for you to handle this problem. You could create the file /mom.html with the following message:
<html> <head> Although this idea provides an adequate solution, it requires more maintenance and is not really the proper way to handle a redirect. To properly handle a redirect, you send a redirect status code and let the browser determine how to properly retrieve the file at its new location. Table 10.1. Redirect status codes.
When the browser receives a status code of 301 (Moved Permanently), it redirects all subsequent requests at the old URL to the new location. For example, if you request http://myserver.org/mom.html and receive a status code of 301 and the new location: http://myserver.org/parents/mom.html it will redirect the request to the latter location. The next time you try to access the first URL, the browser doesn't bother trying the old URL again; it instead directly accesses the new URL. Upon receipt of status code 302 (Moved Temporarily), the browser redirects only that one specific request; upon subsequent requests, it tries the original URL again. For example, suppose you request the following again: http://myserver.org/mom.html This time you receive a status code of 302 along with the new location: http://myserver.org/parents/mom.html It once again redirects your request to the latter location, but the next time you try to access the first URL, it once again tries to access the URL. Instead of creating a new HTML document that routes to the new URL, you send a status code and Location header to properly redirect a request. You can accomplish this task in two ways. You can configure many servers to redirect specific URLs. Although this has the advantage of very low overhead, your redirect options are limited. Some servers might only enable the Web administrator to configure redirections. Other servers might have limited configurability. For example, you cannot configure the NCSA server to send a status code of 301 instead of 302 with its Redirect feature.
The second way to accomplish a redirect is with a CGI program. Although this method is less efficient than having the server directly process the redirect request, a CGI program offers more flexibility. For example, you can write your CGI program so that users can configure their own redirections. Businesses that provide advertising space on their Web sites can use a redirection script to log every time someone clicks on an advertisement to go to another site. For example, suppose you have an advertisement for Mom and Pop's Candy Store . If you click on the advertisement, you go to Mom and Pop's Web site. Normally, the HTML document for such an advertisement might look something like Listing 10.2. Listing 10.2. advertisement.html.
<html> <head> Now it's time for you to collect your revenues from the candy store and attempt to renew your contract. Unfortunately, with the Web page in Listing 10.2, you have no way of knowing how many times people actually clicked on the advertisement to go to Mom and Pop's Web site.
If you had a program that updated an access file every time someone clicked on that link, and then redirected the person to the new site, you could keep track of how many people visited the site because of the advertisement on your Web page. The following list provides some specifications for a redirection manager: · It should enable people other than the site administrator to configure their own redirection. · It should flexibly enable you to specify either status code 301 or 302. · It should give the option of logging redirects. This procedure is called CGI program redirect. You can use redirect in two ways. You can either access the redirect program directly, passing its instructions through QUERY_STRING, or you can have your server call redirect every time it cannot find a document. For example, consider the preceding scenario. You want to log all accesses to Mom and Pop's Web site from the advertisement on your page. Instead of just specifying the URL in the <a href> tag, you could use redirect:
<a href="/cgi-bin/redirect?url=http://www.mnpcandy.
Now, every time someone clicks on
this advertisement, redirect would log the request to the To enable users to specify their own redirections without having access to any global configuration file, you need to configure your server to run the redirect program every time it cannot find a file. (See the following note for instructions on how to do this for the NCSA server.)
If the server cannot find a file, it will run the redirect program, which searches for a configuration file (.redirect) in the appropriate directory. The configuration file looks something like this:
LOGFILE=/var/logs/redirect.log LOGFILE specifies where to log requests. If this line is absent, then redirect will not log requests. STATUS contains the default status code for redirection. If STATUS is not specified, redirect assumes a status code of 302 (temporarily moved). Finally, the redirect command follows this form: document newlocation status Document is the old document relative to the document root, and newlocation contains the new location of the file. Note that unlike the Redirect option for NCSA servers, newlocation does not have to be a URL. Status is optional; if you include it, it will use that status code. It is time to begin coding. Figure 10.3 is a flowchart describing the program design. Two parts exist: one that handles redirects if called by the server, and the other that handles redirects specified in QUERY_STRING. Begin with the easier of the two tasks: the Perl code that will handle redirects if given some CGI input. The task is simple: · Check to make sure redirect is not being called by the server. (Do this by looking for the existence of the REDIRECT_URL environment variable.) · Parse the input for url and log. · If log is defined, log the request. · Send a redirect request to url. The code for this task is in Listing 10.3. The CGI input and output is straightforward. The ReadParse function parses the input. If no URL is specified, redirect sends an error message. If a log file is specified, redirect tries to append to the log file. If it can't append to the log file, it sends an error. If no errors occur, redirect sends a Status and Location header along with some HTML in case the browser does not properly handle redirects. ------------------------------------- Listing 10.3. Handling redirects specified in QUERY_STRING.
require 'cgi-lib.pl'; --------------------------------------------------- Now the second part of the program is added: user configurable redirections. The steps are as follows: · Check for REDIRECT_URL. · If it exists, parse it. · Look for the configuration file in the directory specified by REDIRECT_URL. · Parse the configuration file. · Take the appropriate action. Look at the second step for a moment. After you have the REDIRECT_URL, you need to determine where the directory is located. REDIRECT_URL tells you a relative directory in one of two forms:
/somedir/file.html You need to translate either of these two cases into the appropriate, full pathname. Translating the first case is fairly simple. Append the value of REDIRECT_URL to the value of the DOCUMENT_ROOT environment variable, and then remove the filename. If your document root were /usr/local/etc/httpd/, then /somedir/file.html would translate to /usr/local/etc/httpd/somedir/ The second possibility presents more of a challenge. You need to extract the username, determine where the user's home directory is, append the name of the public HTML directory to this home directory, and then append the rest of the directories. For example, if your home directory was in /home/username and the public HTML directory was in public_html, then /~username/somedir/file.html would translate into /home/username/public_html/somedir/ You can use the getpwnam() function to determine the home directory of the user. A CGI program cannot determine the name of the public HTML directory, so you can make that a user configurable item. The code to extract the directory from REDIRECT_URL is in Listing 10.4. -------------------------------------- Listing 10.4. Extracting directory information from REDIRECT_URL.
$public_html = '/public_html'; -------------------------------------------------- Now that you know where to look for a configuration file, you must open and parse that file. If it doesn't exist, then you just send a regular File not found error message (status code 404). If it does exist, parse it for the options listed earlier. The code for opening and parsing the file is in Listing 10.5. Listing 10.6 contains the function not_found, which sends the appropriate 404 error message. ---------------------------------------------- Listing 10.5. Parsing the configuration file.
if (-e $config_loc) { --------------------------------------------- Listing 10.6. List for File Not Found.
sub not_found { ------------------------------------------- You can now put together all of the code into one full-fledged application-redirect-listed in Listing 10.7. -------------------------------- Listing 10.7. Redirect-the finished application.
#!/usr/local/bin/perl -------------------------------------- The majority of redirect's source code is dedicated to determining where the configuration file is located and to parsing the file. Determining where the configuration file is located depends on your ability to manipulate the appropriate server variables. As usual, the CGI input and output routines seem almost trivial in this program; the real substance lies in determining how to take advantage of the environment variables and of parsing configuration files. Generic Form Parser One of CGI's most important contributions to the World Wide Web is its capability to collect input from the user. Although many CGI programs depend on this input to determine what to send back (for example, a search front-end to a database), perhaps the most basic use of CGI is to simply collect the information from the user and store it somewhere for the provider to look at later. You see these types of applications all over the Web, ranging from forms soliciting comments to online voting booths to guestbooks. You can reduce all of these applications to these steps: · Collect the input submitted via a form. · Store the input somewhere, perhaps for later processing. · Send confirmation of receipt. Instead of writing a separate application every time you need to collect data, you can write one generic forms parser that performs the preceding three steps. Such an application is developed here, starting with the most basic type of program and later extending it so that any user can easily configure it. "Gateways," extends the program further so that it e-mails the results rather than store the information on disk.
Simple Parser This section is a very specific application. You are conducting a poll over a controversial topic, and you want to collect people's choices and their ages and store these results in a comma-delimited file. Because the application is so specific, I hard code the form into the CGI application. The completed program in both Perl and C are in Listings 10.8 and 10.9. --------------------------------------------- Listing 10.8. The poll.cgi program (in Perl).
#!/usr/local/bin/perl ------------------------------------------- Listing 10.9. The poll.cgi program (in C).
#include <stdio.h> ---------------------------------
Both the Perl and C versions of poll.cgi consist mostly of printing the appropriate HTML. Obtaining and parsing the input is one line of code in both versions. In Perl: if (&ReadParse(*input)) { … } In C: if (read_cgi_input(&entries)) { … } Appending the results to a file is three lines. In Perl:
open(FILE,">>$file") || &CgiDie("Can't
Append to $file"); In C:
if ( (output = fopen(OUTPUT,"a"))
== NULL) { … } You could easily create this kind of program any time you need one. You want to avoid this kind of effort, however. Instead of having a separate program for each task, you want one program that parses input and saves it to a file. In order to achieve this result using poll.cgi as the basis for your code, you need to do the following: · Remove the built-in form. You want the program to work with any form, so having a built-in form probably is not very useful. · Allow the user to specify the filename and location for saving the information. · Save any and all values to the file. You can no longer assume that you have only two values labeled cola and age. To achieve the second step, allow the user to specify the filename and location via the PATH_INFO variable. The Perl and C source code for our simple but general forms parser are in Listings 10.10 and 10.11, respectively. -------------------------------------------- Listing 10.10. The parse-form program (in Perl).
#!/usr/local/bin/perl ------------------------------------------------ Listing 10.11. The parse-form program (in C).
#include <stdio.h> --------------------------------------------- To use parse-form, include it in the action parameter of your HTML form with the full pathname of the output file. For example, the following will save the results of the form, comma-delimited, in the /var/adm/results.txt file: <form action="/cgi-bin/parse-form/var/adm/results.txt"> The code is smaller, even though the program is more general because the built-in form has been removed. Even in its new, more general form, however, parse-form is still not quite satisfactory. First, the confirmation message is fairly unhelpful and ugly. You might want to send a custom message for each type of form. Second, the output file is somewhat unhelpful. The point of parsing the data before saving it to a file is to simplify the parsing. For example, with poll.cgi, it's easier to parse a file like the following:
coke,15 Here, because you know the variables, you can assume that you won't have any commas in the response, for example. You can make no such assumption in general, though. What if you had a form that asked for comments? People might use commas when they fill out their comments. You need to escape these commas so that a clear distinction exists between the delimiter and actual commas. If your data is very complex, then a comma-delimited file might not be easier to parse than a CGI-encoded one. Customizable Parser (form.cgi) Form.cgi solves the other parsers' problems. Form.cgi reads a configuration file (either defined by PATH_INFO or the predefined default) and does the following: · Sends a customized HTML form if no input exists. · If there is input, writes to an output file in a format specified by a template file. Both files are defined in the configuration file. · Sends either a standard response or a customized response. Because form.cgi requires some amount of text processing and because this text focuses on the algorithm rather than the programming implementation, form.cgi is written in Perl. You might already have Perl code for reading and parsing a configuration file from the redirection manager. This code has been adapted to read a configuration file that looks like the following:
FORM=/form.html FORM and RESPONSE define HTML documents relative to the document root. The TEMPLATE and OUTPUT variables contain full pathnames to the template. If you do not define it in the configuration file, then form.cgi sends the same response as parse-form. The code for parsing the configuration file appears in Listing 10.12. This code will ignore any other line not in the specified form. -------------------------------------- Listing 10.12. Parsing the configuration file.
$global_config = '/usr/local/etc/httpd/conf/form.conf';
------------------------------------------ The template file tells form.cgi the format of the output file. In order to specify the form values, you precede the field name with a dollar sign ($). For example, the template for a comma-delimited output file for the cola poll would look like the following: $cola,$age The input name must be only one word and consist entirely of alphanumeric characters. This example also has the capability to write the values of CGI environment variables to the file. To add this capability, you specify the environment variable name preceded by a percent symbol (%). For example, if you want to label each line of your cola poll's output file with the name of the machine where the browser resides, you would use the template file: %REMOTE_HOST $cola,$age If you want to just print a dollar sign or percent symbol, precede the symbol with a backslash (/). In order to print a backslash, precede the backslash with a backslash to print two backslashes (//). How do you implement this? After you have read and parsed the form input, you need to read the template file and parse each line, replacing any variables with the appropriate form values. The code for this process appears in Listing 10.13. ------------------------------------------- Listing 10.13. Use template to define output file format.
# read template into list --------------------------------------------- Putting all of the code together results in form.cgi as listed in Listing 10.14. Form.cgi seems to overcome all of the shortcomings of the previous attempts at a general, generic form parser. It serves as a customizable, robust application that will probably save you a great deal of time. ---------------------------------------------- Listing 10.14. The form.cgi program.
#!/usr/local/bin/perl ------------------------------------------------ Using form.cgi as a Guestbook You can use form.cgi as a very primitive guestbook. To do so, you need to create a configuration file, a form and a response HTML file, and a template file that describes the format of the guestbook. Assume the following specifications: · The document root is /usr/local/etc/httpd/htdocs/. · The add form is add.html (see Listing 10.15) and the response is thanks.html (see Listing 10.16). Both are in document root. · The configuration and template files are in /usr/local/etc/httpd/conf/guestbook.conf (see Listing 10.17) and /usr/local/etc/httpd/conf/guestbook.template (see Listing 10.18), respectively. · The guestbook is in /usr/local/etc/httpd/htdocs/guestbook.html. -------------------------------------------- Listing 10.15. The add.html program.
<html><head> ----------------------------------------------- Listing 10.16. The thanks.html program.
<html><head> ------------------------------------------------ Listing 10.17. The guestbook.conf program.
FORM=/add.html -------------------------------------------------- Listing 10.18. The guestbook.template program.
<p><b>From <a href="$url">$name</a>
<a href="mailto:$email">$email</a></p> ------------------------------------------------- By creating the text files in Listings 10.15 through 18, you have created a guestbook without one extra line of CGI programming. Remember, however, that you have a very rudimentary guestbook, lacking features such as date-stamping and filtering greater than (>) and less than (<) symbols. "Programming Strategies," are superior to this primitive example. Regardless, form.cgi can save the CGI developer a great deal of time. Summary The examples in this chapter were minimalistic as far as CGI programs go. The complexity came in manipulating CGI environment variables, in parsing input, and in sending output. All other routines either read and wrote data to a file, or they manipulated text. The applications in this chapter-the content negotiator, the redirection manager, and the form parser-as well as the techniques applied, are enough to cover the majority of CGI programs that most people will ever need to write. The remainder of this book focuses on more specialized, advanced applications. |
