app.html

A very small LISP implementation with several packages and demo programs.

of <a href="#cssAttr">CSS Attributes</a> below). It will be passed to the
<code>body</code> tag.

</ol>

<p>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. <a name="tagRule">This rule</a> is slightly different from the
evaluation of normal Lisp expressions:

<p><ul>

<li>If an argument is an atom (a number or a symbol (string)), its value is
printed immediately.

<li>Otherwise (a list), it is evaluated as a Lisp function (typically some form
of print statement).

</ul>

<p>Therefore, our source file might as well be written as:

<p><pre><code>
########################################################################
(html 0 "Hello" "lib.css" NIL
   (prinl "Hello World!") )
########################################################################
</code></pre>

<p>The most typical print statements will be some HTML-tags:

<p><pre><code>
########################################################################
(html 0 "Hello" "lib.css" NIL
   (&lt;h1&gt; NIL "Hello World!")
   (&lt;br&gt; "This is some text.")
   (ht:Prin "And this is a number: " (+ 1 2 3)) )
########################################################################
</code></pre>

<p><code>&lt;h1&gt;</code> and <code>&lt;br&gt;</code> are tag functions.
<code>&lt;h1&gt;</code> takes a CSS attribute as its first argument.

<p>Note the use of <code>ht:Prin</code> instead of <code>prin</code>.
<code>ht:Prin</code> should be used for all direct printing in HTML pages,
because it takes care to escape special characters.


<p><hr>
<h3><a name="cssAttr">CSS Attributes</a></h3>

<p>The <a href="#htmlFoo"><code>html</code> function</a> above, and many of the
HTML <a href="#tags">tag functions</a>, 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 <code>&lt;h1&gt;</code> tag function.

<p>An atom (usually a symbol or a string) is taken as a CSS class name

