CS151 2001S : CGI Scripting in Scheme

As you may know, it is possible to write programs that generate Web pages in response to user input (often entered on other Web pages). The most common mechanism for writing such programs is CGI, which stands for common gateway interface. It is possible to write CGI programs (usually called "scripts") in almost any programming language, including Scheme.

Here's how CGI typically works. The user enters information on a form (simply an HTML page with some special tags). When the user clicks on the Submit button (or something similar) the browsers packages up all the information and sends it to the server. The server then unpackages the information and passes it on to the CGI script. The CGI script looks at the information and generates a page and passes the page back to the server. The server passes the page back to the browser, and everyone is happy. So, what do you need to learn? You already know how to write Scheme to generate an HTML page (or you should if you did the strings lab). So, you have to learn how to get information from the server, tell the server to run your program from a CGI script, and build the HTML page that lets someone enter information.

I've set up some helper programs that make it easier (but not necessarily easy) for you to write CGI scripts in Scheme. I also recommend that you follow a standard process when building your scripts.

The Basic Steps

Here are the steps that I recommend that you undertake when writing a CGI script.

Stage One: Prepare a Scheme Procedure

Stage Two: Extend Scheme File

Now you need to extend the file so that it works with the CGI system (in terms of getting input from the CGI system and working when called from the CGI system). The way I've set up my CGI gateway, it always calls a procedure named page that has no parameters.

Stage Three: Build CGI Wrapper

Now it's time to build something that ties your Scheme program to the CGI system.

Stage Four: Build HTML Interface

Stage Five: Put it all together

A Sample Procedure

Here is a Scheme procedure that generates a greeting page based on an input name. It assumes that you've written some helper procedures similar to those from the strings lab.

