sunet/doc/latex/surfletapi.tex

\section{API description}
\label{sec:surflet-api}

The \surflet server comes with an extensive set of modules.  This
section describes the modules and the programming interfaces.  See the
howto section \ref{sec:surflethowto} for a practical guide.  Note that
most of the procedures mentioned here are meant to be called from
within a \surflet.


\subsection{The \surflet server}

The \surflet server provides basic procedures to send web content to a
client.  To enable the SUnet webserver to serve \surflets, you have to
add the \surflet handler to it, which resides in the
\exi{surflet-handler} structure.  \Eg:

\begin{alltt}
(httpd 
  (make-httpd-options
   \dots
   with-request-handler 
   (alist-path-dispatcher
    (list
     (cons "surflet" (surflet-handler (with-surflet-path 
                                       "web-server/root/surflets"))))
     (rooted-file-or-directory-handler "web-server/root/htdocs"))))
\end{alltt}

This will set up the \surflet handler to handle requests directed to
the directory \ex{/surflet/}.  The \surflet handler can only handle
requests directed to \surflets.  Here's the interface description:

\defun{surflet-handler}{options}{request-handler}
\begin{desc}
  This procedures sets up the \surflet handler and returns the request
  handler for the SUnet webserver.  The options argument is similar to
  the one passed to \ex{httpd} and is exlpained below.

  The \surflet handler accepts requests (solely) to \surflets whose
  file name must have the extension \ex{.scm}.  The structure of
  \surflets is explained below.  The \surflet handler receives the
  \ex{request} from \ex{httpd}, translates it to a
  \ex{surflet-request} and passes it to the requested \surflet.  The
  \surflet in turn is expected to return a \ex{surflet-response},
  which the \surflet handler translates to a \ex{repsonse} for
  \ex{httpd}.  Thus, the \surflet deals only with \ex{surflet-request}
  and \ex{surflet-response} objects.  The structure of these objects
  and how they are passed around is explained below.

  A \surflet may also return a \ex{redirect} \ex{response}, which the
  \surflet handler passes to the \ex{httpd} untouched.  See
  \ref{sec:http-responses} for details.

  The \surflet handler calls the \surflet wrapped into an error
  handler that catches any error the \surflet may yield.  In this
  case, it terminates the \surflets session (see below for more on
  sessions) and returns an \ex{error} \ex{response} to \ex{httpd} with
  the error code 500 "Internal Server Error" and a description of
  the error.
\end{desc}

The \var{options} argument can be constructed in a similar way to the
options argument of \ex{httpd}.  The procedures' names are of the form
\ex{with-\ldots} and they all either create a new option or add a
new parameter to a given option.  The new parameter is always the
first argument while the (old) option the optional second one.  The
following procedures reside in the  \exi{surflet-handler/options}
structure.

\defun{with-surflet-path}{surflet-path [options]}{options}
\begin{desc}
  This specifies the path in which the \surflet handler looks for
  \surflets.  The \var{surflet-path} is a string.  This option must be
  given for the handler to work.
\end{desc}

\defun{with-session-lifetime}{seconds [options]}{options}
\begin{desc}
  This specifies the initial lifetime of a session.  The lifetime of a
  session is the number of seconds the \surflet handler waits for a
  response from a client for that session, before she automatically
  finishes it.  See below for details on sessions.  Defaults to 600,
  \ie 10 minutes.
\end{desc}

\defun{with-cache-surflets?}{cache-surflets? [options]}{options}
\begin{desc}
  This specifices whether the \surflet handler caches \surflets.  The
  caching of \surflets is a prerequisite for \surflet wide global
  variables.  See below for details on the scope of variables in
  \surflets.  Defaults to \sharpt.
\end{desc}

\defun{with-make-session-timeout-text}{timeout-text-procedure
  [options]}{options}
\begin{desc}
  This specifies a procedure that generates the timeout text.  The
  \surflet handler displays the timeout text when she receives a
  request for a \surflet session that does not exist, either because
  the \surflet finished its session, the session has timed out, or the
  URL is illformed.  The default is an English text with an
  explanation of the possible reasons and a link to a new session of
  the requested \surflet.  \var{timeout-text-procedure} accepts the
  string path to the \surflet that was requested and returns a string.
\end{desc}

Similar to the \ex{httpd} options there exists a procedure to avoid
parenthisis:

\defun{make-surflet-options} {transformer value \ldots}{options}
\begin{desc}
  This constructs an options value from an argument list of parameter
  transformers and parameter values.  The arguments come in pairs,
  each an option transformer from the list above, and a value for that
  parameter. \ex{make-surflet-options} returns the resulting options
  value.
\end{desc}

For example,

\begin{alltt}
(surflet-handler 
  (make-surflet-options
   with-surflet-path "root/surflets"
   with-session-timeout 3600))
\end{alltt}

defines the \surflet handler to serve \surflets from the directory
\ex{root/surflets} and to timeout unused session after one hour.

The \surflet handler allows runtime read and write access to her
options:

\defun{options-surflet-path}{options}{string}
\defunx{options-session-lifetime}{options}{integer}
\defunx{options-cache-surflets?}{options}{boolean}
\defunx{options-make-session-timeout-text}{options}{procedure}
\begin{desc}
  These procedures return the stored value for the respective option.
  See above for the description of the options.
\end{desc}

\defun{set-options-surflet-path!}{options surflet-path}{\undefined}
\defunx{set-options-session-lifetime!}{options seconds}{\undefined}
\defunx{set-options-cache-surflets?!}{options cache-surflets?}{\undefined}
\defunx{set-options-make-session-timeout-text!}
       {options timeout-text-procedure} {\undefined}
\begin{desc}
  These procedures change the respective option value.  See above for
  the description of the arguments.  Note that changing the
  \var{surflet-path} within a \surflet may result in the \surflets
  being unreachable.  Turning the cache off will not empty the
  \surflet cache.
\end{desc}


\subsection{\surflets}

Technically, \surflets are Scheme48 structures, that have the name
\ex{surflet} and export a \ex{main} procedure.  The file in which their
definition reside must have the extension \ex{.scm}.  The \ex{main}
procedure must accept the initial \ex{surflet-request} as an argument.
She may or may not return, but if she does, she must return either a
\ex{surflet response} or a \ex{redirect response}.  For example, this
is a valid \surflet definition:

