(c) Software Lab. Alexander Burger, Mattias Sundblad
This document presents an introduction to writing browser-based applications in PicoLisp.
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 plug-ins, JavaScript, cookies or CSS.
A plain HTTP/HTML GUI has various advantages: It runs on any browser, and can be fully driven by scripts ("@lib/scrape.l").
To be precise: CSS can be used to enhance the layout. And browsers with JavaScript will respond faster and smoother. But this framework works just fine in browsers which do not know anything about CSS or JavaScript. All examples were also tested using the w3m text browser.
For basic informations about the PicoLisp system please look at the PicoLisp Reference and the PicoLisp Tutorial. Knowledge of HTML, and a bit of CSS and HTTP is assumed.
The examples assume that PicoLisp was started from a global installation (see Installation).
You can use PicoLisp 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 PicoLisp installation directory.
########################################################################
(html 0 "Hello" "@lib.css" NIL
"Hello World!" )
########################################################################
(We will modify and use this file in all following examples and experiments. Whenever you find such a program snippet between hash ('#') lines, just copy and paste it into your "project.l" file, and press the "reload" button of your browser to view the effects)
Open a second terminal window, and start a PicoLisp application server
$ pil @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 pil' 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 (via the '+' switch), the HTTP server code ("@lib/http.l"), the XHTML functions ("@lib/xhtml.l") and the input form framework ("@lib/form.l", it will be needed later for interactive forms).
Then the -server function is called (a front-end to
server) 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 the browser. The code in "project.l" is responsible to produce HTML (or anything else the browser can understand).
The PicoLisp application server uses a slightly specialized syntax when communicating URLs to and from a client. The "path" part of an URL - which remains when
(load)ed. This
is the most common case, and we use it in our example "project.l".
*Mimes, the file is sent to the client with mime-type and
max-age values taken from that table.
An application is free to extend or modify the *Mimes table with
the mime function. For example
(mime "doc" "application/msword" 60)
defines a new mime type with a max-age of one minute.
Argument values in URLs, following the path and the question mark, are encoded in such a way that Lisp data types are preserved:
In that way, high-level data types can be directly passed to functions encoded in the URL, or assigned to global variables before a file is loaded.
It is, of course, a huge security hole that - directly from the URL - any
Lisp source file can be loaded, and any Lisp function can be called. For that
reason, applications must take care to declare exactly which files and functions
are to be allowed in URLs. The server checks a global variable *Allow, and - when its value is
non-NIL - denies access to anything that does not match its
contents.
Normally, *Allow is not manipulated directly, but set with the
allowed and allow functions
(allowed ("app/")
"!start" "!stop" "@lib.css" "!psh" )
This is usually called at the beginning of an application, and allows access to the directory "app/", to the functions 'start', 'stop' and 'psh', and to the file "@lib.css".
Later in the program, *Allow may be dynamically extended with
allow
(allow "!foo")
(allow "newdir/" T)
This adds the function 'foo', and the directory "newdir/", to the set of allowed items.
For a variety of security checks (most notably for using the psh
function, as in some later examples) it is necessary to create a file named
".pw" in the PicoLisp installation directory. This file should contain a single
line of arbitrary data, to be used as a password for identifying local
resources.
The recommeded way to create this file is to call the pw
function, defined in "@lib/http.l"
$ pil @lib/http.l -'pw 12' -bye
Please execute this command.
html FunctionNow back to our "Hello World" example. In principle, you could write "project.l" as a sequence of print statements
########################################################################
(prinl "HTTP/1.0 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 PicoLisp Shell (psh) to
the server process (you must have generated a ".pw" file for
this), and enter the html statement
$ /usr/lib/picolisp/bin/psh 8080
: (html 0 "Hello" "@lib.css" NIL "Hello World!")
HTTP/1.0 200 OK
Server: PicoLisp
Date: Fri, 29 Dec 2006 07:28:58 GMT
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" type="text/css" href="http://localhost:8080/@lib.css"/>
</head>
<body>Hello World!</body>
</html>
-> </html>
: # (type Ctrl-D here to terminate PicoLisp)
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 print statements will be some HTML-tags:
########################################################################
(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 a set 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 a bit, by executing them at a PicoLisp prompt, or by pressing the browser's "Reload" button after editing the "project.l" file.
For a suitable PicoLisp prompt, either execute (in a separate terminal
window) the PicoLisp Shell (psh) command (works only if the
application server is running, and you did generate a ".pw"
file)
$ /usr/lib/picolisp/bin/psh 8080
:
or start the interpreter stand-alone, with "@lib/xhtml.l" loaded
$ pil @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 10 # 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 an alternating red and 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 10 # 10 rows
(<row> (xchg '(red) '(blue)) # red or blue
N # 2 columns
(prin (* N N) ) ) ) ) )
########################################################################
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 columns (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 attributes. 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>
("Item" "project.l") # Top level item
(NIL (<hr>)) # Plain HTML
(T "Submenu 1" # Submenu
("Subitem 1.1" "project.l")
(T "Submenu 1.2"
("Subitem 1.2.1" "project.l")
("Subitem 1.2.2" "project.l")
("Subitem 1.2.3" "project.l") )
("Subitem 1.3" "project.l") )
(T "Submenu 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: The entry is not an active menu item, and the rest of the
list may consist of arbitrary code (usually HTML tags).
T: The second element is taken as a submenu name, and a click
on that name will open or close the corresponding submenu. The rest of the list
recursively specifies the submenu items (may nest to arbitrary depth).
<tab> takes a list of subpages. 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" defines 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
<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 in the application's startup code.
########################################################################
(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 PicoLisp prompt
$ pil @lib/http.l @lib/xhtml.l @lib/form.l --server 8080 project.l +
:
Tools like the Unix ps utility will tell you that now two
picolisp processes are running, 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 PicoLisp process, "connected" to the client.
You can terminate this process (like any interactive PicoLisp) by hitting
Ctrl-D on an empty line. Otherwise, it will terminate by itself if
no other browser requests arrive within a default timeout period of 5 minutes.
To start a (non-debug) production version, the server is commonly started
without the '+' flag, and with -wait
$ pil @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> ..)
.. ) )
gui FunctionThe most prominent function in a form body is gui.
It is the workhorse of GUI construction.
Outside of a form body, gui is undefined.
Otherwise, it takes an optional alias name, a list of classes, and additional
arguments as needed by the constructors of these classes. We saw this example
before
(gui 'a '(+TextField) 10) # Text Field
a' is an alias name for a component of type
(+TextField). The numeric argument 10 is passed to the
text field, specifying its width. See the chapter on GUI
Classes for more examples.
During a GET request, gui is basically a front-end to
new. It builds a component, stores it in the internal structures of
the current form, and initializes it by sending the init>
message to the component. Finally, it sends it the show>
message, to produce HTML code and transmit it to the browser.
During a POST request, gui does not build any new components.
Instead, the existing components are re-used. So gui does not have
much more to do than sending the show> message to a component.
HTTP has only two methods to change a browser window: GET and POST. We employ these two methods in a certain defined, specialized way:
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 (See Switching URLs).
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 state of a form is preserved over time. When the user returns to a previous page with the browser's BACK button, that state is reactivated, and may be POSTed again.
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 '(+JS +Button) "Upper Case"
'(set> (: home dst)
(uppc (val> (: home src))) ) )
(gui '(+JS +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 NIL "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 NIL "Are you sure? "
(yesButton
'(set> (: home top 2 gui 1)
(val> (: home top 1 gui 1)) ) )
(noButton) ) )
(cancelButton) ) ) ) ) )
########################################################################
The +Init prefix class
initializes 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 answer "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 PicoLisp can do only bignums)
It uses a single form, a single numeric input field, and lots of buttons. It can be found in the PicoLisp distribution (e.g. under "/usr/share/picolisp/") in "misc/calc.l", together with a directly executable wrapper script "misc/calc".
To use it, change to the PicoLisp installation directory, and start it as
$ misc/calc
or call it with an absolute path, e.g.
$ /usr/share/picolisp/misc/calc
If you like to get a PicoLisp prompt for inspection, start it instead as
$ pil misc/calc.l -main -go +
Then - as before - point your browser to 'http://localhost:8080'.
The code for the calculator logic and the GUI is rather straightforward. The
entry point is the single function calculator. It is called
directly (as described in URL Syntax) as the server's
default URL, and implicitly in all POST requests. No further file access is
needed once the calculator is running.
Note that for a production application, we inserted an allow-statement (as recommended by the Security chapter)
(allowed NIL "!calculator" "@lib.css")
at the beginning of "misc/calc.l". This will restrict external access to that single function.
The calculator uses three global variables, *Init,
*Accu and *Stack. *Init is a boolean flag
set by the operator buttons to indicate that the next digit should initialize
the accumulator to zero. *Accu is the accumulator. It is always
displayed in the numeric input field, accepts user input, and it holds the
results of calculations. *Stack is a push-down stack, holding
postponed calculations (operators, priorities and intermediate results) with
lower-priority operators, while calculations with higher-priority operators are
performed.
The function digit is called by the digit buttons, and adds
another digit to the accumulator.
The function calc does an actual calculation step. It pops the
stack, checks for division by zero, and displays an error alert if necessary.
operand processes an operand button, accepting a function and a
priority as arguments. It compares the priority with that in the top-of-stack
element, and delays the calculation if it is less.
finish is used to calculate the final result.
The calculator function has one numeric input field, with a
width of 60 characters
(gui '(+Var +NumField) '*Accu 60)
The +Var prefix class
associates this field with the global variable *Accu. All changes
to the field will show up in that variable, and modification of that variable's
value will appear in the field.
The square root operator button has an
+Able prefix class
(gui '(+Able +JS +Button) '(ge0 *Accu) (char 8730)
'(setq *Accu (sqrt *Accu)) )
with an argument expression which checks that the current value in the accumulator is positive, and disables the button if otherwise.
The rest of the form is just an array (grid) of buttons, encapsulating all
functionality of the calculator. The user can enter numbers into the input
field, either by using the digit buttons, or by directly typing them in, and
perform calculations with the operator buttons. Supported operations are
addition, subtraction, multiplication, division, sign inversion, square root and
power (all in bignum integer arithmetic). The 'C' button just
clears the accumulator, while the 'A' button also clears all
pending calculations.
All that in 53 lines of code!
Charts are virtual components, maintaining the internal representation of two-dimensional data.
Typically, these data are nested lists, database selections, or some kind of dynamically generated tabular information. Charts make it possible to view them in rows and columns (usually in HTML tables), scroll up and down, and associate them with their corresponding visible GUI components.
In fact, the logic to handle charts makes up a substantial part of the whole framework, with large impact on all internal mechanisms. Each GUI component must know whether it is part of a chart or not, to be able to handle its contents properly during updates and user interactions.
Let's assume we want to collect textual and numerical data. We might create a table
########################################################################
(app)
(action
(html 0 "Table" "@lib.css" NIL
(form NIL
(<table> NIL NIL '((NIL "Text") (NIL "Number"))
(do 4
(<row> NIL
(gui '(+TextField) 20)
(gui '(+NumField) 10) ) ) )
(<submit> "Save") ) ) )
########################################################################
with two columns "Text" and "Number", and four rows, each containing a
+TextField and a +NumField.
You can enter text into the first column, and numbers into the second. Pressing the "Save" button stores these values in the components on the server (or produces an error message if a string in the second column is not a legal number).
There are two problems with this solution:
: (val> (get *Top 'gui 2)) # Value in the first row, second column
-> 123
A chart can handle these things:
########################################################################
(app)
(action
(html 0 "Chart" "@lib.css" NIL
(form NIL
(gui '(+Chart) 2) # Inserted a +Chart
(<table> NIL NIL '((NIL "Text") (NIL "Number"))
(do 4
(<row> NIL
(gui 1 '(+TextField) 20) # Inserted '1'
(gui 2 '(+NumField) 10) ) ) ) # Inserted '2'
(<submit> "Save") ) ) )
########################################################################
Note that we inserted a +Chart component before the GUI
components which should be managed by the chart. The argument '2' tells the
chart that it has to expect two columns.
Each component got an index number (here '1' and '2') as the first argument
to gui, indicating the column into which this component should go
within the chart.
Now - if you entered "a", "b" and "c" into the first, and 1, 2, and 3 into
the second column - we can retrieve the chart's complete contents by sending it
the val> message
: (val> (get *Top 'chart 1)) # Retrieve the value of the first chart
-> (("a" 1) ("b" 2) ("c" 3))
BTW, a more convenient function is chart
: (val> (chart)) # Retrieve the value of the current chart
-> (("a" 1) ("b" 2) ("c" 3))
chart can be used instead of
the above construct when we want to access the "current" chart, i.e. the chart
most recently processed in the current form.
To enable scrolling, let's also insert two buttons. We use the pre-defined
classes +UpButton and
+DnButton
########################################################################
(app)
(action
(html 0 "Scrollable Chart" "@lib.css" NIL
(form NIL
(gui '(+Chart) 2)
(<table> NIL NIL '((NIL "Text") (NIL "Number"))
(do 4
(<row> NIL
(gui 1 '(+TextField) 20)
(gui 2 '(+NumField) 10) ) ) )
(gui '(+UpButton) 1) # Inserted two buttons
(gui '(+DnButton) 1)
(----)
(<submit> "Save") ) ) )
########################################################################
to scroll down and up a single (argument '1') line at a time.
Now it is possible to enter a few rows of data, scroll down, and continue. It is not necessary (except in the beginning, when the scroll buttons are still disabled) to press the "Save" button, because any button in the form will send changes to the server's internal structures before any action is performed.
As we said, a chart is a virtual component to edit two-dimensional data. Therefore, a chart's native data format is a list of lists: Each sublist represents a single row of data, and each element of a row corresponds to a single GUI component.
In the example above, we saw a row like
("a" 1)
being mapped to
(gui 1 '(+TextField) 20)
(gui 2 '(+NumField) 10)
Quite often, however, such a one-to-one relationship is not desired. The internal data structures may have to be presented in a different form to the user, and user input may need conversion to an internal representation.
For that, a chart accepts - in addition to the "number of columns" argument - two optional function arguments. The first function is invoked to 'put' the internal representation into the GUI components, and the second to 'get' data from the GUI into the internal representation.
A typical example is a chart displaying customers in a database. While the internal representation is a (one-dimensional) list of customer objects, 'put' expands each object to a list with, say, the customer's first and second name, telephone number, address and so on. When the user enters a customer's name, 'get' locates the matching object in the database and stores it in the internal representation. In the following, 'put' will in turn expand it to the GUI.
For now, let's stick with a simpler example: A chart that holds just a list of numbers, but expands in the GUI to show also a textual form of each number (in German).
########################################################################
(app)
(load "@lib/zahlwort.l")
(action
(html 0 "Numerals" "@lib.css" NIL
(form NIL
(gui '(+Init +Chart) (1 5 7) 2
'((N) (list N (zahlwort N)))
car )
(<table> NIL NIL '((NIL "Numeral") (NIL "German"))
(do 4
(<row> NIL
(gui 1 '(+NumField) 9)
(gui 2 '(+Lock +TextField) 90) ) ) )
(gui '(+UpButton) 1)
(gui '(+DnButton) 1)
(----)
(<submit> "Save") ) ) )
########################################################################
"@lib/zahlwort.l" defines the utility function zahlwort, which
is required later by the 'put' function. zahlwort accepts a number
and returns its wording in German.
Now look at the code
(gui '(+Init +Chart) (1 5 7) 2
'((N) (list N (zahlwort N)))
car )
We prefix the +Chart class
with +Init, and pass it a list
of numbers (1 5 7) for the initial value of the chart. Then,
following the '2' (the chart has two columns), we pass a 'put' function
'((N) (list N (zahlwort N)))
which takes a number and returns a list of that number and its wording, and a 'get' function
car )
which in turn accepts such a list and returns a number, which happens to be the list's first element.
You can see from this example that 'get' is the inverse function of 'put'. 'get' can be omitted, however, if the chart is read-only (contains no (or only locked) input fields).
The field in the second column
(gui 2 '(+Lock +TextField) 90) ) ) )
is locked, because it displays the text generated by 'put', and is not supposed to accept any user input.
When you start up this form in your browser, you'll see three pre-filled
lines with "1/eins", "5/fünf" and "7/sieben", according to the +Init argument (1 5 7).
Typing a number somewhere into the first column, and pressing ENTER or one of
the buttons, will show a suitable text in the second column.
In previous chapters we saw examples of GUI classes like +TextField, +NumField or +Button, often in combination with
prefix classes like +Lock,
+Init or +Able. Now we take a broader look at the
whole hierarchy, and try more examples.
The abstract class +gui is the base of all GUI classes. A live
view of the class hierarchy can be obtained with the dep ("dependencies") function:
: (dep '+gui)
+gui
+Img
+field
+Radio
+TextField
+UpField
+PwField
+BlobField
+FileField
+TimeField
+DateField
+MailField
+AtomField
+HttpField
+LinesField
+ClassField
+TelField
+numField
+NumField
+FixField
+SymField
+SexField
+ListTextField
+Checkbox
+Button
+BubbleButton
+DelRowButton
+DnButton
+GoButton
+UpButton
+ChoButton
+Choice
+ClrButton
+PickButton
+DstButton
+todoButton
+RedoButton
+UndoButton
+ShowButton
+JsField
-> +gui
We see, for example, that +DnButton is a subclass of +Button, which in turn is a subclass of
+gui. Inspecting +DnButton directly
: (dep '+DnButton)
+Tiny
+Rid
+JS
+Able
+gui
+Button
+DnButton
-> +DnButton
shows that +DnButton
inherits from +Tiny, +Rid, +Able and +Button. The actual definition of
+DnButton can be found in
"@lib/form.l"
(class +DnButton +Tiny +Rid +JS +Able +Button)
...
In general, "@lib/form.l" is the ultimate reference to the framework, and should be freely consulted. See also the form library reference.
Input fields implement the visual display of application data, and allow - when enabled - input and modification of these data.
On the HTML level, they can take the form of
Except for checkboxes, which are implemented by the Checkbox class, all these HTML representations are
generated by +TextField and
its content-specific subclasses like +NumField, +DateField etc. Their actual
appearance (as one of the above forms) depends on their arguments:
We saw already "normal" text fields. They are created with a single numeric argument. This example creates an editable field with a width of 10 characters:
(gui '(+TextField) 10)
If you supply a second numeric for the line count ('4' in this case), you'll get a text area:
(gui '(+TextField) 10 4)
Supplying a list of values instead of a count yields a drop-down selection (combo box):
(gui '(+TextField) '("Value 1" "Value 2" "Value 3"))
In addition to these arguments, you can pass a string. Then the field is created with a label:
(gui '(+TextField) 10 "Plain")
(gui '(+TextField) 10 4 "Text Area")
(gui '(+TextField) '("Value 1" "Value 2" "Value 3") "Selection")
Finally, without any arguments, the field will appear as a plain HTML text:
(gui '(+TextField))
This makes mainly sense in combination with prefix classes like +Var and +Obj, to manage the contents of these
fields, and achieve special behavior as HTML links or scrollable chart values.
A +NumField returns a
number from its val> method, and accepts a number for its
set> method. It issues an error message when user input cannot
be converted to a number.
Large numbers are shown with a thousands-separator, as determined by the current locale.
########################################################################
(app)
(action
(html 0 "+NumField" "@lib.css" NIL
(form NIL
(gui '(+NumField) 10)
(gui '(+JS +Button) "Print value"
'(msg (val> (: home gui 1))) )
(gui '(+JS +Button) "Set to 123"
'(set> (: home gui 1) 123) ) ) ) )
########################################################################
A +FixField needs an
additional scale factor argument, and accepts/returns scaled fixpoint numbers.
The decimal separator is determined by the current locale.
########################################################################
(app)
(action
(html 0 "+FixField" "@lib.css" NIL
(form NIL
(gui '(+FixField) 3 10)
(gui '(+JS +Button) "Print value"
'(msg (format (val> (: home gui 1)) 3)) )
(gui '(+JS +Button) "Set to 123.456"
'(set> (: home gui 1) 123456) ) ) ) )
########################################################################
A +DateField accepts and
returns a date value.
########################################################################
(app)
(action
(html 0 "+DateField" "@lib.css" NIL
(form NIL
(gui '(+DateField) 10)
(gui '(+JS +Button) "Print value"
'(msg (datStr (val> (: home gui 1)))) )
(gui '(+JS +Button) "Set to \"today\""
'(set> (: home gui 1) (date)) ) ) ) )
########################################################################
The format displayed to - and entered by - the user depends on the current
locale (see datStr and expDat). You can change it, for example to
: (locale "DE" "de")
-> NIL
If no locale is set, the format is YYYY-MM-DD. Some pre-defined locales use patterns like DD.MM.YYYY (DE), YYYY/MM/DD (JP), DD/MM/YYYY (UK), or MM/DD/YYYY (US).
An error is issued when user input does not match the current locale's date format.
Independent from the locale setting, a +DateField tries to expand
abbreviated input from the user. A small number is taken as that day of the
current month, larger numbers expand to day and month, or to day, month and
year:
Similar is the +TimeField. It accepts and returns a time value.
########################################################################
(app)
(action
(html 0 "+TimeField" "@lib.css" NIL
(form NIL
(gui '(+TimeField) 8)
(gui '(+JS +Button) "Print value"
'(msg (tim$ (val> (: home gui 1)))) )
(gui '(+JS +Button) "Set to \"now\""
'(set> (: home gui 1) (time)) ) ) ) )
########################################################################
When the field width is '8', like in this example, time is displayed in the
format HH:MM:SS. Another possible value would be '5', causing
+TimeField to display its value as HH:MM.
An error is issued when user input cannot be converted to a time value.
The user may omit the colons. If he inputs just a small number, it should be between '0' and '23', and will be taken as a full hour. '125' expands to "12:05", '124517' to "12:45:17", and so on.
Telephone numbers are represented internally by the country code (without a leading plus sign or zero) followed by the local phone number (ideally separated by spaces) and the phone extension (ideally separated by a hyphen). The exact format of the phone number string is not enforced