;;; Procedure
;;;   greeting-page
;;; Parameters:
;;;   user, a string that represents the name of a user
;;; Purpose:
;;;   Generates an HTML page that can greet the named person.
;;; Produces:
;;;   A string that corresponds to that page.
;;; Preconditions:
;;;   The string must be nonempty.
;;; Postconditions:
;;;   The returned page is valid HTML.
(define greeting-page
  (lambda (user)
    (make-page 
      (head "Greetings")
      (body (string-append
              (heading 1 "Welcome")
              (string #\newline)
              (paragraph (string-append "Hi " user "!")))))))

HTML Forms

As mentioned above, a form is simply some HTML that lets the user enter some input and ties that input to a CGI script. (Forms can do other things, too, but this purpose is enough for now).

As you might expect, you surround a form with form tags. The opening tag must also include two parameters:

<form method="get" action="greeting.cgi">
...
</form>

You can include normal HTML in a form. Normal HTML is displayed normally and is not uploaded to the server when the user submits values. Rather, it is used to give some information to the user about where things might go.

When you want the user to type a value, you use an input tag with the following parameters:

<input type="text" name="user" value="">

You should also provide a handy-dandy "Click Here" button. Once again, you use an input tag. This time, you use slightly different parameters:

<input type="submit" value="Enter your name and click here!">

That's it, you know the basics. If you want things other than fields in your forms, ask me about them in class or look them up on the Web.

Sample Code

;;; File:
;;;   greeting.ss
;;; Version:
;;;   1.0 of February 2001
;;; Author:
;;;   Samuel A. Rebelsky
;;; Contents:
;;;   A simple example of some Scheme procedures for CGI
;;; Organization:
;;;   Preparation - Stuff I need to do to get started
;;;   Sam's HTML Helpers - Procedures for generating HTML
;;;   Page Generators - Procedures for generating specific kinds of
;;;     pages (when given particular values)
;;;   Interface - Stuff to extract important values and then
;;;     call the page generators.  You'll find (page) here.

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; Preparation

;;; Look!  We're going to use the CGI library.  What fun.
(require-library "cgi.ss" "net")

;;; Are we testing?
(define testing #f)

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; Sam's HTML Helpers

;;; Procedure:
;;;   markup
;;; Parameters:
;;;   text, some text to mark up
;;;   tag, the role that the text plays
;;; Purpose:
;;;   Generates some nice happy HTML for me.
;;; Produces:
;;;   A string for HTML that represents the marked text.
;;; Preconditions:
;;;   Both parameters are strings.
;;;   The text is valid HTML.
;;;   The tag contains only alphanumeric characters and 
;;;     corresponds to a valid HTML tag.
;;; Postconditions:
;;;   You get some nice HTML.
(define markup 
  (lambda (text tag)
    (string-append "<" tag ">" text "</" tag ">")))

;;; Procedure:
;;;   heading
;;; Parameters:
;;;   level, a heading level (1-6)
;;;   text, some text to mark up
;;; Purpose:
;;;   Generates some nice happy HTML that represents the heading of
;;;   a section of text.
;;; Produces:
;;;   A string for HTML that represents the heading.
;;; Preconditions:
;;;   Level is an exact integer between 1 and 6, inclusive.
;;;   text is a string.
;;;   text is valid HTML.
;;; Postconditions:
;;;   You get some nice HTML which a normal browser displays
;;;   as a heading.
(define heading
  (lambda (level text)
    (markup text (string-append "h" (number->string level)))))

;;; Procedure:
;;;   head
;;; Parameters:
;;;   title, the title of the page
;;; Purpose:
;;;   Generates some nice happy HTML that represents the head of
;;;   a page with a particular title.
;;; Produces:
;;;   A string for HTML that represents the head.
;;; Preconditions:
;;;   The title is a string with no internal HTML.
;;; Postconditions:
;;;   You get some nice HTML which a normal browser displays
;;;   as the titlebar of a window.
(define head
  (lambda (title)
    (markup (markup title "title") "head")))

;;; Procedure:
;;;   body
;;; Parameters:
;;;   contents, the intended contents of a page
;;; Purpose:
;;;   Generates some nice happy HTML that represents the body of
;;;   a page with a particular contents.
;;; Produces:
;;;   A string for HTML that represents the body.
;;; Preconditions:
;;;   contents is a string
;;;   contents represents valid, though partial, HTML
;;; Postconditions:
;;;   You get some nice HTML which you can join with a
;;;     head and some html tags to make a full page.
;;;   The result may contain carriage returns (newlines).
(define body
  (lambda (contents)
    (markup (string-append (string #\newline)
                           contents 
                           (string #\newline))
            "body")))

;;; Procedure:
;;;   paragraph
;;; Parameters:
;;;   contents, the contents of the paragraph
;;; Purpose:
;;;   Generates some nice happy HTML that represents on paragraph.
;;;   Also to annoy the world with introductory comments that are
;;;     significantly longer than the procedure needs.
;;; Produces:
;;;   A string for HTML that represents the paragraph.
;;; Preconditions:
;;;   The contents is (are?) valid HTML with no block-level elements.
;;; Postconditions:
;;;   You get some nice HTML which a normal browser displays
;;;   appropriately.
(define paragraph
  (lambda (contents)
    (markup contents "p")))

;;; Procedure:
;;;   paragraph
;;; Parameters:
;;;   head, the head of a page
;;;   body, the body of a page
;;; Purpose:
;;;   Shoves the head and the body together to make a page.
;;; Produces:
;;;   HTML for a full page.  Wow!
;;; Preconditions:
;;;   head was created by the head procedure
;;;   body was created by the body procedure
;;; Postconditions:
;;;   You get some nice HTML which a normal browser displays
;;;   appropriately.
(define make-page
  (lambda (head body)
    (markup (string-append (string #\newline)
                           head
                           (string #\newline)
                           body
                           (string #\newline))
            "html")))

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; Page Generators

;;; Procedure
;;;   greeting-page
;;; Parameters:
;;;   name, a string
;;; Purpose:
;;;   Generates an HTML page that can greet the named person.
;;; Produces:
;;;   A string that corresponds to that page.
;;; Preconditions:
;;;   The string must be nonempty.
;;; Postconditions:
;;;   The returned page is valid HTML.
(define greeting-page
  (lambda (name)
    (make-page 
      (head "Greetings")
      (body (string-append
              (heading 1 "Welcome")
              (string #\newline)
              (paragraph (string-append "Hi " name "!")))))))

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
;;; Interface


;;; Value:
;;;   user
;;; Purpose:
;;;   Names the user.  Intended as input for greeting-page.
(define user 
  (if testing "Sam"
      (extract-binding/single 'user (get-bindings))))

;;; Procedure:
;;;   page
;;; Parameters:
;;;   None
;;; Purpose:
;;;   Builds an HTML page according to specifications.
;;; Produces:
;;;   A string that corresponds to the HTML page.
;;; Preconditions:
;;;   Variable "user" must be defined.
;;;   greeting-page must be definedk, take one parameter, and generate a page.
;;; Postconditions:
;;;   The returned page is as valid as anything greeting-page produces.
(define page
  (lambda ()
    (greeting-page user)))