diff --git a/doc/latex/surfletapi.tex b/doc/latex/surfletapi.tex index a4a1a4d..4f56186 100644 --- a/doc/latex/surfletapi.tex +++ b/doc/latex/surfletapi.tex @@ -448,6 +448,54 @@ of a session via the following procedures. 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 @@ -512,7 +560,7 @@ the \ex{status-code} syntax. continuation-URLs. \end{desc} -\defun{send/error}{status-code surflet-request [messages]}{\noreturn} +\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 @@ -828,6 +876,7 @@ for the double naming \ex{resume-url} and continuation-URL. \end{desc} + \subsection{Input fields} The \surflets support all input fields defined for HTML~2.0 and allow @@ -1293,8 +1342,7 @@ The \surflets library allow you to determine which link or button a \end{desc} % There is \defsyn or \defsyntax command yet, so I hack it on my own. -{\par\medskip{\index{case-returned-via} - \hbox to \linewidth{\ttchars{{\ttt{(case-returned-via \synvar{key} \synvar{clause} \ldots)}} \hfill syntax}}}% +\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} @@ -1472,3 +1520,145 @@ Replacing the \ex{main} procedure with the following definition will \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 \surlets 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