(c) Software Lab. Alexander Burger
This document presents an introduction to writing browser-based applications in Pico Lisp.
It concentrates on the XHTML/CSS GUI-Framework (as opposed to the previous Java-AWT, Java-Swing and Plain-HTML frameworks), which is easier to use, more flexible in layout design, and does not depend on plugins, JavaScript or cookies.
It works also in browsers which do not know about CSS or JavaScript. All examples were tested using the w3m text browser.
For basic informations about the Pico Lisp system please look at the Pico Lisp Reference and the Pico Lisp Tutorial. Knowledge of HTML, and a bit of CSS and HTTP is assumed.
You can use Pico Lisp to generate static HTML pages. This does not make much sense in itself, because you could directly write HTML code as well, but it forms the base for interactive applications, and allows us to introduce the application server and other fundamental concepts.
To begin with a minimal application, please enter the following two lines into a generic source file named "project.l" in the Pico Lisp installation directory
########################################################################
(html 0 "Hello" "lib.css" NIL
"Hello World!" )
########################################################################
(We will modify and use this file in all following examples and experiments)
Open a second terminal window, and start a Pico Lisp application server
$ ./p dbg.l lib/http.l lib/xhtml.l lib/form.l -'server 8080 "project.l"'
No prompt appears. The server just sits, and waits for connections. You can
stop it later by hitting Ctrl-C in that terminal, or by executing
'killall picolisp' in some other window.
(In the following, we assume that this HTTP server is up and running)
Now open the URL 'http://localhost:8080' with your
browser. You should see an empty page with a single line of text.
The above line loads the debugger ("dbg.l"), the HTTP server code ("lib/http.l"), the XHTML functions ("lib/xhtml.l") and the input form framework ("lib/form.l", will be needed later for interactive forms).
Then the server function is called with a port number and a
default URL. It will listen on that port for incoming HTTP requests in an
endless loop. Whenever a GET request arrives on port 8080, the file "project.l"
will be (load)ed, causing the
evaluation (= execution) of all its Lisp expressions.
During that execution, all data written to the current output channel is sent directly to to the browser. The code in "project.l" is responsible to produce HTML (or anything else the browser can understand).
html FunctionIn principle you could write "project.l" as a sequence of print statements
########################################################################
(prinl "HTTP/1.1 200 OK^M")
(prinl "Content-Type: text/html; charset=utf-8")
(prinl "^M")
(prinl "<html>")
(prinl "Hello World!")
(prinl "</html>")
########################################################################
but using the html function is much more convenient.
Moreover, html is nothing more than a printing function.
You can see this easily if you connect a Pico Lisp Shell (psh) to
the server process, and enter the html statement
$ bin/psh 8080
: (html 0 "Hello" "lib.css" NIL "Hello World!")
HTTP/1.1 200 OK
Server: PicoLisp
Connection: close
Cache-Control: max-age=0
Cache-Control: no-cache
Content-Type: text/html; charset=utf-8
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Hello</title>
<base href="http://localhost:8080/"/>
<link rel="stylesheet" href="http://localhost:8080/lib.css" type="text/css"/>
</head>
<body>Hello World!</body>
</html>
-> </html>
:
These are the arguments to html:
0: A max-age value for cache-control (in seconds, zero means
"no-cache"). You might pass a higher value for pages that change seldom, or
NIL for no cache-control at all.
"Hello": The page title.
"lib.css": A CSS-File name. Pass NIL if you do not want
to use any CSS-File, or a list of file names if you want to give more than one
CSS-File.
NIL: A CSS style attribute specification (see the description
of CSS Attributes below). It will be passed to the
body tag.
After these four arguments, an arbitrary number of expressions may follow. They form the body of the resulting page, and are evaluated according to a special rule. This rule is slightly different from the evaluation of normal Lisp expressions:
Therefore, our source file might as well be written as:
########################################################################
(html 0 "Hello" "lib.css" NIL
(prinl "Hello World!") )
########################################################################
The most typical printing statements will be some HTML-tag
########################################################################
(html 0 "Hello" "lib.css" NIL
(<h1> NIL "Hello World!")
(<br> "This is some text.")
(ht:Prin "And this is a number: " (+ 1 2 3)) )
########################################################################
<h1> and <br> are tag functions.
<h1> takes a CSS attribute as its first argument.
Note the use of ht:Prin instead of prin.
ht:Prin should be used for all direct printing in HTML pages,
because it takes care to escape special characters.
The html function above and many of the
HTML tag functions accept a CSS attribute specification.
This may be either an atom, a cons pair, or a list of cons pairs. We demonstrate
the effects with the <h1> tag function.
An atom (usually a symbol or a string) is taken as a CSS class name
: (<h1> 'foo "Title")
<h1 class="foo">Title</h1>
For a cons pair, the CAR is taken as an attribute name, and the
CDR as the attribute's value
: (<h1> '(id . bar) "Title")
<h1 id="bar">Title</h1>
Consequently, a list of cons pairs gives an arbitrary number of attribute-value pairs
: (<h1> '((id . "abc") (lang . "de")) "Title")
<h1 id="abc" lang="de">Title</h1>
All pre-defined XHTML tag functions can be found in "lib/xhtml.l". We recommend to look at their sources, and to experiment by executing them at a Pico Lisp prompt and by pressing the browser's "Reload" button after editing the "project.l" file.
For a suitable Pico Lisp prompt, either execute (in a separate terminal
window) the Pico Lisp Shell (psh) command (works only if the
application server is running)
$ bin/psh 8080
:
or start the interpreter stand-alone, with "lib/xhtml.l" loaded
$ ./p dbg.l lib/http.l lib/xhtml.l
:
Note that for all these tag functions the above tag body evaluation rule applies.
Most tag functions are simple and straightforward. Some of them just print their arguments
: (<br> "Hello world")
Hello world<br/>
: (<em> "Hello world")
<em>Hello world</em>
while most of them take a CSS attribute specification
as their first argument (like the <h1> tag above)
: (<div> 'main "Hello world")
<div class="main">Hello world</div>
: (<p> NIL "Hello world")
<p>Hello world</p>
: (<p> 'info "Hello world")
<p class="info">Hello world</p>
All of these functions take an arbitrary number of arguments, and may nest to an arbitrary depth (as long as the resulting HTML is legal)
: (<div> 'main
(<h1> NIL "Head")
(<p> NIL
(<br> "Line 1")
"Line"
(<nbsp>)
(+ 1 1) ) )
<div class="main"><h1>Head</h1>
<p>Line 1<br/>
Line 2</p>
</div>
HTML-lists, implemented by the <ol> and
<ul> tags, let you define hierarchical structures. You might
want to paste the following code into your copy of "project.l":
########################################################################
(html 0 "Unordered List" "lib.css" NIL
(<ul> NIL
(<li> NIL "Item 1")
(<li> NIL
"Sublist 1"
(<ul> NIL
(<li> NIL "Item 1-1")
(<li> NIL "Item 1-2") ) )
(<li> NIL "Item 2")
(<li> NIL
"Sublist 2"
(<ul> NIL
(<li> NIL "Item 2-1")
(<li> NIL "Item 2-2") ) )
(<li> NIL "Item 3") ) )
########################################################################
Here too, you can put arbitrary code into each node of that tree, including other tag functions.
Like the hierarchical structures with the list functions, you can generate
two-dimensional tables with the <table> and
<row> functions.
The following example prints a table of numbers and their squares:
########################################################################
(html 0 "Table" "lib.css" NIL
(<table> NIL NIL NIL
(for (N 1 (>= 10 N) (inc N)) # A table with 10 rows
(<row> NIL N (prin (* N N))) ) ) ) # and 2 columns
########################################################################
The first argument to <table> is the usual CSS attribute,
the second an optional title ("caption"), and the third an optional list
specifying the column headers. In that list, you may supply a list for a each
column, with a CSS attribute in its CAR, and a tag body in its CDR for the
contents of the column header.
The body of <table> contains calls to the
<row> function. This function is special in that each
expression in its body will go to a separate column of the table. If both for
the column header and the row function an CSS attribute is given, they will be
combined by a space and passed to the HTML <td> tag. This
permits distinct CSS specifications for each column and row.
As an extension of the above table example, let's pass some attributes for
the table itself (not recommended - better define such styles in a CSS file and
then just pass the class name to <table>), right-align both
columns, and print each row in a blue color
########################################################################
(html 0 "Table" "lib.css" NIL
(<table>
'((width . "200px") (style . "border: dotted 1px;")) # table style
"Square Numbers" # caption
'((align "Number") (align "Square")) # 2 headers
(for (N 1 (>= 10 N) (inc N)) # 10 rows
(<row> 'blue N (prin (* N N))) ) ) ) # 2 columns
########################################################################
If you wish to concatenate two or more cells in a table, so that a single
cell spans several columns, you can pass the symbol '-' for the
additional cell data to <row>. This will cause the data given
to the left of the '-' symbols to expand to the right.
You can also directly specify table structures with the simple
<th>, <tr> and <td> tag
functions.
If you just need a two-dimensional arrangement of components, the even
simpler <grid> function might be convenient:
########################################################################
(html 0 "Grid" "lib.css" NIL
(<grid> 3
"A" "B" "C"
123 456 789 ) )
########################################################################
It just takes a specification for the number of colums (here: 3) as its first argument, and then a single expression for each cell. Instead of a number, you can also pass a list of CSS atributes. Then the length of that list will determine the number of columns. You can change the second line in the above example to
(<grid> '(NIL NIL right)
Then the third column will be right aligned.
The two most powerful tag functions are <menu> and
<tab>. Used separately or in combination, they form a
navigation framework with
The following example is not very useful, because the URLs of all items link to the same "project.l" page, but it should suffice to demonstrate the functionality:
########################################################################
(html 0 "Menu+Tab" "lib.css" NIL
(<div> '(id . menu)
(<menu>
(T "Start" "project.l") # Direct action
(NIL (<hr>)) # Plain HTML
("Item 1" # Sub-menu 1
("Subitem 1.1" "project.l")
("Subitem 1.2" "project.l") )
("Item 2" # Sub-menu 2
("Subitem 2.1" "project.l")
("Subitem 2.2" "project.l") ) ) )
(<div> '(id . main)
(<h1> NIL "Menu+Tab")
(<tab>
("Tab1"
(<h3> NIL "This is Tab 1") )
("Tab2"
(<h3> NIL "This is Tab 2") )
("Tab3"
(<h3> NIL "This is Tab 3") ) ) ) )
########################################################################
<menu> takes a sequence of menu items. Each menu item is a
list, with its CAR either
NIL: In that case, it is not an active menu item, and the rest
of the list may consist of arbitrary code (usually HTML tags).
T: In that case, the menu item will specify a direct action
(instead of opening a sub-menu), where the second list element gives the item's
name, the third element an URL, and the fourth (optional) element an URL-target.
<tab> takes a list of sub-pages. Each page is simply a tab
name, followed by arbitrary code (typically HTML tags).
Note that only a single menu and a single tab may be active at the same time.
In HTML, the only possibility for user input is via <form>
and <input> elements, using the HTTP POST method
to communicate with the server.
"lib/xhtml.l" supplies a function called <post>, and a
collection of input tag functions, which allow direct programming of HTML forms.
We will supply only one simple example:
########################################################################
(html 0 "Simple Form" "lib.css" NIL
(<post> NIL "project.l"
(<field> 10 '*Text)
(<submit> "Save") ) )
########################################################################
This associates a text input field with a global variable *Text.
The field displays the current value of *Text, and pressing the
submit button causes a reload of "project.l" with *Text set to any
string entered by the user.
An application program could then use that variable to do something useful, for example store its value in a database.
The problem with such a straightforward use of forms is that
POST
request spawns an individual process on the server, which sets the global
variables to their new values, generates the HTML page, and terminates
thereafter. The application state has to be passed along explicitly, e.g. using
<hidden> tags.
Though we wrote a few applications in that style, we recommend the GUI framework provided by "lib/form.l". It does not need any variables for the client/server communication, but implements a class hierarchy of GUI components for the abstraction of application logic, button actions and data linkage.
First of all, we need to establish a persistent environment on the server, to handle each individual session (for each connected client).
Technically, this is just a child process of the server we started above, which does not terminate immediately after it sent its
page to the browser. It is achieved by calling the app function
somewhere on the application's startup page.
########################################################################
(app) # Start a session
(html 0 "Simple Session" "lib.css" NIL
(<post> NIL "project.l"
(<field> 10 '*Text)
(<submit> "Save") ) )
########################################################################
Nothing else changed from the previous example. However, when you connect your browser and then look at the terminal window where you started the application server, you'll notice a colon, the Pico Lisp prompt
$ ./p dbg.l lib/http.l lib/xhtml.l lib/form.l -'server 8080 "project.l"'
:
and tools like the Unix ps utility will tell you that two
picolisp processes are running now, the first being the parent of
the second.
If you enter some text, say "abcdef", into the text field in the browser
window, press the submit button, and inspect the Lisp *Text
variable,
: *Text
-> abcdef
you see that we now have a dedicated Pico Lisp process, "connected" to the client.
You can terminate this process (like any interactive Pico Lisp) by hitting
RETURN on an empty line. Otherwise, it will terminate by itself if
no other browser requests arrive within a default timeout period of 15 minutes.
To start a (non-debug) production version, the server is commonly started
without "dbg.l", and with -wait
$ ./p lib/http.l lib/xhtml.l lib/form.l -'server 8080 "project.l"' -wait
In that way, no command line prompt appears when a client connects.
Now that we have a persistent session for each client, we can set up an active GUI framework.
This is done by wrapping the call to the html function with
action. Inside the body of html can be - in addition
to all other kinds of tag functions - one or more calls to form
########################################################################
(app) # Start session
(action # Action handler
(html 0 "Form" "lib.css" NIL # HTTP/HTML protocol
(form NIL # Form
(gui 'a '(+TextField) 10) # Text Field
(gui '(+Button) "Print" # Button
'(msg (val> (: home a))) ) ) ) )
########################################################################
Note that there is no longer a global variable like *Text to
hold the contents of the input field. Instead, we gave a local, symbolic name
'a' to a +TextField component
(gui 'a '(+TextField) 10) # Text Field
Other components can refer to it
'(msg (val> (: home a)))
(: home) is always the form which contains this GUI component.
So (: home a) evaluates to the component 'a' in the
current form. As msg prints its argument to standard error, and the
val> method retrieves the current contents of a component, we
will see on the console the text typed into the text field when we press the
button.
An action without embedded forms - or a
form without a surrounding action - does not make much
sense by itself. Inside html and form, however, calls
to HTML functions (and any other Lisp functions, for that matter) can be freely
mixed.
In general, a typical page may have the form
(action # Action handler
(html .. # HTTP/HTML protocol
(<h1> ..) # HTML tags
(form NIL # Form
(<h3> ..)
(gui ..) # GUI component(s)
(gui ..)
.. )
(<h2> ..)
(form NIL # Another form
(<h3> ..)
(gui ..) # GUI component(s)
.. )
(<br> ..)
.. ) )
HTTP has only two methods to change a browser window: GET and
POST. We employ these two methods in a certain defined, specialized
way:
GET means, a new page is being constructed. It is used
when a page is visited for the first time, usually by entering an URL into the
browser's address field, or by clicking on a link (which is often a sub-menu item or tab).
POST is always directed to the same page. It is
triggered by a button press, updates the corresponding form's data structures,
and executes that button's action code.
A button's action code can do almost anything: Read and modify the contents
of input fields, communicate with the database, display alerts and dialogs, or
even fake the POST request to a GET, with the effect
of showing a completely different document.
GET builds up all GUI components on the server. These components
are objects which encapsulate state and behavior of the HTML page in the
browser. Whenever a button is pressed, the page is reloaded via a
POST request. Then - before any output is sent to the browser - the
action function takes control. It performs error checks on all
components, processes possible user input on the HTML page, and stores the
values in correct format (text, number, date, object etc.) in each component.
The following silly example displays two text fields. If you enter some text into the "Source" field, you can copy it in upper or lower case to the "Destination" field by pressing one of the buttons
########################################################################
(app)
(action
(html 0 "Case Conversion" "lib.css" NIL
(form NIL
(<grid> 2
"Source" (gui 'src '(+TextField) 30)
"Destination" (gui 'dst '(+Lock +TextField) 30) )
(gui '(+Button) "Upper Case"
'(set> (: home dst)
(uppc (val> (: home src))) ) )
(gui '(+Button) "Lower Case"
'(set> (: home dst)
(lowc (val> (: home src))) ) ) ) ) )
########################################################################
The +Lock prefix class in the "Destination" field makes that
field read-only. The only way to get some text into that field is by using one
of the buttons.
Because an action code runs before html has a chance to output
an HTTP header, it can abort the current page and present something different to
the user. This might, of course, be another HTML page, but would not be very
interesting as a normal link would suffice. Instead, it can cause the download
of dynamically generated data.
The next example shows a text area and two buttons. Any text entered into the text area is exported either as a text file via the first button, or a PDF document via the second button
########################################################################
(load "lib/ps.l")
(app)
(action
(html 0 "Export" "lib.css" NIL
(form NIL
(gui '(+TextField) 30 8)
(gui '(+Button) "Text"
'(let Txt (tmp "export.txt")
(out Txt (prinl (val> (: home gui 1))))
(url Txt) ) )
(gui '(+Button) "PDF"
'(psOut NIL "foo"
(a4)
(indent 40 40)
(down 60)
(hline 3)
(font (14 . "Times-Roman")
(ps (val> (: home gui 1))) )
(hline 3)
(page) ) ) ) ) )
########################################################################
(a text area is built when you supply two numeric arguments (columns and
rows) to a +TextField class)
The action code of the first button creates a temporary file (i.e. a file
named "export.txt" in the current process's temporary space), prints the value
of the text area (this time we did not bother to give it a name, we simply refer
to it as the form's first gui list element) into that file, and then calls the
url function with the file name.
The second button uses the PostScript library "lib/ps.l" to create a
temporary file "foo.pdf". Here, the temporary file creation and the call to the
url function is hidden in the internal mechanisms of
psOut. The effect is that the browser receives a PDF document and
displays it.
Alerts and dialogs are not really what they used to be ;-)
They do not "pop up". In this framework, they are just a kind of simple-to-use, pre-fabricated form. They can be invoked by a button's action code, and appear always on the current page, immediately preceding the form which created them.
Let's look at an example which uses two alerts and a dialog. In the beginning, it displays a simple form, with a locked text field, and two buttons
########################################################################
(app)
(action
(html 0 "Alerts and Dialogs" "lib.css" NIL
(form NIL
(gui '(+Init +Lock +TextField) "Initial Text" 20 "My Text")
(gui '(+Button) "Alert"
'(alert "This is an alert " (okButton)) )
(gui '(+Button) "Dialog"
'(dialog NIL
(<br> "This is a dialog.")
(<br>
"You can change the text here "
(gui '(+Init +TextField) (val> (: top 1 gui 1)) 20) )
(<br> "and then re-submit it to the form.")
(gui '(+Button) "Re-Submit"
'(alert "Are you sure? "
(yesButton
'(prog
(set> (: home top 2 gui 1)
(val> (: home top 1 gui 1)) )
(dispose (: home top 1)) ) )
(noButton) ) )
(cancelButton) ) ) ) ) )
########################################################################
The +Init prefix class initialises the "My Text" field with the
string "Initial Text". As the field is locked, you cannot modify this value
directly.
The first button brings up an alert saying "This is an alert.". You can dispose it by pressing "Ok".
The second button brings up a dialog with an editable text field, containing a copy of the value from the form's locked text field. You can modify this value, and send it back to the form, if you press "Re-Submit" and aswer "Yes" to the "Are you sure?" alert.
Now let's forget our "project.l" test file for a moment, and move on to a more substantial and practical, stand-alone, example. Using what we have learned so far, we want to build a simple bignum calculator. ("bignum" because Pico Lisp can only do bignums)
It uses a single form, a single numeric input field, and lots of buttons. It can be found in the Pico Lisp distribution in "misc/calc.l", together with a directly executable wrapper script "misc/calc".
To use it, change to the Pico Lisp installation directory, and start it as
$ misc/calc
If you want to use it from other directories too, change the two relative path names in the first line to absolute paths. We recommend symbolic links in some global directories, as described in the Scripting section of the Pico Lisp Tutorial.
If you like to get a Pico Lisp prompt for debugging, start it instead as
$ ./p dbg.l misc/calc.l -main -go
Then - as before - point your browser to 'http://localhost:8080'.
*** TO BE CONTINUED ***
The most recent version of this document can be found on the Pico Lisp Download page, and in the current development release of Pico Lisp.