app.html

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

<p><hr>
<h2><a name="guiClasses">GUI Classes</a></h2>

<p>In previous chapters we saw examples of GUI classes like
<code>+TextField</code>, <code>+NumField</code> or <code>+Button</code>, often
in combination with prefix classes like <code>+Lock</code>, <code>+Init</code>
or <code>+Able</code>. Now we take a broader look at the whole hierarchy, and
try more examples.

<p>The abstract class <code>+gui</code> is the base of all GUI classes. A live
view of the class hierarchy can be obtained with the <code>dep</code>
("dependencies") function:

<p><pre><code>
: (dep '+gui)
+gui
   +JsField
   +Button
      +UpButton
      +PickButton
         +DstButton
      +ClrButton
      +ChoButton
         +Hint
      +BubbleButton
      +DelRowButton
      +ShowButton
      +DnButton
   +field
      +Checkbox
      +TextField
         +ClassField
         +UrlField
            +MailField
            +HttpField
         +numField
            +NumField
            +FixField
         +BlobField
         +DateField
         +SymField
         +UpField
         +SexField
         +PwField
         +ListTextField
         +TelField
         +TimeField
-> +gui
</code></pre>

<p>We see, for example, that <code>+DnButton</code> is a subclass of
<code>+Button</code>, which in turn is a subclass of <code>+gui</code>.
Inspecting <code>+DnButton</code> directly

<p><pre><code>
: (dep '+DnButton)
   +Tiny
   +Rid
   +JS
   +Able
      +gui
   +Button
+DnButton
-> +DnButton
</code></pre>

<p>shows that <code>+DnButton</code> inherits from <code>+Tiny</code>,
<code>+Rid</code>, <code>+Able</code> and <code>+Button</code>. The actual
definition of <code>+DnButton</code> can be found in "lib/form.l"

<p><pre><code>
(class +DnButton +Tiny +Rid +JS +Able +Button)
...
</code></pre>

<p>In general, "lib/form.l" is the ultimate reference to the framework, and
should be freely consulted.


<p><hr>
<h3><a name="inputFields">Input Fields</a></h3>

<p>Input fields implement the visual display of application data, and allow -
when enabled - input and modification of these data.

<p>On the HTML level, they can take the form of

<ul>
<li>Normal text input fields
<li>Textareas
<li>Checkboxes
<li>Drop-down selections
<li>Password fields
<li>HTML links
<li>Plain HTML text
</ul>

<p>Except for checkboxes, which are implemented by the <a
href="#checkboxes">Checkbox</a> class, all these HTML representations are
generated by <code>+TextField</code> and its content-specific subclasses like
<code>+NumField</code>, <code>+DateField</code> etc. Their actual appearance (as
one of the above forms) depends on their arguments:

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

<p><pre><code>
   (gui '(+TextField) 10)
</code></pre>

<p>If you supply a second numeric for the line count ('4' in this case), you'll
get a text area:

<p><pre><code>
   (gui '(+TextField) 10 4)
</code></pre>

<p>Supplying a list of values instead of a count yields a drop-down selection
(combo box):

<p><pre><code>
   (gui '(+TextField) '("Value 1" "Value 2" "Value 3"))
</code></pre>

<p>In addition to these arguments, you can pass a string. Then the field is
created with a label:

<p><pre><code>
   (gui '(+TextField) 10 "Plain")
   (gui '(+TextField) 10 4 "Text Area")
   (gui '(+TextField) '("Value 1" "Value 2" "Value 3") "Selection")
</code></pre>

<p>Finally, without any arguments, the field will appear as a plain HTML text:

<p><pre><code>
   (gui '(+TextField))
</code></pre>

<p>This makes mainly sense in combination with prefix classes like
<code>+Var</code> and <code>+Obj</code>, to manage the contents of these fields,
and achieve special behavior as HTML links or scrollable chart values.


<h4><a name="numberFields">Numeric Input Fields</a></h4>

<p>A <code>+NumField</code> returns a number from its <code>val&gt;</code>
method, and accepts a number for its <code>set&gt;</code> method. It issues an
error message when user input cannot be converted to a number.

<p>Large numbers are shown with a thousands-separator, as determined by the
current locale.

<p><pre><code>
########################################################################
(app)

(action
   (html 0 "+NumField" "lib.css" NIL
      (form NIL
         (gui '(+NumField) 10)
         (gui '(+JS +Button) "Print value"
            '(msg (val&gt; (: home gui 1))) )
         (gui '(+JS +Button) "Set to 123"
            '(set&gt; (: home gui 1) 123) ) ) ) )
########################################################################
</code></pre>

<p>A <code>+FixField</code> needs an additional scale factor argument, and
accepts/returns scaled fixpoint numbers.

<p>The decimal separator is determined by the current locale.

<p><pre><code>
########################################################################
(app)

(action
   (html 0 "+FixField" "lib.css" NIL
      (form NIL
         (gui '(+FixField) 3 10)
         (gui '(+JS +Button) "Print value"
            '(msg (format (val&gt; (: home gui 1)) 3)) )
         (gui '(+JS +Button) "Set to 123.456"
            '(set&gt; (: home gui 1) 123456) ) ) ) )
########################################################################
</code></pre>


<h4><a name="timeDateFields">Time &amp; Date</a></h4>

<p>A <code>+DateField</code> accepts and returns a <code><a
href="refD.html#date">date</a></code> value.

<p><pre><code>
########################################################################
(app)

(action
   (html 0 "+DateField" "lib.css" NIL
      (form NIL
         (gui '(+DateField) 10)
         (gui '(+JS +Button) "Print value"
            '(msg (datStr (val&gt; (: home gui 1)))) )
         (gui '(+JS +Button) "Set to \"today\""
            '(set&gt; (: home gui 1) (date)) ) ) ) )
########################################################################
</code></pre>

<p>The format displayed to - and entered by - the user depends on the current
locale (see <code><a href="refD.html#datStr">datStr</a></code> and <code><a
href="refE.html#expDat">expDat</a></code>). You can change it, for example to

<p><pre><code>
: (locale "DE" "de")
-> NIL
</code></pre>

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

<p>An error is issued when user input does not match the current locale's date
format.

<p>Independent from the locale setting, a <code>+DateField</code> 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:

<ul>
<li>"7" gives the 7th of the current month
<li>"031" or "0301" give the 3rd of January of the current year
<li>"311" or "3101" give the 31st of January of the current year
<li>"0311" gives the 3rd of November of the current year
<li>"01023" or "010203" give the first of February in the year 2003
<li>and so on
</ul>

<p>Similar is the <code>+TimeField</code>. It accepts and returns a <code><a
href="refT.html#time">time</a></code> value.

<p><pre><code>
########################################################################
(app)

(action
   (html 0 "+TimeField" "lib.css" NIL
      (form NIL
         (gui '(+TimeField) 8)
         (gui '(+JS +Button) "Print value"
            '(msg (tim$ (val&gt; (: home gui 1)))) )
         (gui '(+JS +Button) "Set to \"now\""
            '(set&gt; (: home gui 1) (time)) ) ) ) )
########################################################################
</code></pre>

<p>When the field width is '8', like in this example, time is displayed in the
format <code>HH:MM:SS</code>. Another possible value would be '5', causing
<code>+TimeField</code> to display its value as <code>HH:MM</code>.

<p>An error is issued when user input cannot be converted to a time value.

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


<h4><a name="telFields">Telephone Numbers</a></h4>

<p>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 by the GUI, but further
processing (e.g. database searches) normally uses <code><a
href="refF.html#fold">fold</a></code> for better reproducibility.

<p>To display a phone number, <code>+TelField</code> replaces the country code
with a single zero if it is the country code of the current locale, or prepends
it with a plus sign if it is a foreign country (see <code><a
href="refT.html#telStr">telStr</a></code>).

<p>For user input, a plus sign or a double zero is simply dropped, while a
single leading zero is replaced with the current locale's country code (see
<code><a href="refE.html#expTel">expTel</a></code>).

<p><pre><code>
########################################################################
(app)
(locale "DE" "de")

(action
   (html 0 "+TelField" "lib.css" NIL
      (form NIL
         (gui '(+TelField) 20)
         (gui '(+JS +Button) "Print value"
            '(msg (val&gt; (: home gui 1))) )
         (gui '(+JS +Button) "Set to \"49 1234 5678-0\""
            '(set&gt; (: home gui 1) "49 1234 5678-0") ) ) ) )
########################################################################
</code></pre>


<h4><a name="checkboxes">Checkboxes</a></h4>

<p>A <code>+Checkbox</code> is straightforward. User interaction is restricted
to clicking it on and off. It accepts boolean (<code>NIL</code> or
non-<code>NIL</code>) values, and returns <code>T</code> or <code>NIL</code>.

<p><pre><code>
########################################################################
(app)

(action
   (html 0 "+Checkbox" "lib.css" NIL
      (form NIL
         (gui '(+Checkbox))
         (gui '(+JS +Button) "Print value"
            '(msg (val&gt; (: home gui 1))) )
         (gui '(+JS +Button) "On"
            '(set&gt; (: home gui 1) T) )
         (gui '(+JS +Button) "Off"
            '(set&gt; (: home gui 1) NIL) ) ) ) )
########################################################################
</code></pre>


<p><hr>
<h3><a name="fieldPrefix">Field Prefix Classes</a></h3>

<p>A big part of this framework's power is owed to the combinatorial flexibility
of prefix classes for GUI- and DB-objects. They allow to surgically override
individual methods in the inheritance tree, and can be combined in various ways
to achieve any desired behavior.

<p>Technically, there is nothing special about prefix classes. They are just
normal classes. They are called "prefix" because they are intended to be written
<i>before</i> other classes in a class's or object's list of superclasses.

<p>Usually they take their own arguments for their <code>T</code> method from
the list of arguments to the <code>gui</code> function.


<h4><a name="initPrefix">Initialization</a></h4>

<p><code>+Init</code> overrides the <code>init&gt;</code> method for that
component. The <code>init&gt;</code> message is sent to a <code>+gui</code>
component when the page is loaded for the first time (during a GET request).
<code>+Init</code> takes an expression for the initial value of that field.

<p><pre><code>
   (gui '(+Init +TextField) "This is the initial text" 30)
</code></pre>

<p>Other classes which automatically give a value to a field are
<code>+Var</code> (linking the field to a variable)