PicoLisp Application Development

(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).

• Static Pages
  • Hello World
    • Start the application server
    • How does it work?
  • URL Syntax
  • Security
    • The ".pw" File
  • The html Function
  • CSS Attributes
  • Tag Functions
    • Simple Tags
    • (Un)ordered Lists
    • Tables
    • Menus and Tabs
• Interactive Forms
  • Sessions
  • Action Forms
    • The gui Function
    • Control Flow
    • Switching URLs
    • Alerts and Dialogs
    • A Calculator Example
  • Charts
    • Scrolling
    • Put and Get Functions
• GUI Classes
  • Input Fields
    • Numeric Input Fields
    • Time & Date
    • Telephone Numbers
    • Checkboxes
  • Field Prefix Classes
    • Initialization
    • Disabling and Enabling
    • Formatting
    • Side Effects
    • Validation
    • Data Linkage
  • Buttons
    • Dialog Buttons
    • Active JavaScript
• A Minimal Complete Application
  • Getting Started
    • Localization
    • Navigation
    • Choosing Objects
    • Editing
    • Buttons vs. Links
  • The Data Model
  • Usage
    • Customer/Supplier
    • Item
    • Order
    • Reports
  • Bugs

Static Pages

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.

Hello World

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)

Start the application server

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.

How does it work?

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).

URL Syntax

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

• the preceding protocol, host and port specifications,
• and the trailing question mark plus arguments

• If a path starts with an exclamation-mark ('!'), the rest (without the '!') is taken as the name of a Lisp function to be called. All arguments following the question mark are passed to that function.
• If a path ends with ".l" (a dot and a lower case 'L'), it is taken as a Lisp source file name to be (load)ed. This is the most common case, and we use it in our example "project.l".
• If the extension of a file name matches an entry in the global mime type table *Mimes, the file is sent to the client with mime-type and max-age values taken from that table.
• Otherwise, the file is sent to the client with a mime-type of "application/octet-stream" and a max-age of 1 second.

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:

• An internal symbol starts with a dollar sign ('$')
• A number starts with a plus sign ('+')
• An external (database) symbol starts with dash ('-')
• A list (one level only) is encoded with underscores ('_')
• Otherwise, it is a transient symbol (a plain string)

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.

Security

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,