<p><pre><code>
: (&lt;h1&gt; 'foo "Title")
&lt;h1 class="foo"&gt;Title&lt;/h1&gt;
</code></pre>

<p>For a cons pair, the CAR is taken as an attribute name, and the CDR as the
attribute's value

<p><pre><code>
: (&lt;h1&gt; '(id . bar) "Title")
&lt;h1 id="bar"&gt;Title&lt;/h1&gt;
</code></pre>

<p>Consequently, a list of cons pairs gives a set of attribute-value pairs

<p><pre><code>
: (&lt;h1&gt; '((id . "abc") (lang . "de")) "Title")
&lt;h1 id="abc" lang="de"&gt;Title&lt;/h1&gt;
</code></pre>


<p><hr>
<h3><a name="tags">Tag Functions</a></h3>

<p>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 Pico Lisp prompt, or by pressing the browser's "Reload" button after
editing the "project.l" file.

<p>For a suitable Pico Lisp prompt, either execute (in a separate terminal
window) the Pico Lisp Shell (<code>psh</code>) command (works only if the
application server is running, and you did generate a <a href="#pw">".pw"
file</a>)

<p><pre><code>
$ bin/psh 8080
:
</code></pre>

<p>or start the interpreter stand-alone, with "lib/xhtml.l" loaded

<p><pre><code>
$ ./p dbg.l lib/http.l lib/xhtml.l
:
</code></pre>

<p>Note that for all these tag functions the above <a href="#tagRule">tag body
evaluation rule</a> applies.


<h4><a name="simple">Simple Tags</a></h4>

<p>Most tag functions are simple and straightforward. Some of them just print
their arguments

<p><pre><code>
: (&lt;br&gt; "Hello world")
Hello world&lt;br/&gt;

: (&lt;em&gt; "Hello world")
&lt;em&gt;Hello world&lt;/em&gt;
</code></pre>

<p>while most of them take a <a href="#cssAttr">CSS attribute specification</a>
as their first argument (like the <code>&lt;h1&gt;</code> tag above)

<p><pre><code>
: (&lt;div&gt; 'main "Hello world")
&lt;div class="main"&gt;Hello world&lt;/div&gt;

: (&lt;p&gt; NIL "Hello world")
&lt;p&gt;Hello world&lt;/p&gt;

: (&lt;p&gt; 'info "Hello world")
&lt;p class="info"&gt;Hello world&lt;/p&gt;
</code></pre>

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

<p><pre><code>
: (&lt;div&gt; 'main
   (&lt;h1&gt; NIL "Head")
   (&lt;p&gt; NIL
      (&lt;br&gt; "Line 1")
      "Line"
      (&lt;nbsp&gt;)
      (+ 1 1) ) )
&lt;div class="main"&gt;&lt;h1&gt;Head&lt;/h1&gt;
&lt;p&gt;Line 1&lt;br/&gt;
Line&nbsp;2&lt;/p&gt;
&lt;/div&gt;
</code></pre>


<h4><a name="lists">(Un)ordered Lists</a></h4>

<p>HTML-lists, implemented by the <code>&lt;ol&gt;</code> and
<code>&lt;ul&gt;</code> tags, let you define hierarchical structures. You might
want to paste the following code into your copy of "project.l":

<p><pre><code>
########################################################################
(html 0 "Unordered List" "lib.css" NIL
   (&lt;ul&gt; NIL
      (&lt;li&gt; NIL "Item 1")
      (&lt;li&gt; NIL
         "Sublist 1"
         (&lt;ul&gt; NIL
            (&lt;li&gt; NIL "Item 1-1")
            (&lt;li&gt; NIL "Item 1-2") ) )
      (&lt;li&gt; NIL "Item 2")
      (&lt;li&gt; NIL
         "Sublist 2"
         (&lt;ul&gt; NIL
            (&lt;li&gt; NIL "Item 2-1")
            (&lt;li&gt; NIL "Item 2-2") ) )
      (&lt;li&gt; NIL "Item 3") ) )
########################################################################
</code></pre>

<p>Here, too, you can put arbitrary code into each node of that tree, including
other tag functions.


<h4><a name="tables">Tables</a></h4>

<p>Like the hierarchical structures with the list functions, you can generate
two-dimensional tables with the <code>&lt;table&gt;</code> and
<code>&lt;row&gt;</code> functions.

<p>The following example prints a table of numbers and their squares:

<p><pre><code>
########################################################################
(html 0 "Table" "lib.css" NIL
   (&lt;table&gt; NIL NIL NIL
      (for (N 1 (&gt;= 10 N) (inc N))              # A table with 10 rows
         (&lt;row&gt; NIL N (prin (* N N))) ) ) )     # and 2 columns
########################################################################
</code></pre>

<p>The first argument to <code>&lt;table&gt;</code> 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.

<p>The body of <code>&lt;table&gt;</code> contains calls to the
<code>&lt;row&gt;</code> 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 <code>&lt;td&gt;</code> tag. This
permits distinct CSS specifications for each column and row.

<p>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 <code>&lt;table&gt;</code>), right-align both
columns, and print each row in an alternating red and blue color

<p><pre><code>
########################################################################
(html 0 "Table" "lib.css" NIL
   (&lt;table&gt;
      '((width . "200px") (style . "border: dotted 1px;"))    # table style
      "Square Numbers"                                        # caption
      '((align "Number") (align "Square"))                    # 2 headers
      (for (N 1 (&gt;= 10 N) (inc N))                            # 10 rows
         (&lt;row&gt; (xchg '(red) '(blue))                         # red or blue
            N                                                 # 2 columns
            (prin (* N N) ) ) ) ) )
########################################################################
</code></pre>

<p>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 '<code>-</code>' for the
additional cell data to <code>&lt;row&gt;</code>. This will cause the data given
to the left of the '<code>-</code>' symbols to expand to the right.

<p>You can also directly specify table structures with the simple
<code>&lt;th&gt;</code>, <code>&lt;tr&gt;</code> and <code>&lt;td&gt;</code> tag
functions.

<p>If you just need a two-dimensional arrangement of components, the even
simpler <code>&lt;grid&gt;</code> function might be convenient:

<p><pre><code>
########################################################################
(html 0 "Grid" "lib.css" NIL
   (&lt;grid&gt; 3
      "A" "B" "C"
      123 456 789 ) )
########################################################################
</code></pre>

<p>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

<p><pre><code>
   (&lt;grid&gt; '(NIL NIL right)
</code></pre>

<p>Then the third column will be right aligned.


<h4><a name="menus">Menus and Tabs</a></h4>

<p>The two most powerful tag functions are <code>&lt;menu&gt;</code> and
<code>&lt;tab&gt;</code>. Used separately or in combination, they form a
navigation framework with

<p><ul>
<li>menu items which open and close submenus
<li>submenu items which switch to different pages
<li>tabs which switch to different subpages
</ul>

<p>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:

<p><pre><code>
########################################################################
(html 0 "Menu+Tab" "lib.css" NIL
   (&lt;div&gt; '(id . menu)
      (&lt;menu&gt;
         ("Item" "project.l")                      # Top level item
         (NIL (&lt;hr&gt;))                              # 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") ) ) )
   (&lt;div&gt; '(id . main)
      (&lt;h1&gt; NIL "Menu+Tab")
      (&lt;tab&gt;
         ("Tab1"
            (&lt;h3&gt; NIL "This is Tab 1") )
         ("Tab2"
            (&lt;h3&gt; NIL "This is Tab 2") )
         ("Tab3"
            (&lt;h3&gt; NIL "This is Tab 3") ) ) ) )
########################################################################
</code></pre>

<p><code>&lt;menu&gt;</code> takes a sequence of menu items. Each menu item is a
list, with its CAR either

<p><ul>
<li><code>NIL</code>: The entry is not an active menu item, and the rest of the
list may consist of arbitrary code (usually HTML tags).

<li><code>T</code>: 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).

<li>Otherwise: The menu item specifies a direct action (instead of opening a
submenu), where the first list element gives the item's name, and the second
element the corresponding URL.

</ul>

<p><code>&lt;tab&gt;</code> takes a list of subpages. Each page is simply a tab
name, followed by arbitrary code (typically HTML tags).

<p>Note that only a single menu and a single tab may be active at the same time.


<p><hr>
<h2><a name="forms">Interactive Forms</a></h2>

<p>In HTML, the only possibility for user input is via <code>&lt;form&gt;</code>
and <code>&lt;input&gt;</code> elements, using the HTTP POST method to
communicate with the server.

<p>"lib/xhtml.l" defines a function called <code>&lt;post&gt;</code>, and a
collection of input tag functions, which allow direct programming of HTML forms.
We will supply only one simple example:

<p><pre><code>
########################################################################
(html 0 "Simple Form" "lib.css" NIL
   (&lt;post&gt; NIL "project.l"
      (&lt;field&gt; 10 '*Text)
      (&lt;submit&gt; "Save") ) )
########################################################################
</code></pre>

<p>This associates a text input field with a global variable <code>*Text</code>.
The field displays the current value of <code>*Text</code>, and pressing the
submit button causes a reload of "project.l" with <code>*Text</code> set to any
string entered by the user.

<p>An application program could then use that variable to do something useful,