scsh-conservatory
/
sunet
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Prepare for SUrflet API documentation.

This commit is contained in:
interp 2004-07-29 16:20:20 +00:00
parent bfb4068c9a
commit c1b264b9b1
2 changed files with 41 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

66
doc/latex/surflethowto.tex
View File

@ -20,13 +20,16 @@
%%tableofcontents %%tableofcontents
%%sloppy %%sloppy
\section{Introduction} \section{Howto}
\label{sec:surflethowto}
This howto gives a short introduction in how to write a \surflet. It This howto gives a short introduction in how to write a \surflet. It
is concentrated on the practical side rather on describing the is concentrated on the practical side rather on describing the
\surflet API in detail to give you instant succes in running your own \surflet API in detail to give you instant succes in running your own
surflets. The \surflet API will be described in the SUnet surflets. See section \ref{sec:surflet-api} for the (technical) API
documentation eventually. description.
\subsection{Introduction}
%\marginpar{\surflets are pieces of code for web site scripting.} %\marginpar{\surflets are pieces of code for web site scripting.}
For those who don't know it already, \surflets are pieces of code that For those who don't know it already, \surflets are pieces of code that
can be executed interactively through a website. There is a \surflet can be executed interactively through a website. There is a \surflet
@ -55,7 +58,7 @@ of the SUnet webserver and scsh. The environment variable
\typew{\$sunet} refers to the top level directory of your sunet \typew{\$sunet} refers to the top level directory of your sunet
installation. On my system this is \name{/home/andreas/sw/sunet}. installation. On my system this is \name{/home/andreas/sw/sunet}.
\section{How to run the SUnet webserver that handles \surflets} \subsection{How to run the SUnet webserver that handles \surflets}
The following sections will show pieces of \surflet code you might The following sections will show pieces of \surflet code you might
want to try out. Therefore you need the SUnet webserver running with want to try out. Therefore you need the SUnet webserver running with
@ -160,12 +163,12 @@ The \typew{--help} option will show you more parameters that you can
adjust, but you won't need them for this howto. adjust, but you won't need them for this howto.
\section{How to send web pages} \subsection{How to send web pages}
This section will discuss some of the various ways in which you can This section will discuss some of the various ways in which you can
send a web page to a browser that contacted your \surflet. send a web page to a browser that contacted your \surflet.
\subsection{My first \surflet} \subsubsection{My first \surflet}
\label{sec:first-surflet} \label{sec:first-surflet}
Traditionally, your first program in any programming language prints Traditionally, your first program in any programming language prints
@ -300,7 +303,7 @@ strings. Everything else like using valid HTML tags or valid
attributes is your responsibility. attributes is your responsibility.
\subsection{Dynamic content} \subsubsection{Dynamic content}
Let's extend our first \surflet example by some dynamic content, \eg Let's extend our first \surflet example by some dynamic content, \eg
by displaying the current time using scsh's \name{format-date} by displaying the current time using scsh's \name{format-date}
@ -348,7 +351,7 @@ unquote feature. Of course, you can build your list in any way you
want; the quasiquote notation is just a convenient way to do it. want; the quasiquote notation is just a convenient way to do it.
\subsection{Several web pages in a row} \subsubsection{Several web pages in a row}
The previous example \surflets only showed one page and finished The previous example \surflets only showed one page and finished
afterwards. Here, we want to present to web pages in a row. We use afterwards. Here, we want to present to web pages in a row. We use
@ -400,11 +403,11 @@ variables keep their modified values, allowing communication between
sessions of the same \surflet.\footnote{If you want to change a sessions of the same \surflet.\footnote{If you want to change a
variable via side effects but you don't want to interfere with other variable via side effects but you don't want to interfere with other
session, you can use \name{set-session-data!} and session, you can use \name{set-session-data!} and
\name{get-session-data}. See the API documentation for further \name{get-session-data}. See the API documentation in section
information.} \ref{sec:surflet-api}for further information.}
\subsection{Begin and end of sessions} \subsubsection{Begin and end of sessions}
So far I don't have mentioned too much details about sessions. The So far I don't have mentioned too much details about sessions. The
reason is, as mentioned before, that the \surflet handler takes of the reason is, as mentioned before, that the \surflet handler takes of the
@ -431,7 +434,7 @@ sending function is \name{send-html} which just sends a web page.
\name{send-html} does not return and does not touch the session of \name{send-html} does not return and does not touch the session of
your \surflet instance. your \surflet instance.
\subsection{Abbreviations in SXML} \subsubsection{Abbreviations in SXML}
\label{sxml-abbrvs} \label{sxml-abbrvs}
The example in subsection ``Several web pages in a row'' wrote down The example in subsection ``Several web pages in a row'' wrote down
@ -456,14 +459,14 @@ The last abbreviation, \name{surflet-form}, is discussed in the next
section. section.
\section{How to write web forms} \subsection{How to write web forms}
The \surflets come along with a libary for easy user interaction. The The \surflets come along with a libary for easy user interaction. The
following subsections will show how to write web forms and how to get following subsections will show how to write web forms and how to get
the data the user has entered. the data the user has entered.
\subsection{Simple web forms} \subsubsection{Simple web forms}
Let's write a \surflet that reads user input and prints it out on the Let's write a \surflet that reads user input and prints it out on the
next page: next page:
@ -605,9 +608,9 @@ user data with \name{input-field-value}.
\end{itemize} \end{itemize}
The complete list of functions that create \name{input-fields} can be The complete list of functions that create \name{input-fields} can be
found in the API. found in the API in section \ref{sec:surflet-api}.
\subsection{Return types other than strings} \subsubsection{Return types other than strings}
\label{subsec:input-return} \label{subsec:input-return}
As the user interaction elements are first class values in a \surflet, As the user interaction elements are first class values in a \surflet,
@ -680,7 +683,7 @@ the user's input, we will get the associated price for the sweet.
Again, this works not only with numbers, but with any arbitrary Scheme Again, this works not only with numbers, but with any arbitrary Scheme
value (\eg functions or records). value (\eg functions or records).
\subsection{Sending error messages} \subsubsection{Sending error messages}
If a user tries to forge a \surflet-URL (\eg by extracting the If a user tries to forge a \surflet-URL (\eg by extracting the
continuation URL from the HTML source and editing it), your \surflet continuation URL from the HTML source and editing it), your \surflet
@ -783,14 +786,15 @@ does not appear in the data the browser sends to the server. Thus,
raise an error which is not a ``real'' error as you migh expect it. raise an error which is not a ``real'' error as you migh expect it.
\subsection{Your own input fields} \subsubsection{Your own input fields}
The \surflet library contains constructors for all input fields that The \surflet library contains constructors for all input fields that
are described in the HTML~2.0 standard. See the \surflet API for a are described in the HTML~2.0 standard. See the \surflet API in
complete list. The \surflet library also allows you to create your section \ref{sec:surflet-api} for a complete list. The \surflet
own input fields, \eg an input field that only accepts valid dates as library also allows you to create your own input fields, \eg an input
its input. This subsection gives you a short overview how to do field that only accepts valid dates as its input. This subsection
this. You will find the details in the \surflet API. gives you a short overview how to do this. You will find the details
in the \surflet API.
Let's have a look at an \surflet that uses its own input field. The Let's have a look at an \surflet that uses its own input field. The
``input field'', called nibble input field, consists of eight check ``input field'', called nibble input field, consists of eight check
@ -923,7 +927,7 @@ again. We create, use and evaluate the nibble input field as we do
with every other input field. with every other input field.
\section{Program flow control} \subsection{Program flow control}
With the techniques shown so far it is rather difficult to create a With the techniques shown so far it is rather difficult to create a
web page that has several different successor webpages rather than web page that has several different successor webpages rather than
@ -934,7 +938,7 @@ the mark after \name{send-html/suspend} has returned. The other
method is to bind a callback function to each link that is called when method is to bind a callback function to each link that is called when
the user selects the link. This section shows both methods. the user selects the link. This section shows both methods.
\subsection{Dispatching to more than one successor web page} \subsubsection{Dispatching to more than one successor web page}
The basic idea of dispatching is to add a mark to a link and evaluate The basic idea of dispatching is to add a mark to a link and evaluate
it after the user has clicked on a link and \name{send-html/suspend} it after the user has clicked on a link and \name{send-html/suspend}
@ -1037,7 +1041,7 @@ shortly. Of course, it is your choice if you want to use
\name{case-returned-via} or explicitly \name{returned-via}. \name{case-returned-via} or explicitly \name{returned-via}.
\subsection{Annotated dispatching} \subsubsection{Annotated dispatching}
The approach shown in the previous subsection has one major drawback: The approach shown in the previous subsection has one major drawback:
the meaning of an address becomes clear only when you look at the the meaning of an address becomes clear only when you look at the
@ -1127,7 +1131,7 @@ via which the user has left the web page. \name{returned-via} returns
created with this address (which is not really possible in this created with this address (which is not really possible in this
example). example).
\subsection{Callbacks} \subsubsection{Callbacks}
The other method to lead to different successor web pages is using The other method to lead to different successor web pages is using
callbacks. A callback is a function that is called if the user leaves callbacks. A callback is a function that is called if the user leaves
@ -1212,7 +1216,7 @@ calling a function with several arguments and of different amount each
time is also possible if you only use a single function for the time is also possible if you only use a single function for the
callback. callback.
\section{Data management} \subsection{Data management}
When you write web programs, there are usually two kinds of data that When you write web programs, there are usually two kinds of data that
you use: data that is local to each instance of a \surflet, \eg the you use: data that is local to each instance of a \surflet, \eg the
@ -1341,13 +1345,13 @@ endless states of the \surflet.
\name{cancel} shows the final page with the amount of clicks \name{cancel} shows the final page with the amount of clicks
performed. performed.
\section{My own SXML} \subsection{My own SXML}
Section \ref{sec:SXML} introduced SXML, the way how \surflets Section \ref{sec:SXML} introduced SXML, the way how \surflets
represent HTML. This section will show you, how you can create your represent HTML. This section will show you, how you can create your
own rules to translate from SXML to HTML. own rules to translate from SXML to HTML.
\subsection{Terms and theoretical background} \subsubsection{Terms and theoretical background}
This subsection will introduce the main concepts of the translation This subsection will introduce the main concepts of the translation
process and some necessary terms we will use in the following. process and some necessary terms we will use in the following.
@ -1401,7 +1405,7 @@ standard conversion rule set the text conversion rule performs HTML
escaping, \eg for the ampersand (\&). escaping, \eg for the ampersand (\&).
\section{Outlook} \subsubsection{Outlook}
More to come soon about \surflets consisting of different parts and More to come soon about \surflets consisting of different parts and
individual SXML. individual SXML.

9
doc/latex/surflets.tex
View File

@ -3,9 +3,12 @@
\newcommand{\typew}[1]{\texttt{#1}} \newcommand{\typew}[1]{\texttt{#1}}
The \surflet server enables you to write server side scripted web The \surflet server enables you to write server side scripted web
programs in Scheme. Currently, there is only the howto available. programs in Scheme.
The complete API is supposed to come soon. There are lot of example %Currently, there is only the howto available.
files in \typew{httpd/surflet/webserver/root/surflets} from which you %The complete API is supposed to come soon.
There are lot of example files in
\typew{scheme/httpd/surflet/webserver/root/surflets} from which you
can copy freely. can copy freely.
\input{surflethowto} \input{surflethowto}
\input{surfletapi}