These notes give some implementation details about the web server
that's part of the Dr Scheme distribution.  There is help for the Web
Server in the Help Desk, but it's a bit difficult to figure out.  You
may find it easier to work from examples, and from these notes giving
an overview of how things work.

GETTING STARTED.

The web server itself is located in the PLT distribution.  For example
on a PC the PLT distribution shows up as 

C:\Program Files\PLT

You can run "PLT Web Server" or "PLT Web Server Text" - in either case
just by clicking on them.

There are a bunch of sample programs available with the web server.
You can find the possibilities in the PLT distribution at

collects/web-server/default-web-root/servlets/examples

One example there is "hello.ss".  In order to view this in the
browser, use the URL

http://localhost/servlets/examples/hello.ss

Another example you might look at is "add.ss".  This is the staged
addition program we looked at in class.

SIMPLE WAYS OF USING INFORMATION.

The Scheme code that runs on the browser to handle the requests for a
specific page is called a servlet.  In Scheme there are three things
that you have do to create a servlet.  

First you have to create a scheme file somewhere in the
default-web-root hierarchy so that the PLT web server will access it.
The examples directory is as good a place as any.  (Actually you can
adjust the configuration of the PLT web server to serve other
documents but if you are capable of figuring out how to do this, you
can probably figure this all out for yourself.)

Second, you have to start this file with the magical incantation that
makes available all of the infrastructure routines that you will want
to use in making a servlet, and that defines the interfaces that the
web server will use to access the code in the servlet.  This magical
incantation is:

(require (lib "unitsig.ss")
         (lib "servlet-sig.ss" "web-server"))

Third, you have to embed all your code in a declaration saying that
you're defining a particular servlet with this file.  This declaration
is this:

(unit/sig 
 () (import servlet^)

 ; your code here
)

Now, when the servlet is called, the variable "initial-request" will
be defined.  This is a data structure in Scheme that describes what
information was sent to the server as part of activating this page.
One thing that is included is a set of bindings or associations
between variables and values.  These can be supplied to the web server
either through the GET method or the POST method.  The POST method is
often easier to use when calling one web page from another, because
the user doesn't see horrendous looking information on the command
line, but the GET method is the only method that allows you to play
with creating new requests yourself.  In the GET method, the URL
specifies parameters to the web page with the syntax 

URL?variable1=value1&variable2=value2

(Note that spaces are not allowed so there is some encoding that
happens with the GET method.  This happens automatically if you use
forms.)  This request gets translated into bindings that associate
variable1 with the value value1 and variable2 with the value value2.

To access the bindings of the initial request, use the Scheme
expression:

(request-bindings initial-request)

To see whether a value is defined for symbol VARIABLE in BINDINGS use

(exists-binding? VARIABLE BINDINGS)

To safely get the first value for variable when exists-binding?
returns TRUE, do

(car (extract-bindings VARIABLE BINDINGS))

This indirection is because bindings are allowed to store multiple
values for variables, and extract-bindings returns the LIST of all
values assigned, and you only want the first one.

Here is simple sample code that examines the passed environment to
make sure that the relevant values are set and then constructs a new
web page using those values.

  (let ((my-bindings (request-bindings initial-request)))
    (cond [(not (exists-binding? 'q my-bindings))
           '(html (head (title "Error"))
                  (body ((bgcolor "red"))
                        (p "This page needs you to define q!")))]
          [(not (exists-binding? 'r my-bindings))
           '(html (head (title "Error"))
                  (body ((bgcolor "blue"))
                        (p "This page needs you to define r!")))]
          [else
           (let ((q (car (extract-bindings 'q my-bindings)))
                 (r (car (extract-bindings 'r my-bindings))))
             `(html (head (title "Relationships"))
                  (body ([bgcolor "white"])
                        (p "Every "
                           ,q
                           " is a "
                           ,r
                           "."))))]))

It should be pretty self-explanatory.

FIXING BUGS.

Avoid debugging things in the browser.  The server's behavior and the
browser's behavior when you have bad HTML may not be what you expect.
And you don't get to see the HTML.  Debug the HTML construction in a
regular Scheme file first, using the typical Dr Scheme interaction, to
make sure behavior is what you expect, before you go live on a site.

By default, error messages appear in the output window of the web
server program, e.g., on windows, the CMD window created when you
click on PLT Web Server Text.exe.  You can fix this by adding this
line to the top of your servlet code

  (report-errors-to-browser send/finish)

Servlet code is loaded into the server the first time a page is
accessed.  The server then maintains a copy of that code.  If you find
a bug in the servlet or want to make any other change, you have to
instruct the server to reload the servlet from disk.  You do that by
accessing the page

http://localhost/conf/refresh-servlets