\begin{alltt}
(define-structure surflet surflet-interface
  (open scheme-with-scsh
        surflets)
  (begin
    (define (main req)
       (send-html/finish
         '(html (body (p "Hello world!")))))
))
\end{alltt}

\ex{surflet-interface} is a predefined interface description that
exports the \ex{main} procedure.  It is recommended to use this
interface.  \exi{surflets} is a structure that combines the most
commonly used structures to write \surflets.  \ex{send-html/finish} is
one of the procedures that sends HTML to the client.  More on this
below.

As \surflets are Scheme48 structures, you can use all capabilities of
the Scheme48 module language.  See the documentation of Scheme48 for
details.

\surflets should not use the \ex{shift-reset} structure, as this might
confuse the \surflet handler. 

\subsection{\surflet management}

Upon an initial client request, the \surflet handler looks for the
requested \surflet, dynamically loads it, installs an error handler
and calls the \ex{main} function of the \surflet with the initial
\ex{surflet-request}.   To minimize the time of loading a \surflet,
the \surflet handler caches the structure of the \surflet in a cache,
the \surflet cache.  As the \surflet is cached, its global values will
remain unchanged even through times when there are no active sessions
of the \surflet.  Changing global \surflet values is a possibility to
exchange data between different sessions of the same \surflet.  Note
that you have to take care to serialize the access to commonly shared,
mutated data.

The \surflet handler allows access to its cache via the following
procedures.  The access to these procedures is currently
unrestricted but may be restricted in future versions of the
\surflet server.

\defun{get-loaded-surflets}{}{list}
\begin{desc}
  This returns a list of the file names of the loaded \surflets. 
\end{desc}

\defun{unload-surflet}{surflet}{undefined}
\begin{desc}
  This removes the \var{surflet} from the \surflet cache.  The
  \var{surflet} is identified by its file name, as returned from
  \ex{get-loaded-surflets}.
\end{desc}

\defun{reset-surflet-cache!}{}{undefined}
\begin{desc}
  This empties the \surflet cache.
\end{desc}

Of course, when a \surflet is removed from the cache, the values in
its sessions remain untouched.  However, if the \surflet is newly
loaded into the \surflet cache, the \surflet handler treats it like a
new \surflet, \ie the sessions of the "old" and the "new" \surflet
(though physically the same) do \emph{not} share their global data in
any way.

\subsection{Surflet Request}

\surflets get their input from \ex{surflet-request} objects.   The
relevant procedures are the following.  They are all exported by the
\exi{surflet-handler/requests} alias \exi{surflet-requests} structure.

\defun{surflet-request?}{object}{boolean}
\defunx{surflet-request-method}{surflet-request}{string}
\defunx{surflet-request-input-port}{surflet-request}{input-port/undefined}
\defunx{surflet-request-uri}{surflet-request}{string}
\defunx{surflet-request-url}{surflet-request}{url}
\defunx{surflet-request-version}{surflet-request}{pair}
\defunx{surflet-request-headers}{surflet-request}{alist}
\begin{desc}
  The procedures inspect \ex{surflet-request} values.  Most of them
  return the values of the underlying \ex{request} object from
  \ex{httpd}.  \ex{surflet-request?} is a predicate for \ex{surflet
  request}s.  \ex{surflet-request-method} extracts the method of the
  HTTP request; it's a string and either \ex{"GET"} or \ex{"POST"}.
  \surflets won't receive requests with other methods.
  \ex{surflet-request-input-port} returns an input-port that contains
  data from the client on \ex{POST} requests and that the \surflet can
  safely read.  If the request is no \ex{POST} request, its value is
  undefined.  \ex{surflet-request-uri} returns the escaped URI string
  as read from the request line.  \ex{surflet-request-url} returns the
  respective HTTP URL value (see the description of the \ex{url}
  structure in chapter \ref{cha:url}).  \ex{surflet-request-version}
  returns a \verb|(major . minor)| integer pair representing the
  version specified in the HTTP request.  \ex{surflet-request-headers}
  returns an association lists of header field names and their values,
  each represented by a list of strings, one for each line.
\end{desc}

For some unknown weird cases, there are also these two procedures:

\defun{surflet-request-socket}{surflet-request}{socket}
\defunx{surflet-request-request}{surflet-request}{request}
\begin{desc}
  \ex{surflet-request-socket} returns the socket connected to the
  client.  As with \ex{request}s, \surflets should not perform I/O on
  this socket.  See section \ref{httpd:requests} for reasoning.
  \ex{surflet-request-requst} allows access to the underlying
  \ex{request} object from \ex{httpd}.  Both procedures should not be
  necessary in normal operation and their usage is discouraged.
\end{desc}


\subsection{Surflet Response}

\surflets answer to a request by sending an \ex{surflet-response} to
the \surflet handler.  The next section deals with how the surflet
responses are sent to the \surflet handler.  The relevant procedures
for \ex{surflet-response} are the following.  They are all exported by
the \exi{surflet-handler/responses} alias \exi{surflet-response}
structure.

\defun{make-surflet-response}{status content-type headers
  data}{surflet-response}
\begin{desc}
  This creates a \ex{surflet-response}.  \var{status} is the status
  code of the response.  See section \ref{sec:http-responses} for
  details on this.  \var{content-type} is the MIME type of the data,
  \eg \ex{"text/html"}.  \var{headers} is an association list of
  headers to be added to the response, each of which consists of a
  symbol representing the field name and a string representing the
  field value.  \var{data} is the actual data.  It must be either a
  string or a list of values that will be \ex{display}ed.
\end{desc}

\defun{valid-surflet-response-data?}{object}{boolean}
\begin{desc}
  This is a predicate on objects that may be surflet data, \ie a
  string or a list (of objects that will be \ex{display}ed).
\end{desc}

\defun{surflet-response?}{object}{boolean}
\defunx{surflet-response-status}{surflet-response}{status-code}
\defunx{surflet-response-content-type}{surflet-response}{string}
\defunx{surflet-response-headers}{surflet-response}{alist}
\defunx{surflet-response-data}{surflet-response}{surflet-data}
\begin{desc}
  The procedures return \ex{surflet-response} values.
  \ex{surflet-response?} is a predicate for \ex{surflet-response}s.
  \ex{surflet-response-status} returns the status code of the
  response.  See section \ref{sec:http-responses} for details on the
  status code.  \ex{surflet-response-content-type} returns the MIME
  type of the response.  \ex{surflet-response-headers} returns the
  association list of header field names and their values, each
  represented by a list of strings, one for each line.
  \ex{surflet-response-data} returns the data of the
  \ex{surflet-response}, the actual answer of the \surflet.
\end{desc}

\subsection{Sessions}

A \keyword{session} is a set of web pages that logically belong
together, \eg a user surfing through her webmail.  A session starts
with the initial request for a \surflet and ends either explicitly by
the \surflet, or implicitly after a timeout.  A third, not so common
case is its deletion from the session table.

The procedures presented in this subsection are all accessible via the
\exi{surflets/sessions} structure.

\subsubsection{Session management}

The \surflet handler automatically manages the sessions for each
\surflet, thus the \surflet does not have to deal with sessions or
state control (as it is the case with most other programming
interfaces for web applications).  In particular, a \surflet does not
have to take care of saving the contents of variables before emitting
a web page and restoring the values later upon the next request, or
determining how far the user has proceeded in the application.  The
only thing a \surflet may want to do is to tell the \surflet handler
when a session finished by calling \ex{send/finish} or an equivalent
procedure (see below).

Although a \surflet does not have to deal with the management of the
sessions, the \surflet handler allows access to its management
structures.

\defun{instance-session-id}{}{session-id}
\begin{desc}
  This returns the session ID for the current session.  The current
  session is the session from which the function is called.
\end{desc}

\defun{get-session}{session-id}{session}
\begin{desc}
  This returns the session for the given session ID.
\end{desc}

\defun{get-sessions}{}{alist}
\begin{desc}
  This returns the complete list of all active session of the \surflet
  handler.  The list is an association list with the session-id as key
  and the session as value.

  The access to this procedure is currently unrestricted but may be
  restricted in future versions of the \surflet server.
\end{desc}

\defun{delete-session!}{session}{undefined}
\begin{desc}
  This deletes the specified session from the session table.  Future
  requests to the session are answered with the timeout text.
\end{desc}

\defun{session-alive?}{session}{boolean}
\begin{desc}
  This returns \sharpt, if the specified session is alive, \ie
  requests to it will be answered by the appropriate \surflet.
  Otherwise, she returns \sharpf.
\end{desc}

\defun{session-surflet-name}{session}{string}
\defunx{session-session-id}{session}{session-id}
\begin{desc}
  These procedures inspect values of a session.
  \ex{session-surflet-name} returns the name of the \surflet for which
  the session was created.  \ex{session-session-id} returns the
  session ID of the session. 
\end{desc}

For each session, the \surflet handler has a counter running.  She
resets the counter each time she receives a request for the session.
When the counter reaches a particular number of seconds, the
\keyword{lifetime} of the session, the \surflet handler deletes the
session and removes it from its session table.  She will answer all
future requests for the session with the timeout text.  The following
procedures deal with the lifetime of a session.

\defun{session-lifetime}{session}{integer}
\defunx{set-session-lifetime!}{session new-lifetime}{undefined}
\begin{desc}
  \ex{session-lifetime} returns the number of seconds the \surflet
  handler will initially wait before she automatically finishes the
  session.  \ex{set-session-lifetime!} changes the initial lifetime of
  the \var{session} to \var{new-lifetime} and also resets the counter
  for that session.
\end{desc}

\defun{session-adjust-timeout!}{session [lifetime]}{undefined}
\defunx{adjust-timeout!}{[lifetime]}{undefined}
\begin{desc}
  These reset the counter for the lifetime of either the given
  \var{session} (\ex{session-adjust-timeout!}) or the current session
  (\ex{adjust-timeout!}).  Both procedures give the session a lifetime
  of either \var{lifetime} seconds or of the lifetime seconds stored
  for the according \var{session}.
\end{desc}

In order to allow easy web programming, the \surflet handler
automatically saves and reifies continuations of a session.  This is
totally transparent to the web programmer.  For adminstration
purposes, the \surflet handler offers access to the continuation table
of a session via the following procedures.

\defun{session-continuation-table}{session}{table}
\defunx{session-continuation-table-lock}{session}{lock}
\defunx{session-continuation-counter}{session}{thread-safe-counter}
\begin{desc}
  These functions the continuation table, the lock for the
  continuation table and the counter for the continuations.  The
  continuation \var{table} is a hash table with the continuation ID as
  key and the continuation as value, based on the \ex{tables}
  structure of Scheme48.  The \var{lock} is based on the \ex{locks}
  structure of Scheme48.  The \var{thread-safe-counter} is based on
  the \ex{thread-safe-counter} structure that is part of the
  \surflets.

  The access to these functions is currently unrestricted but may be
  restricted in future versions of the \surflet server.
\end{desc}

The \exi{surflets/continuations} also offers procedures to access the
  continuations.

\defun{get-continuations}{session}{list}
\begin{desc}
  Returns a list of all continuations of the \var{session}.  The list
  elements are pairs with the \ex{car} being the session and the
  \ex{cdr} being the continuation.
\end{desc}

\defun{delete-continuation!}{session-continuation}{undefined}
\begin{desc}
  Removes the specified continuation from the continuation table.
  \var{session-continuation} is a pair as returned from
  \ex{get-continuations}.  It is no error if the session or the
  continuation does not exist anymore.

  The access to this functions is currently unrestricted but may be
  restricted in future versions of the \surflet server.
\end{desc}

\defun{continuation-id}{session-continuation}{number}
\begin{desc}
  Returns the continuation ID of the continuation specified by
  \var{session-continuation} which is a pair as returned by
  \ex{get-continuations}. 
\end{desc}

The \exi{surflets/ids} structure provides procedures to determine the
  session and continuation IDs of the current session.  See also the
  entry for \ex{resume-url-ids} some where else in this document.

\defun{my-session-id}{surlfet-request}{number}
\defunx{my-continuation-id}{surlfet-request}{number}
\defunx{my-ids}{surlfet-request}{number number}
\begin{desc}
  These return the session and continuation ID that where used to
  access the current session.  The procedures work for every
  \var{surflet-request} except for the inital one that \ex{main}
  gets.  The values returned by \ex{my-ids} are the session and the
  continuation ID in this order.
\end{desc}

\defun{surflet-file-name}{surlfet-request}{string}
\begin{desc}
  This returns the name of the \surflet of the current session.
\end{desc}


\subsubsection{Session data}
The \surflet handler distinguishes three kinds of \keyword{session
data}: session data that is local to a session of a \surflet and not
mutated, session data that is local to a session of a \surflet and
mutated and session data that is global to all sessions of a \surflet.
Every variable value that is never mutated is automatically local to
the session of the \surflet.  Variable values that are mutated are
automatically global to all sessions of the \surflet.  Values that
have to be mutated but should be local to a session of the \surflet
must be stored in a special place, the session data field of the
\surflet handler.\footnote{The reason for this distinction is the fact
  that the \surflet handler saves and reifies the continuation of a
  \surflet to realize the easy programming of web applications.
  Mutations of values remain visible after reifying the continuation.}

\defun{get-session-data}{}{object}
\defunx{set-session-data!}{new-value}{undefined}
\begin{desc}
  These procedures allow read/write access to the session data field
  of the \surflet handler.  The \surflet handler installs a session
  data field for each session she creates.  \ex{get-session-data}
  reads the contents of this field, which is initially \sharpf.
  \ex{set-session-data!} sets the contents of the field to
  \var{new-value}.  Mutations to the values, no matter when they
  occur, are local to the session from which the procedures are
  called, \ie the changes are only visible within a particular session
  of the \surflet.  The procedures are exported by the
  \exi{surflet-handler/session-data} structure.
\end{desc}


\subsection{Basic I/O}

The \surflet communicates with the web client basically with the
following \ex{send} primitives.  They are exported by the
\exi{surflet-handler/primitives} structure along with the procedures
from \ex{surflet-handler/requests}, \ex{surflet-handler/responses} and
the \ex{status-code} syntax.

\defun{send}{surflet-response}{\noreturn}
\begin{desc}
  This procedure send the data of the \var{surflet-response} to the
  client and does not return.
\end{desc}

\defun{send/finish}{surflet-response}{\noreturn}
\begin{desc}
  This procedure does the same as \ex{send}, but it also finishes the
  session of the \surflet.  Future requests to the \surflet will be
  answered with the timeout text (see above).
\end{desc}

\defun{send/suspend}{surflet-response-maker}{surflet-request}
\begin{desc}
  This procedure suspends the current computation of the \surflet and
  calls \var{surflet-response-maker} with the continuation-URL of the
  current session to create the actual \ex{surflet-response}.  When a
  client requests the continuation-URL, the computation of the
  \surflet will resume with \ex{send/suspend} returning that request
  of the client.  See \ref{sec:continuation-url} for details on
  continuation-URLs.
\end{desc}

\defun{send-error}{status-code surflet-request [messages]}{\noreturn}
\begin{desc}
  This sends an error response to the client.  \var{status-code} is
  the status code of the error, see section \ref{sec:http-responses} for
  details.  \var{surflet-request} is the last \ex{surflet-request} the
  \surflet received; if unknown this argument may be \sharpf.
  \var{messages} may contain some further information about the cause
  of the error.
\end{desc}


\subsection{Web I/O}

Most of the time, a \surflet won't send arbitrary data but HTML to the
client.  For this purpose, the \surflets provide extensive support.
First of all, they provide procedures specially designed for
submitting HTML.

\defun{send-html}{sxml}{\noreturn}
\defunx{send-html/finish}{sxml}{\noreturn}
\defunx{send-html/suspend}{sxml-maker}{surflet-request}
\begin{desc}
  These are the equivalent procedures to the \ex{send} primitives.
  \ex{send-html} and \ex{send-html/finish} accept an SXML object (more
  on that below), translate it into HTML and send it to the client,
  the latter finishing the session.  \ex{send-html/suspend} suspends
  the current computation, calls \var{sxml-maker} with the
  continuation-URL, translates the resulting SXML into HTML and sends
  it to the client.  When the client requests the continuation-URL,
  the computation is resumed and \ex{send-html/suspend} returns with
  the \ex{surflet-request}.
\end{desc}


\subsubsection{SXML}

For easy creation of HTML output, the \ex{send-html} procedures
mentioned above represent the HTML in SXML.  SXML is a creation of
Oleg Kiselyov.  Basically, SXML is a list whose \ex{car} is an SXML
tag, a symbol representing the HTML tag, and the \ex{cdr} are other
SXML elements that will be enclosed by the HTML tag.  For example,

\codex{'(h2 "Result")}
represents the tag \ex{h2}, that encloses the text "Result".  The
represented HTML is
\codex{<h2>Result</h2>\textnormal{.}}

As in HTML, elements may be nested:
\codex{'(body (h2 "Result") (p "Example"))}
represents
\codex{<body><h2>Result</h2><p>Example</p>\textnormal{.}}

The @ symbol marks HTML attributes.  The attributes follow the @
symbol in two element lists, the first element being the name of the
attribute and the last its value.  For example, this is a link:
\codex{'(a (@ (href "add-surflet.scm") (name "linklist")) "Make new calculation.")}
representing the following HTML
\codex{<a href="add-surflet.scm" 
name="linklist">Make new calculation.</a>\textnormal{.}}  The
attributes form will only be recognized as such if it is the second
element of a list, right after the SXML tag.  

\defun{sxml-attribute?}{object}{boolean}
\defunx{sxml-attribute-attributes}{sxml-attribute}{list}
\begin{desc}
  These are procedures on SXML attribute forms.  \ex{sxml-attribute?}
  is  a predicate for SXML attribute forms.
  \ex{sxml-attribute-attributes} returns the list of name-value-lists
  of the attributes form.  Both procedures are exported by the
  \exi{surflets/sxml} structure.
\end{desc}

The translator translates list elements which are numbers and symbols
to their string representation (except for the first element, of
course).  She scans strings for the special characters \verb'&',
\verb'"', \verb'>' and \verb'<' and replaces them by their HTML
equivalents, and she ignores \sharpf and the emtpy list.  See below
the special SXML tag \ex{plain-html} to see how to insert HTML code
untranslated.  Furthermore, the translator accepts \ex{input-fields}
as list elements, which are translated to their HTML representation.
See below for details on input fields.

Using lists to represent HTML allows the programmer to define
operations on it.  Most programmers construct their lists dynamically,
often by using \ex{quasiquote} (the symbol \ex{`}) and \ex{unquote}
(the symbol \ex{,}).  \Eg

\begin{alltt}
 `(html (title ,my-title) 
        (body (p "Hello, " ,(get-user-full-name))))
\end{alltt}

See below for how to create your own SXML.

\subsubsection{Special SXML tags}

The SXML to HTML translator accepts some special SXML tags that don't
directly translate to an HTML tag.

\newcommand{\defsxmltag}     {\par\medskip\defsxmltagx}
\newcommand{\defsxmltagx}[2]%
{\hbox to \linewidth{\ttchars%
     {\ttt(#1\testvoid{#2}{}{\ }{\sem{#2}}\testvoid{#2}{}{\/})
%\hskip 1em minus 0.5em$\longrightarrow$\hskip 1em minus 0.5em
%{\sem{#3}}
\hfill\quad\textnormal{SXML-tag}}}\index{#1}}


\defsxmltag{url}{URL [text]}
\begin{desc}
  Inserts a link to \var{URL}, named with \var{text}.  \var{text}
  defaults to \var{URL}.  Takes at least one argument.  \Eg
  
  \begin{alltt}
  (url "/" "Main menu") \ensuremath{\Longrightarrow} <a href="/">Main menu</a>
  (url "go.html")       \ensuremath{\Longrightarrow} <a href="go.html">go.html</a>
  \end{alltt}  

\oops{\ex{url} does not accept extra attributes for the `\ex{A}' tag of
  HTML.  This should be fixed in a future version.} 
\end{desc}

\defsxmltag{nbsp}{}
\begin{desc}
  Inserts the HTML sequence \ex{"\&nbsp;"}.  Takes no arguments.
\end{desc}

\defsxmltag{plain-html}{html \ldots}
\begin{desc}
  Inserts \var{html} without any changes, thus it works like a quote.
  Takes any number of arguments.
\end{desc}

\defsxmltag{*COMMENT*}{comment \ldots}
\begin{desc}
  Inserts a comment, \ie \var{comment} enclosed between \verb|<!--|
  and \verb|-->|.  Takes any number of arguments.
\end{desc}

\defsxmltag{surflet-form}{k-url [method] [attributes] [SXML \ldots]}
\begin{desc}
  Inserts HTML code for a web form.  See below for details.
  \var{k-url} usually is a continuation-URL.  \var{method} is the
  method to be used by the client to transfer the webform data.
  Possible values are the symbols \ex{GET}, \ex{get}, \ex{POST},
  \ex{post}, the first two specifying the GET method, the last two the
  POST method.  \var{method} defaults to the GET method.
  \ex{attributes} are attributes for the created web form, \eg \ex{(@
  (enc-type "text/plain"))}.  The remaining arguments are taken as
  SXML and translated as usually.  Takes at least one argument.  Note
  that the attributes form may come at position three.
\end{desc}

\subsubsection{Do it yourself: your own SXML}

The \ex{send-html} procedures use a standard set of translation rules
to translate from SXML to HTML.  However, you may define your own set
of translation rules or extend the given ones as you see fit.  For
this, a short introduction to the translation process.

The translation process takes place in two steps.  Step one translates
the given SXML to low level SXML, essentially a rough form of HTML in
list notation.  Step two takes this low level SXML and prints to a
port.  Step one is performed by \ex{sxml->low-level-sxml}, step two by
\ex{display-low-level-sxml}.  All procedures and rules presented in
this subsection are exported from \exi{surflets/sxml}.

\defun{sxml->low-level-sxml}{sxml rules}{low-level-sxml}
\begin{desc}
  Takes an SXML object (which essentially is a list) and a list of
  SXML rules (more on this below) and translates it to low level SXML.
  This procedure is an alias to the \ex{pre-post-order} procedure of
  Oleg Kiselyov's SSAX module.  It is an error if no rule triggers
  (see below for when a rule triggers).  However, it is no error if
  multiple rules trigger; the first rule in the \var{rules} list wins.
\end{desc}

\defun{display-low-level-sxml}{low-level-sxml port}{boolean}
\begin{desc}
  Takes low level SXML and \ex{display}s it to a port.  She traverses
  the list \var{low-level-sxml} depth-first, ignores the empty list
  and \sharpf, executes thunks and \ex{display}s all other elements,
  usually strings and characters, to \var{port}.  Returns \sharpt if
  she wrote anything, \sharpf otherwise.  This function is basically
  the \ex{SRV:send-reply} procedure of Oleg Kiselyov's SSAX module.
\end{desc}

\defun{sxml->string}{sxml rules}{string}
\begin{desc}
  Combines step one and two of the translation process and returns the
  resulting string, \ie it calls \ex{display-low-level-sxml} with the
  result of a call to \ex{sxml->low-level-sxml} and a string port,
  returning the content of the string port.
\end{desc}

%\defun{sxml->string/internal}{sxml rules}{list}
%\begin{desc}
%  I forgot what this function was good for.  I probably used it
%  internally in one of the \surflet rules.
%\end{desc}

An \keyword{SXML-rule} consists of a \textit{trigger}, which is a
symbol, and the \textit{handler}, which is a translation procedure.

There are three types of rules, each of which is a dotted list:
\begin{description}
\item[\ex{(\synvar{trigger} *preorder* . \synvar{handler})}] \mbox{}\\
When \ex{sxml->low-level-sxml} sees the \synvar{trigger} as the
first element of a list, she calls \synvar{handler} with the
\emph{whole} list as arguments and replaces the list with the result
of that call (which must be a single value).  Note that the arity of
the handler determines how many elements the list with the trigger may
or must contain.

\item[\ex{(\synvar{trigger} . \synvar{handler})}] \mbox{}\\
When \ex{sxml->low-level-sxml} sees the \synvar{trigger} as the first
element of a list, she calls herself on the remaining elements of the
list and then calls the \synvar{handler} with the trigger and the
results of those calls as arguments.

\item[\ex{(\synvar{trigger} \synvar{new-rules} . \synvar{handler})}] \mbox{} \\
When \ex{sxml->low-level-sxml} sees the \synvar{trigger} as the first
element of a list, she temporarily prepends \synvar{new-rules} to the
current rule set while calling herself on the remaining elements of
the list.  She then calls the \synvar{handler} with the trigger and
the results of those calls as arguments.  As the new rules are
prepended, this rule allows the temporary override of some rules.
\end{description}

There are two special triggers, who may trigger for all elements of
the SXML, not only the first element of a list:
\begin{itemize}
\item  \ex{*text*} triggers for atoms in the SXML list, \ie usually
strings and characters.  The handler is called with the symbol
\ex{*text*} and the atom as arguments.

\item \ex{*default*} triggers whenever no rule triggered, including
\ex{*text*}.  If called for a list whose first element did not trigger
a rule, the handler is called with the whole list.  If called for an
atom, the handler is called with the symbol \ex{*text*} and the atom
as arguments.
\end{itemize}

The \exi{surflets/sxml} structure defines some basic rules:

\defvar{default-rule}{SXML-rule}
\defvarx{text-rule}{SXML-rule}
\defvarx{attribute-rule}{SXML-rule}
\begin{desc}
  These are the three basic rules exported by the \ex{surflets/sxml}
  structure.  \ex{default-rule} creates the leading and trailing HTML
  tag and encloses the attributes.  \ex{text-rule} just inserts the
  given text with the special HTML characters \verb'&', \verb'"',
  \verb'>' and \verb'<' escaped.  \ex{attribute-rule} triggers for the
  attributes form and creates attributes like \ex{selected} or
  \ex{color="red"}.
\end{desc}

The \exi{surflets/surflet-sxml} add the rules for the special SXML
tags to this list:

\defvar{url-rule}{SXML-rule}
\defvarx{nbsp-rule}{SXML-rule}
\defvarx{plain-html-rule}{SXML-rule}
\defvarx{comment-rule}{SXML-rule}
\defvarx{surflet-form-rule}{SXML-rule}
\begin{desc}
  These are the rules for the special SXML tags mentioned above,
  namely \ex{url}, \ex{nbsp}, \ex{plain-html}, \ex{*COMMENT*} and
  \ex{surflet-form}. 
\end{desc}

\defvar{default-rules}{list}
\defvarx{surflet-sxml-rules}{list}
\begin{desc}
  These are rule sets.  \ex{default-rule} contains the rulese
  \ex{default-rule}, \ex{attribute-rule}, \ex{text-rule},
  \ex{comment-rule}, \ex{url-rule}, \ex{plain-html-rule} and
  \ex{nbsp-rule}.  \ex{surflet-sxml-rules} extends this list by
  \ex{surflet-form-rule} and a rule for input fields.
\end{desc}

\defun{surflet-sxml->low-level-sxml}{sxml}{low-level-sxml}
\begin{desc}
  This uses the \ex{surflet-sxml-rules} to translate \var{sxml} to low
  level SXML, performin step one of the translation process.
\end{desc}


\subsection{Continuation-URL}
\label{sec:continuation-url}

The \keyword{continuation-URL} represents the point in the computation
of a session of a \surflet where the computation was halted by the
\surflet handler.  When a browser requests a continuation-URL, the
\surflet handler looks up the continuation in its tables and reifies
it, allowing the session of the \surflet to resume its computation.

The procedures to access the continuation-URL are the following.  They
are exported by the \exi{surflet-handler/resume-url} structure.  Sorry
for the double naming \ex{resume-url} and continuation-URL.

\defun{resume-url?}{string}{boolean}
\defunx{resume-url-ids}{resume-url}{session-id continuation-id}
\defunx{resume-url-session-id}{resume-url}{session-id}
\defunx{resume-url-continuation-id}{resume-url}{continuation-id}
\begin{desc}
  These inspect values of a resume url.  \ex{resume-url?} is predicate
  for resume urls.  Note that it only operates on strings.
  \ex{resume-url-ids} returns the session- and the continuation-id
  that is stored in the \var{resume-url}.  \ex{resume-url-session-id}
  and \ex{resume-url-continuation-id} return only the session- or the
  continuation-id, respectively.
\end{desc}



\subsection{Input fields}

The \surflets support all input fields defined for HTML~2.0 and allow
  the creation of own input fields.  \ex{input-field}s are first order
  values, that represent the actual input field of the web page in the
  \surflet.  For that, this documentation distinguishes the
  \emph{browser} value from the \emph{Scheme} value of an input field.
  The browser value is the string representation of the input field
  data the browser sends.  The Scheme value is the value in the
  \surflet the input field reports as its value, which may be of any
  type, not only strings.

Here is a short overview, how to use input fields.  See also the howto
  for more informations.  First, you create the \ex{input-field} that
  represents the input field you want to use.  Then you put this
  \ex{input-field} into the SXML of the web page at the place the
  input field shall appear.  After \ex{send-html/suspend} has returned
  with the next \ex{surflet-request}, you call \ex{get-bindings} with
  that \ex{surlfet-request} and collect the resulting bindings.  Last,
  you call \ex{input-field-value} (or \ex{raw-input-field-value}) with
  your \ex{input-field} and the collected bindings to get the Scheme
  representation of the value the user has entered.  Here is a small
  example:

\begin{alltt}
(define-structure surflets surflet-interface
  (open scheme-with-scsh
        surflets)
  (begin
    
    (define (main req)
      (let* ((text-input (make-text-field))
             (req (send-html/suspend
                   (lambda (k-url)
                     `(html
                       (body
                        (surflet-form
                         ,k-url
                         (p "Enter some asd  text: " ,text-input)
                         ,(make-submit-button)))))))
             (bindings (get-bindings req))
             (text (input-field-value text-input bindings)))
        (send-html/finish 
         `(html
           (body
            (p "You've entered `" ,text "'."))))))
))
\end{alltt}

\paragraph{Getting the bindings}

The \exi{surflets/bindings} structures exports the necessary functions
  to create bindings and extract values from them:

\defun{get-bindings}{surflet-request}{bindings}
\begin{desc}
  This returns an association list representing the data the browser
  has sent, usually the content of a webform.  The name of the input
  fields are the keys, their browser values the values.  The values
  are already unescaped.  \ex{get-bindings} can (currently) only
  handle \ex{application/x-www-form-urlencoded} data.  You can call
  \ex{get-bindings} on both \ex{GET} and \ex{POST} requests, even
  multiple times (even on \ex{POST} requests).
\end{desc}

\defun{extract-bindings}{key bindings}{list}
\defunx{extract-single-binding}{key bindings}{string}
\begin{desc}
  These extract values from the \var{bindings} as returned by
  \ex{get-bindings}.  \var{key} may be a string or a symbol which will
  be translated to a string before use.  \ex{extract-bindings} returns
  a list of all values from \var{bindings} whose key is \var{key}.
  \ex{extract-single-binding} returns the value from the binding whose
  key is \var{key} and raises an error if there more than one such
  binding.  The two procedures are the same as in PLT's webserver.
\end{desc}

\ex{get-bindings} must acces the "Content-length" header field to
  handle \ex{POST} request.  \ex{surflets/bindings} therefore also
  exports the procedure that does that job:

\defun{get-content-length}{headers}{number}
\begin{desc}
  Returns the value of the "Content-length" header as a number, as
  present in \var{headers}, \eg from \ex{surflet-request-headers}.
  Will raise an error if there is no "Content-length" header or the
  header is illformed, \eg contains no number.
\end{desc}

\paragraph{Retrieving the Scheme values}

The \exi{surflets/input-field-value} structure provides the functions
  necessary to retrieve the Scheme value of input fields.

\defun{raw-input-field-value}{input-field bindings}{any type}
\defunx{input-field-value}{input-field bindings [error-value]}{any type}
\begin{desc}
  These extract the Scheme value of an \var{input-field}, given the
  \var{bindings} of the last request.  Asking for a Scheme value may
  raise an error.  Some error conditions are: the input field was not
  present in the bindings, the transformer could not generate a Scheme
  value for the browser value, or some other error occured in a maybe
  malfunctioning transformer.  In any case, \ex{raw-input-field-value}
  won't catch that error, while \ex{input-field-value} will catch it
  and provide \var{error-value} as the \var{input-field}'s Scheme
  value, which defaults to \sharpf.
\end{desc}

\defun{input-field-binding}{input-field bindings}{binding}
\begin{desc}
  This returns the first binding in \var{bindings} that belongs to the
  given \var{input-field} (\ie has \var{input-field}'s name as key).
\end{desc}

\paragraph{Creating and using input fields}

The procedures for the creation of the input fields mentioned in
  HTML~2.0 are the following.  They are exported by the
  \exi{surflets/surflet-input-fields}.  Note that most of the time,
  you may omit any of the optional arguments, \eg you may only specify
  some further attributes to \ex{make-text-field} without specifying a
  default value.  Keep in mind that \ex{input-field-value} catches the
  error that may occur if an \ex{input-field} is asked for its Scheme
  value and may return any (previously chosen) value instead.

\defun{make-text-field}{[default] [attributes]}{input-field}
\defunx{make-number-field}{[value] [attributes]}{input-field}
\defunx{make-password-field}{[default] [attributes]}{input-field}
\defunx{make-textarea}{[default] [rows] [columns] [readonly?] [attributes]}{input-field}
\begin{desc}
  These create various input field where the user types something in.
  \var{default} is the text or the number that the browser initially
  displays in the input field.  \var{attributes} are some further
  attributes for the input field in SXML notation.
  \ex{make-text-field} creates a regular text input field.  Its Scheme
  value is a string.  \ex{make-number-field} creates a regular text
  input field, whose Scheme value is a number.  It is an error if the
  input field does not contain a number.  \ex{make-password-field}
  creates a text input field that will display stars instead of the
  typed text.  Its Scheme value is a string.  \ex{make-textarea}
  creates a possibly multi line text input field.  \var{rows}
  specifies how many rows of the text the browser will display at once
  and defaults to 5.  \var{columns} specifies how many columns the
  browser will display at once and defaults to 20.  Note that if you
  only supply one number, it will be interpreted as the \var{rows}
  argument.  \var{readonly?} is a boolean that tells the browser
  whether to disallow changes of the displayed text.
\end{desc}


\defun{make-hidden-input-field}{[default] [attributes]}{input-field}
\begin{desc}
  Creates a hidden input field, \ie a input field that the browser
  won't display but whose value the browser will send.  This input
  field is provided for completeness; you usually won't need it, as
  all values in your \surflet will survive the emission of a web page.
  \var{default} is this value the browser will send.  Note that
  although the argument is marked as optional you usually want to
  provide it.  \var{attributes} are some further attributes for the
  input field in SXML notation.
\end{desc}

\defun{set-text-field-value!}{input-field}{undefined}
\defunx{set-number-field-value!}{input-field}{undefined}
\defunx{set-hidden-field-value!}{input-field}{undefined}
\defunx{set-password-field-value!}{input-field}{undefined}
\defunx{set-textarea-value!}{input-field}{undefined}
\begin{desc}
  These set the default value of the according input field after it
  has been created.  Although the procedure may not complain, it is an
  error, if \var{input-field} is not the expected type of
  \ex{input-field}, \eg if the argument to \ex{set-text-field-value}
  was not created by \ex{make-text-field}.
\end{desc}

\defun{make-submit-button}{[caption] [attributes]}{input-field}
\defunx{make-reset-button}{[caption] [attributes]}{input-field}
\defunx{make-image-button}{image-source [attributes]}{input-field}
\begin{desc}
  These create buttons on the web page which the user can click on.
  \var{caption} is the text that is displayed on the button.  If not
  specified, the browser will choose a text, usually depending on the
  local language setting on the browser side.  \var{attributes} are
  some further attributes for the input field in SXML notation.
  \ex{make-submit-button} creates the regular button to submit the web
  form data.  As HTML~2.0 specifies that the value of a submit button
  is its caption, its Scheme value is its caption, too.
  \ex{make-reset-button} creates the button to reset all input fields
  of the web form to their default values.  As the browser does not
  send data for reset buttons, it does not have a Scheme value, \ie
  asking for a value will raise an error.  \ex{make-image-button}
  creates a picture button.  Its Scheme value is a pair indicating the
  x- and y-coordinates of the picture where the user has clicked to.
  The argument \var{image-source} is not optional and is the string
  URL of the displayed picture.
\end{desc}

\defun{make-checkbox}{[checked?] [attributes]}{input-field}
\defunx{make-annotated-checkbox}{value [checked?]
  [attributes]}{input-field}
\begin{desc}
  These create checkboxes.  \var{checked?} says whether the browser
  should initially mark the checkbox as checked.  \var{attributes} are
  some further attributes for the input field in SXML notation.  If it
  was checked the Scheme value of a checkbox made by
  \ex{make-checkbox} is \sharpt.  If it was checked, the Scheme value
  of a checkbox made by \ex{make-annotated-checkbox} is its
  \var{value} provided during its creation where \var{value} may be
  chosen arbitrarily.  Note that HTML~2.0 specifies that browsers
  should not send data for unmarked checkboxes, thus asking for the
  Scheme value of an unmarked checkbox will raise an error.  It is
  recommended to use \ex{input-field-value} to ask for the Scheme
  value of a checkbox.  This will catch the error and will instead
  return \sharpf by default.
\end{desc}

\defun{check-checkbox!}{input-field}{undefined}
\defunx{uncheck-checkbox!}{input-field}{undefined}
\defunx{set-checkbox-checked?!}{input-field checked?}{undefined}
\begin{desc}
  These change the \ex{checked?} field of a checkbox that tells the
  browser whether it should initially mark the checkbox as checked.
  \ex{check-checkbox!} tells the browser to do so,
  \ex{uncheck-checkbox!} does not tell the browser to do so, and
  \ex{set-checkbox-checked?!} does so depending on \var{checked?}.  It
  is an error if \var{input-field} was not created by
  \ex{make-checkbox} or \ex{make-annotated-checkbox}.
\end{desc}

\defun{make-radio-group}{}{procedure}
\defunx{make-annotated-radio-group}{}{procedure}
\begin{desc}
  These return generators for radio buttons.  Radio buttons usually
  are part of a group of radio buttons of which only one may be
  selected at any time.  The procedures return a procedure that
  creates radio button \ex{input-field}s that belong to the same
  group.  

  The returned procedures accept a \var{value} argument, an optional
  \var{checked?} argument and an optional \var{attributes} argument.
  They return an \ex{input-field}, the actual radio button.  For
  \ex{make-radio-group}, \var{value} must be a string, for
  \ex{make-annotated-radio-group}, \var{value} may be any Scheme
  value.  The Scheme value of any member of the group of radio buttons
  is the \var{value} of the marked radio button that was provided
  during its creation.  \var{checked?} determines whether the browser
  will initially mark the radio button.  Note that you are able to
  tell the browser to initially mark more than one radio button, but
  in which case the browser's behavior is undefined.  \var{attributes}
  are some further attributes for the input field in SXML notation.

%The procedure returned by \ex{make-radio-group} is of the
%  form of \ex{\textit{radio-generator}} explained below, the one
%  returned by \ex{make-annotated-radio-group} is of the form of
%  \ex{\textit{annotated-radio-generator}}.

%\defun{\textit{radio-generator}}{text [checked?]
%  [attributes]}{input-field}
%\defunx{\textit{annotated-radio-generator}}{value [checked?]
%  [attributes]}{input-field} 
%\begin{desc}
%  A further description.
%\end{desc}
\end{desc}

\defun{check-radio!}{input-field}{undefined}
\defunx{uncheck-radio!}{input-field}{undefined}
\defunx{set-radio-checked?!}{input-field \var{checked?}}{undefined}
\begin{desc}
  These change the \ex{checked?} field of a radio button that tells
  the browser whether it should initially mark the radio button as
  checked.  \ex{check-radio!} tells the browser to do so,
  \ex{uncheck-radio!} does not tell the browser to do so, and
  \ex{set-radio-checked?!} does so depending on \var{checked?}.  It is
  an error if \var{input-field} was not created by the procedures
  returned by \ex{make-radio-group} or
  \ex{make-annotated-radio-group}.
\end{desc}

\defun{make-select}{select-options [multiple?]
  [attributes]}{input-field}
\begin{desc}
  This creates a select boxes.  Other names are ``drop down menu'' or
  simply ``list''.  \var{select-options} is either a list of
  \ex{select-options} created with the procedures presented below or a
  list of strings.  In the latter case the strings are automatically
  translated into \ex{select-options}.  \var{multiple?}  allows
  multiple selections in the select box.  \var{attributes} are some
  further attributes for the input field in SXML notation.  Note that
  you will only get multiple Scheme values for a select box that
  allows multiple selections, if you specify the \var{multiple?}
  argument; providing the according attribute in \var{attributes}
  won't work (you will get the value of the first selection only).
\end{desc}

\defun{make-simple-select-option}{tag [selected?]
  [attributes]}{select-option}
\defunx{make-annotated-select-option}{tag value [selected?]
  [attributes]}{select-option}
\begin{desc}
  These create the options for a select box, to be used as arguments
  to \ex{make-select}.  \var{tag} is a string that will be displayed
  as an option of a select box.  \var{value} is an arbitrary Scheme
  value that will be the Scheme value of the select input field 
  that contains the option.  For simple select options this is the same as
  \var{tag}.  \var{selected?} determines whether the browser should
  preselect the option.  \var{attributes} are some further attributes
  for the input field in SXML notation.
\end{desc}

\defun{select-option?}{object}{boolean}
\begin{desc}
  This is a predicate for \ex{select-option}s.
\end{desc}

\defun{select-select-option!}{tag input-field}{undefined}
\defunx{unselect-select-option!}{tag input-field}{undefined}
\defunx{set-select-option-selected?!}{tag input-field
  selected?}{undefined}
\begin{desc}
  These change the \ex{selected?} field of a select option that tells
  the browser to preselect it.  \ex{select-select-option!} tells the
  browser to preselect it, \ex{unselect-select-option!} does not tell
  it to do so and \ex{set-select-option-selected!} does so depending
  on \var{selected?}.  Note that you access the select option by
  providing the \var{tag} and the select \var{input-field} in which
  the select option is saved.  \var{tag} is either the tag of the
  select option or an index with 0 being the first select option of
  that select input field.  However, the change will affect all select
  input fields that use the same select option.  If there are
  different select options with the same tag in a select input field,
  the procedures will only touch one of them.

\oops{Unfortunetaly, the order of the arguments (index, object) is the
  opposite of what is usual in Scheme (object, index).  This should be
  fixed in a future version.}
\end{desc}

\defun{add-select-option!}{input-field select-option}{undefined}
\defunx{delete-select-option!}{input-field select-option}{undefined}
\begin{desc}
  These add or remove \var{select-option} to or from the select
  \var{input-field}, respectively.
\end{desc}
	   

\subsubsection{Do it yourself: your own input fields}

The \surflets library allows the creation of arbitrary own input
  fields.  The relevant procedures are exported by the
  \exi{surflets/my-input-fields} structure.

\defun{make-input-field}{name type transformer attributes
  html-tree-maker}{input-field}
\defunx{make-multi-input-field}{name type transformer attributes
  html-tree-maker}{input-field} 
\begin{desc}
  These are the two constructors for \ex{input-field}s.  

  \var{name} is the name of the input field as used in the HTML.  You
  have to make sure that this name is unique across your web page, \eg
  by using \ex{generate-input-field-name} presented below.  

  \var{type} is the type of the input field and mainly meant as a
  label for debugging.  You may choose an arbitrary value for it.
  
  \var{transformer} is a procedure that accepts the created
  \ex{input-field} and some other value as arguments and returns the
  (single) Scheme value of the input field.  For
  \ex{make-input-field}, the other value is the string representation
  of the value the user has entered in the represented input field, as
  sent by the browser.  For \ex{make-multi-input-field}, the other
  value is an association list of all data the browser has sent, the
  names being the key and the entered data being the value.  This is
  the very same list as returned by \ex{get-bindings}, see above.
  When the \var{transformer} cannot create a Scheme value for the
  \ex{input-field}, she should raise an error.

  \var{attributes} takes some extra information you want to store
  along with the \ex{input-field}.  You may choose an arbitrary value
  for it. 

  \var{html-tree-maker} is a procedure that takes the created
  \ex{input-field} as argument and returns its representation in SXML.
\end{desc}

\defun{generate-input-field-name}{prefix}{string}
\begin{desc}
  This generates a pseudo unique name based on prefix.  Subsequent
  calls with the same prefix are guaranteed to never return the same
  string.\footnote{Well, never say never:  if the structure is
  reloaded, the counter is reset and \ex{generate-input-field-name}
  will return the same names again.} 
\end{desc}


\defun{input-field-name}{input-field}{string}
\defunx{input-field-type}{input-field}{any type}
\defunx{input-field-transformer}{input-field}{procedure}
\defunx{input-field-attributes }{input-field}{any type}
\defunx{input-field-html-tree-maker}{input-field}{procedure}
\defunx{input-field-html-tree}{input-field}{sxml}
\defunx{input-field-multi?}{input-field}{boolean}
\begin{desc}
  These inspect input field values.  \ex{input-field-name} returns the
  name of the input field as used in its HTML representation.
  \ex{input-field-type} returns a string indicating the type of the
  input field, \eg "\ex{radio}" or "\ex{text}".  For individual input
  fields it may return a value of any type.
  \ex{input-field-transformer} returns the transformer procedure that
  is used the transform the browser value of the input field to a
  Scheme value.  \ex{input-field-attributes} returns the attributes
  that were stored along with the input field.
  \ex{input-field-html-tree-maker} returns the procedure that creates
  the SXML representation of the input field.
  \ex{input-field-html-tree} returns the SXML representation of the
  input field.  \ex{input-field-multi?} returns \sharpt if the input
  field was created with \ex{make-multi-input-field}, \sharpf
  otherwise.  The transformer of an multi-\ex{input-field} gets the
  browser bindings as second argument while the transformer of a
  normal (non-multi) \ex{input-field} gets the string representation
  of the entered data as second argument.
\end{desc}


\defun{set-input-field-attributes!}{input-field
  new-attributes}{undefined}
\begin{desc}
  This allows the mutation of the attributes of the \var{input-field}
  to \var{new-attributes}.
\end{desc}

\defun{touch-input-field!}{input-field}{undefined}
\begin{desc}
  This forces the recalculation of the SXML representation of the
  \var{input-field} using its html-tree-maker procedure.
\end{desc}


\subsection{Web addresses}

The \surflets library allow you to determine which link or button a
  user used to leave a page.  The links are called evaluatable web
  addresses.  The \exi{surflets/returned-via} structure provides
  procedures and syntax for this.

\defun{returned-via}{return-object bindings}{any value}
\defunx{returned-via?}{return-object bindings}{any value}
\begin{desc}
  Determines, whether the user left the web page using
  \var{return-object}.  \var{bindings} are the bindings as returned by
  \ex{get-bindings}.  If \var{return-object} is an \ex{input-field},
  \ex{returned-via} returns its Scheme value as reported by
  \ex{input-field-value}.  The input field usually can only be a
  submit or an image button.  If \var{return-object} is not an
  \ex{input-field}, \ex{returned-via} assumes it is an evaluatable web
  address.  If the user did not use the evaluatable web address to
  leave the web page, \ex{returned-via} returns \sharpf.  Otherwise,
  when the evaluatable web address is annotated, \ex{returned-via}
  returns its annotation, otherwise just \sharpt.  \ex{returned-via?}
  is an alias for \ex{returned-via}.  The type of the return value
  depends on the type of \var{return-object}.
\end{desc}

% There is \defsyn or \defsyntax command yet, so I hack it on my own.
\defsyn{case-returned-via}{\synvar{key} \synvar{clause} \ldots}
% This said:
% (case-returned-via \synvar{key} \synvar{clause} \ldots)      syntax
%\defvar{(case-returned-via \synvar{key} \synvar{clause} \ldots)}{syntax}
\begin{desc}
  This works like \ex{case} with some flavor of \ex{cond}.  Instead of
  \ex{eq?}  it uses \ex{returned-via} to determine which
  \synvar{clause} applies.  \synvar{key} is the \var{bindings}
  argument to \ex{returned-via} (see above for the arguments of
  \ex{returned-via}).  

  A clause is of the form
\codex{((\synvar{datum} \ldots) \synvar{expression} \ldots)}
  where each \synvar{datum} is the \var{return-object} argument of
  \ex{returned-via}.   If for any of the \synvar{datum}
  \ex{returned-via} returns a true value, the \synvar{expression}s are
  evaluated.  

  Alternatively, a clause may be of the form
\codex{((\synvar{datum} \ldots) => \synvar{procedure} \ldots)}
  If for any of the \synvar{datum} \ex{returned-via} returns a true
  value, \synvar{proc} is called with that value.  

  The last possible clause is an "else" clause of the form
\codex{(else \synvar{expression} \ldots)}
  which applies when the previous clauses don't apply.

  \ex{case-returned-via} returns the value(s) of the
  \synvar{expression} that was evaluated last.
\end{desc}

\subsubsection{Evaluatable web addresses}

The \exi{surflets/addresses} structure provides procedures to create
  evaluatable web addresses.  Evaluatable web addresses are used just
  like web addresses with the difference that \ex{returned-via} can
  tell whether the user used this web address to leave the web page.

\defun{make-address}{}{address-procedure}
\begin{desc}
  This creates an evaluatable web address.  \var{address-procedure} is
  a procedure that accepts messages.  If the message is a string,
  \var{address-procedure} will assume it is a continuation URL and
  will return a web address that can be used as a link.  If the
  message is the symbol \ex{address}, \var{address-procedure} will
  return the real \ex{address} object.
\end{desc}

\defun{make-annotated-address}{}{address-procedure}
\begin{desc}
  This creates an annotated evaluatable wewb address.
  \var{address-procedure} is a procedure that accepts messages.  The
  procedure accepts either a string and an optional annotation which
  may be any Scheme value, or it accepts only the symbol \ex{address}.
  In the first case, it will assume the string is a continuation URL
  and will return a web address that can be used as a link.  In the
  latter case, it will return the real \ex{address} object.
\end{desc}

\oops{Evaluatable web address cannot be used as the action URL of web
  forms.} 

\defun{address-name}{address}{string}
\defunx{address-annotated?}{address}{boolean}
\defunx{address-annotation}{address}{any type}
\begin{desc}
  These inspect real \ex{address} objects as returned by the
  evaluatable web addresses when given the symbol \ex{address}.
  \ex{address-name} returns the name of the \var{address} as used in
  the browser data.  \ex{address-annotated?} indicates whether
  \var{address} is annotated.  \ex{address-annotation} returns the
  annotation of \var{address}.  If \var{address} is not annotated, it
  returns \sharpf.
\end{desc}

\subsection{Callbacks}

The \surflets library allows to add a callback to a link.  When the
  user of a web page clicks on the link, the callback will be
  executed. \ex{send-html/suspend} (usually) won't return in that
  case.


\defun{make-callback}{callback-procedure}{continuation-URL}
\begin{desc}
  This creates a callback.  When a user clicks on a link to the
  continuation URL \ex{make-callback} has returned,
  \var{callback-procedure} will be called with the according
  \ex{surflet-request}.  \var{callback-procedure} should not return.

  \ex{make-callback} works with continuations.  Therefore, it is not
  sensible to create callbacks on toplevel, nor is it sensible to
  reuse callbacks.  Instead, create your callback every time and right
  before you need it.

  If \var{callback-procedure} returns, \ex{make-callback} will return
  \emph{again}, this time with the value returned by
  \var{callback-procedure}.  Note that in this case the continuation
  that was active at the time of the call to \ex{make-callback} is
  restored.  Or, in short, don't let \var{callback-procedure} return
  if you want to avoid headaches.
\end{desc}

\defun{make-annotated-callback}{callback-procedure}{procedure}
\begin{desc}
  This creates a callback generator.  The returned procedure accepts
  any number of arguments \var{args} and returns a continuation URL.
  When the user clicks on a link to the continuation URL,
  \var{callback-procedure} will be called with the arguments
  \var{args} previously provided.  

  It is an error, if \var{callback-procedure} returns.  You should
  create a fresh annotated callback every time and right before you
  need it, as the continuation that was active at the time of the call
  to \ex{make-annotated-callback} is restored.
\end{desc}

\defvar{callback-function}{procedure}
\begin{desc}
  Use this procedure as the \var{callback-procedure} argument to
  \ex{make-annotated-callback} to call arbitrary procedures with
  arbitrary arguments.
\end{desc}

Here are some examples.  The first example shows how you can use an
  annotated callback.  Note that it does not need to use
  \ex{send-html/suspend}.

\begin{alltt}
(define-structure surflet surflet-interface
  (open surflets
        surflets/callbacks
        scheme-with-scsh)
  (begin
    
    (define (main req)
      (let ((language (make-annotated-callback result-page)))
        (send-html
         `(html 
           (head (title "Multi-lingual"))
           (body 
            (h2 "Select your language:")
            (ul
             (li (url ,(language "Hello, how are you?") 
                      "English")
             (li (url ,(language "Hallo, wie geht es Ihnen?")
                      "Deutsch")))))))))

    (define (result-page req text)
      (send-html/finish
       `(html 
         (head (title "Greeting"))
         (body
          (h2 ,text)))))
                        
    ))
\end{alltt}


Replacing the \ex{main} procedure with the following definition will
  have the same result:

\begin{alltt}
    (define (main req)
      (let ((language (make-annotated-callback  callback-function)))
        (send-html
         `(html 
           (head (title "Multi-lingual"))
           (body 
            (h2 "Select your language:")
            (ul
             (li (url ,(language result-page "Hello, how are you?") 
                      "English")
             (li (url ,(language result-page "Hallo, wie geht es Ihnen?")
                      "Deutsch")))))))))
\end{alltt}


\subsection{Outdater}

The \surflets library allows the user to navigate through the web
  pages back and forth as she sees fit.  However, sometimes you want
  to make sure, that a submission is done only once.  For this, the
  \surflets provide \ex{outdater} objects that take care of this.

\defun{make-outdater}{}{outdater}
\begin{desc}
  Creates an outdater object.
\end{desc}

\defsyn{if-outdated}{\synvar{outdater} \synvar{consequence}
  \synvar{alternative}}
\begin{desc}
  Using the \synvar{outdater}, this makes sure, the
  \synvar{alternative} is executed at most once, \ie the first time
  the \synvar{outdater} is used in such a form, the
  \synvar{alternative} is evaluated.  Every subsequent evaluation of
  the \ex{if-outdated} form with the \synvar{outdater} will evaluate
  the \synvar{consequence}, usually something similar to what
  \ex{show-outdated} does.
\end{desc}

\defun{show-outdated}{url}{\noreturn}
\begin{desc}
  Emits a regular web page to the client informing the user (in
  English) that ``the page or action you requested relies on outdated
  data''.  It offers a ``reload'' link that points to \var{url} to get
  current data.  Usually, \var{url} is a callback URL the calls the
  according procedure.  See the admin \surflets for examples, \eg
  \ex{scheme/web-server/root/surlfets/admin-surflet.scm}. 
\end{desc}


\subsection{Simple SUrflets}

PLT offers an API to create simple servlets (which are their analogues
  to our \surflets).  The \exi{simple-surflet-api} structure offers
  the procedures with the same name as in the PLT API.  With that,
  \surflets can look as simple as this
  (\ex{scheme/web-server/root/surlfets/add-simple.scm, see also
  \ex{simple-surflet.scm} in the same directory for a larger example}:

\begin{alltt}
(define-structure surflet surflet-interface
  (open scheme-with-scsh
        surflets
        simple-surflet-api
        )
  (begin

    (define (main req)
      (let* ((number-1 (single-query (make-number "First number:")))
             (number-2 (single-query (make-number "Second number:"))))
        (inform (format #f "~a + ~a = ~a"
                        number-1
                        number-2
                        (+ number-1 number-2))))
      (final-page "Session finished."))

))
\end{alltt}

The procedures are the following.

\defun{single-query}{query}{any type}
\begin{desc}
  Asks the user one single questions based on \var{query} and returns
  her answer.
\end{desc}

\defun{queries}{queries}{list}
\begin{desc}
  Asks the user multiple questions based on the list of \var{queries}
  and returns her answers in a list.
\end{desc}

\defun{form-query}{named-queries}{list}
\begin{desc}
  Asks the user multiple queries based on the list of
  \var{named-queries} and returns her answers in a pseudo association
  list.  \var{named-queries} is a list of two element lists.  The
  first element of those lists is a symbol identifying the query, the
  second is the query.  The resulting pseudo association list contains
  two element lists, where the first element is the symbol and the
  second element the user's answer to the query.  The result can be
  read using the \ex{extract/single} and \ex{extract} procedures.
\end{desc}

\defun{inform}{title [text \ldots]}{surflet-request}
\begin{desc}
  Sends a web page title \var{title} with the \var{text} to the user
  as an information.  The returned \ex{surflet-request} is usually
  discarded.  Takes at least one argument.
\end{desc}

\defun{final-page}{title [text \ldots]}{\noreturn}
\begin{desc}
  This sends the last page of the session to the user, titled
  \var{title} and containing \var{text}.  This is the analog to
  \ex{send/finish}.  Takes at least one argument.
\end{desc}

\defun{make-text}{invitation}{query}
\defun{make-number}{invitation}{query}
\defun{make-password}{text}{query}
\defun{make-boolean}{invitation}{query}
\defun{make-radio}{invitation choices}{query}
\defun{make-yes-no}{invitation yes-text no-text}{query}
\begin{desc}
  These create the various queries.  \var{invitation} is a text
  displayed in front of the input field, \eg ``Please enter your
  password:''.  \ex{make-text} creates a text input field,
  \ex{make-number} creates a number input field (\ie a text input field
  that only accepts numbers as inputs), \ex{make-password} creates a
  password input field, \ex{make-boolean} creates a checkbox,
  \ex{make-radio} creates a group of radio buttons of which only one
  can be selected and \ex{make-yes-no} creates a radio group that
  allows the choices \var{yes-text} and \var{no-text}. 

  The value of \ex{make-text}, \ex{make-number} and \ex{make-password}
  is the text or number entered into the input field.  The value of
  \ex{make-boolean} is \sharpt or \sharpf.  The value of
  \ex{make-radio} and \ex{make-yes-no} is the selected choice, a
  string.
\end{desc}

\defun{extract/single}{symbol table}{any value}
\defunx{extract}{symbol table}{list}
\begin{desc}
  Return the answer of a user to a query.  \var{table} is the result
  of \ex{form-query}, \var{symbol} the symbol used to identify the
  query of interest.  For \ex{extract/single}, it is an error if there
  is more than one query in \var{table} that is identified by
  \var{symbol}.
\end{desc}

% shift-reset
% profiling
% handle-fatal
% thread safe counter