[clinton/website/site/unknownlamer.org.git] / UCWNotes.html

<?xml version="1.0" encoding="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">
  <head>
    <title>Roadmap to UCW Codebase</title>
    <meta name="generator" content="muse.el" />
    <meta http-equiv="Content-Type"
          content="text/html; charset=utf-8" />
<link rel="stylesheet" href="default.css" media="screen" />
  </head>
  <body>
    <h1>Roadmap to UCW Codebase</h1>
   <div class="contents">
<dl>
<dt>
<a href="#sec1">Abstract</a>
</dt>
<dt>
<a href="#sec2">Roadmap</a>
</dt>
<dd>
<dl>
<dt>
<a href="#sec3">Applications</a>
</dt>
<dd>
<dl>
<dt>
<a href="#sec4">Cookie</a>
</dt>
<dt>
<a href="#sec5">L10n</a>
</dt>
<dt>
<a href="#sec6">Secure</a>
</dt>
</dl>
</dd>
<dt>
<a href="#sec7">Components</a>
</dt>
<dd>
<dl>
<dt>
<a href="#sec8">Windows</a>
</dt>
<dt>
<a href="#sec9">Containers</a>
</dt>
<dt>
<a href="#sec10">Dialogs</a>
</dt>
<dt>
<a href="#sec11">Forms</a>
</dt>
<dt>
<a href="#sec12">Templates</a>
</dt>
<dt>
<a href="#sec13">Utility Mixin Components</a>
</dt>
</dl>
</dd>
<dt>
<a href="#sec14">Control Flow</a>
</dt>
<dd>
<dl>
<dt>
<a href="#sec15">Calling</a>
</dt>
<dt>
<a href="#sec16">Actions</a>
</dt>
<dt>
<a href="#sec17">Entry Points</a>
</dt>
</dl>
</dd>
<dt>
<a href="#sec18">Dispatching</a>
</dt>
<dd>
<dl>
<dt>
<a href="#sec19">Simple Dispatcher</a>
</dt>
</dl>
</dd>
<dt>
<a href="#sec20">Server</a>
</dt>
<dt>
<a href="#sec21">Debugging</a>
</dt>
<dd>
<dl>
<dt>
<a href="#sec22">Inspector</a>
</dt>
</dl>
</dd>
</dl>
</dd>
<dt>
<a href="#sec23">Tips</a>
</dt>
<dd>
<dl>
<dt>
<a href="#sec24">Getting dojo to load</a>
</dt>
<dt>
<a href="#sec25">Specials Bound During Rendering</a>
</dt>
<dt>
<a href="#sec26">Printing to the yaclml stream</a>
</dt>
</dl>
</dd>
</dl>
</div>


<!-- Page published by Emacs Muse begins here --><h2><a name="sec1" id="sec1"></a>
Abstract</h2>

<p><a href="http://common-lisp.net/project/ucw/">UnCommon Web</a> is a very powerful and mature web framework for Common
Lisp, but is a bit difficult to learn. It is documented
extensively&mdash;in the form of docstrings. These are extremely helpful
once you've figured out the rough structure of UCW, but they are of no
help when first learning unless you just read most of the source. I
ended up having to do that, and after some urging along by folks in
<code>#ucw</code> I decided to clean up my planner notes and publish them for
public consumption.</p>

<p>The roadmap is presented with major sections ordered in a logical
order for learning the framework. The sections are ordered internally
in order of most immediately useful to least, but it may be worth
hopping between major sections before reading all of the details. I
have used abridged class definitions and docstrings with occasional
commentary to clarify things.</p>


<h2><a name="sec2" id="sec2"></a>
Roadmap</h2>

<h3><a name="sec3" id="sec3"></a>
Applications</h3>

<p class="first">Applications are a bundle of entry points. The base class is,
naturally, <code>standard-application</code>, but you should instead derive your
application class from <code>modular-application</code> and any standard or custom
application mixins you find useful.</p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/standard-classes.lisp">src/rerl/standard-classes.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">standard-application</span> (application)
  ((url-prefix <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:url-prefix</span>
               <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A string specifying the
start (prefix) of all the urls this app should handle.

This value is used by the standard-server to decide what app a
particular request is aimed at and for generating links to
actions within the app. "</span>)
   (www-roots <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:www-roots</span>
              <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A list of directories (pathname
specifiers) or cons-cell (URL-subdir . pathname) to use when looking for static files."</span>)
   (dispatchers <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:dispatchers</span>
                <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A list of request
dispatchers. The user supplied list of dispatchers is extended
with other dispatchers that are required for UCW to function
properly (action-dispatcher, a parenscript-dispatcher, etc). If
you want full control over the active dispatchers use the (setf
application.dispatchers) accessor or, if you want control over
the order of the dispathcers, (slot-value instance
'dispatchers)."</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"The default UCW application class."</span>))
</pre>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/modular-application/modular-application.lisp">src/rerl/modular-application/modular-application.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">modular-application-mixin</span> ()
  ()
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Superclass for all application mixins."</span>))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">modular-application</span> (standard-application modular-application-mixin)
  ...)
</pre>

<h4><a name="sec4" id="sec4"></a>
Cookie</h4>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/modular-application/cookie-module.lisp">src/rerl/modular-application/cookie-module.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">cookie-session-application-module</span> (modular-application-mixin)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Class for applications which use cookies for sesion tracking.

Cookie session applications work exactly like
standard-applications except that when the session is not found
using the standard mechanisms the id is looked for in a cookie."</span>))
</pre>

<p>This is the most useful of the application components. It makes your
application urls readable by stashing the session id into a cookie
rather than as a set of long and ugly GET parameters.</p>


<h4><a name="sec5" id="sec5"></a>
L10n</h4>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/modular-application/l10n-module.lisp">src/rerl/modular-application/l10n-module.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">l10n-application-module</span> (modular-application-mixin)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Application class which can handle l10n requests."</span>))
</pre>


<h4><a name="sec6" id="sec6"></a>
Secure</h4>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/modular-application/security-module.lisp">src/rerl/modular-application/security-module.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">secure-application-module</span> (modular-application-mixin)
  (<span style="color: #b0c4de;">:documentation</span>
    <span style="color: #b3b3b3;">"Mixin class for applications which require authorized access.
Concrete application must specialize the following methods:
APPLICATION-FIND-USER (APPLICATION USERNAME)
APPLICATION-CHECK-PASSWORD (APPLICATION USER PASSWORD)
APPLICATION-AUTHORIZE-CALLZE-CALL (APPLICATION USER FROM-COMPONENT TO-COMPONENT)."</span>))
</pre>


<h3><a name="sec7" id="sec7"></a>
Components</h3>

<p class="first">A component is a special class that handles the complexities of
continuation suspension and such for you. New components are derived
from the existing ones by using <code>defcomponent</code> instead of <code>defclass</code>. This
adds a few extra slot and class options, and ensures that the proper
metaclass is set.</p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/standard-component/standard-component.lisp">src/rerl/standard-component/standard-component.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defmacro</span> <span style="color: #87cefa;">defcomponent</span> (name supers slots <span style="color: #98fb98;">&amp;rest</span> options)
  <span style="color: #b3b3b3;">"Macro for defining a component class.

This macro is used to create component classes and provides
options for easily creating the methods which often accompany a
component definition.

NAME, SUPERS and SLOTS as treated as per defclass. The following
extra options are allowed:

 (:ENTRY-POINT url (&amp;key application class)) - Define an
 entry-point on the url URL which simply calls an instance of
 this component. Any request parameters passed to the entry-point
 are used to initialize the slots in the component. This option
 may appear multiple times.

 (:DEFAULT-BACKTRACK function-designator) - Unless the slots
 already have a :backtrack option FUNCTION-DESIGNATOR is
 added. As with the 'regular' :backtrack options if you pass T
 here it is assumed to mean #'IDENTITY.

 (:RENDER (&amp;optional COMPONENT) &amp;body BODY) - Generate a render
 method specialized to COMPONENT. COMPONENT may be a symbol, in
 which case the method will be specialized on the componnet
 class. If COMPONNET is omited the component is bound to a
 variable with the same name as the class.

 (:ACTION &amp;optional NAME) - Generate a defaction form named
 NAME (which defaults to the name of the component) which simply
 CALL's this component class passing all the arguments passed to
 the action as initargs."</span>)

<span style="color: #ff7f24;">;;; </span><span style="color: #ff7f24;">Extra Slot Options
</span><span style="color: #b3b3b3;">"Other than the initargs for standard slots the following
options can be passed to component slots:

:backtrack [ T | NIL | FUNCTION-NAME ] - Specify that this slot
should be backtracked (or not if NIL is passed as the value). If
the value is neither T nor NIL then it must be a function which
will be used as the copyer.

:component [ TYPE | ( TYPE &amp;rest INITARGS ) ] - Specify that this
slot is actually a nested component of type TYPE. When instances
of the class are created this slot will be set to an instance of
type TYPE and it's place will be set to this slot. If a list is
passed to :component then TYPE (which isn't evaluated) will be
passed as the first argument to make-instance. The INITARGS will
be eval'd and apply'd to make-instance. The result of this call
to make-instance will be used as the effective component
object."</span>
</pre>

<h4><a name="sec8" id="sec8"></a>
Windows</h4>

<p class="first">A window-component represents a top level browser window, naturally.</p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/window.lisp">src/components/window.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">window-component</span> ()
  ((content-type)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">simple-window-component</span> (window-component)
  ((title)
   (stylesheet)
   (javascript <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"List of javascript includes.

Each element must be a list whose first value is either the
symbol :SRC or :JS.

 (:SRC url) - writes &lt;script src=\"URL\"&gt;&lt;/script&gt; tag.
 (:JS form) - equivalent to (:SCRIPT (js:js* form))
 (:SCRIPT string) - write &lt;script&gt;STRING&lt;/script&gt;.

The elements will be rendered in order."</span>)
   ...))
</pre>

<p><code>window-component</code> could be useful for doing things like dumping binary
data to the user, or just deriving your own funky top level window
type.</p>

<p><code>simple-window-component</code> is the easiest for displaying standard
webpage. It provides a wrapping method on render that displays the
html boilerplate based on your component slot values which is what one
wants most of the time. The initargs to <code>simple-window-component</code> have
the same names as the slots.</p>

<h5>Status Bar</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/status-bar.lisp">src/components/status-bar.lisp</a></p>

<p>There is a generic status bar interface. Messages severity is one of
<code>(:error :warn :info)</code>. Note that the default status bar render method
just shows a div with status messages. A derivative could be defined
to insert messages into the browser status bar.</p>

<pre class="src">
(defcomponent status-bar ()
  ((messages <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"An ALIST of the messages to
show. Each element is a cons of the form (SEVERITY .
MESSAGE). SEVERITY is one of :ERROR, :WARN, :INFO and MESSAGE is
a string which will be html-escaped."</span>)
   ...)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Stateless status bar to display messages."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">add-message</span> (status-bar msg <span style="color: #98fb98;">&amp;key</span> severity <span style="color: #98fb98;">&amp;allow-other-keys</span>)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Add the message text MSG to STATUS-BAR with
severity SEVERITY."</span>))
</pre>

<pre class="src">
(defcomponent status-bar-mixin ()
  ((status-bar <span style="color: #b0c4de;">:accessor</span> status-bar
               <span style="color: #b0c4de;">:initarg</span> status-bar
               <span style="color: #b0c4de;">:component</span> (status-bar))))

(<span style="color: #00ffff;">defmethod</span> <span style="color: #87cefa;">show-status-bar</span> ((win status-bar-mixin))
  (render (status-bar win)))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">show-message</span> (msg <span style="color: #98fb98;">&amp;key</span> severity <span style="color: #98fb98;">&amp;allow-other-keys</span>)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Show a message in the status bar. Only works if
  current window is a status-bar-mixin"</span>))
</pre>


<h5>Redirect</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/redirect.lisp">src/components/redirect.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">redirect-component</span> ()
  ((target <span style="color: #b0c4de;">:accessor</span> target <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:target</span>))
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Send a client redirect.

This component, which must be used as a window-component,
redirects the client to the url specified in the target slot. A
302 (as opposed to 303) response code is sent to ensure
compatability with older browsers.

The redirect component never answers."</span>))
</pre>

<p>There is also a <code>meta-refresh</code> procedure.</p>

<pre class="src">
(defun/cc meta-refresh ()
  <span style="color: #b3b3b3;">"Cause a meta-refresh (a freshly got (GET) url) at this point.
This is useful in order to have a GET url after a form POST's
actions have completed running. The user can then refresh to his
heart's content."</span>)
</pre>


<h4><a name="sec9" id="sec9"></a>
Containers</h4>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/container.lisp">src/components/container.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">container</span> ()
  (...)
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Allow multiple components to share the same place.

The container component serves to manage a set of components.
It does not provide any render impementation, which is the
resposibility of the subclasses (e.g. switching-container or
list-container).

Each contained component has a \"key\" associated with it which
is used to retrieve a particular component. Keys are compared with
container.key-test.

The :contents inintarg, if provided, must be either a list of (key .
component) or a list of components. In the latter case it will
be converted into (component . component) form."</span>))
</pre>

<h5>Protocol</h5>

<ul>
<li><code>child-components</code></li>
<li><code>find-component CONTAINER KEY</code></li>
<li><code>remove-component</code></li>
<li><code>(setf find-component CONTAINER KEY) COMPONENT</code> -&gt;
<code>add-component CONTAINER COMPONENT KEY</code></li>
</ul>


<h5>Switching Container</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/container.lisp">src/components/container.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">switching-container</span> ...
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A simple renderable container component.

This component is like the regular CONTAINER but serves to manage a set
of components which share the same place in the UI. Therefore it provides
an implementation of RENDER which simply renders its current component.

The switching-container component class is generally used as the super
class for navigatation components and tabbed-pane like
components."</span>))
</pre>

<p>Subclass and <code>(defmethod render :around ...)</code> to render navigation using
<code>(call-next-method)</code> to render the selected component.</p>

<h5>Protocol</h5>

<ul>
<li><code>container.current-component COMPONENT</code></li>
<li><code>(setf container.current-component CONTAINER) COMPONENT</code></li>
</ul>


<h5>Tabbed Pane</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/tabbed-pane.lisp">src/components/tabbed-pane.lisp</a></p>

<pre class="src">
(defcomponent tabbed-pane (switching-container)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Component for providing the user with a standard \"tabbed pane\" GUI widget."</span>))
</pre>

<p>Provides a generic tabbed pane that renders a nested div split into a
naviation and content box. The navigation box is a set of styled divs
containing the navigation links.</p>


<h4><a name="sec10" id="sec10"></a>
Dialogs</h4>

<p class="first">A few convenience dialogs are provided for grabbing data from the
user.</p>

<h5>login</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/login.lisp">src/components/login.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">login</span> ()
  ((username) (password) (message))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Generic login (input username and password) component.

This component, which must be embedded in another component,
presents the user with a simple two fielded login form.

When the user attempts a login the action try-login is called,
try-login calls the generic function check-credentials passing it
the login component. If check-credentials returns true then the
login-successful action is called, otherwise the message slot of
the login component is set (to a generic \"bad username\"
message).

The default implementaion of login-successful simply answers t,
no default implementation of check-credentials is
provided. Developers should use sub-classes of login for which
all the required methods have been definined."</span>)
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class))
</pre>

<pre class="src">
(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">check-credentials</span> (login)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Returns T if LOGIN is valid."</span>))

(defaction login-successful ((l login))
  (answer t))
</pre>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/user-login.lisp">src/components/user-login.lisp</a></p>

<pre class="src">
(defcomponent user-login (simple-window-component status-bar-mixin)
  ((username string-field) (password password-field)))
</pre>

<p>Used by <code>secure-application-module</code> to provide a user login. Relevant
protocol details follow.</p>

<pre class="src">
(<span style="color: #00ffff;">defmethod</span> <span style="color: #87cefa;">check-credentials</span> ((self user-login))
  (<span style="color: #00ffff;">let*</span> ((username (value (username self)))
         (password (value (password self)))
         (user (find-application-user username)))
    (<span style="color: #00ffff;">when</span> (and user (check-user-password user password))
      user)))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">application-find-user</span> (application username)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Find USER by USERNAME for APPLICATION."</span>))
</pre>


<h5>error</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/error.lisp">src/components/error.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">error-message</span> (simple-window-component)
  ((message <span style="color: #b0c4de;">:accessor</span> message <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:message</span> <span style="color: #b0c4de;">:initform</span> <span style="color: #b3b3b3;">"ERROR [no message specified]"</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Generic component for showing server side
 error messages."</span>)
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">error-component</span> (error-message)
  ((condition <span style="color: #b0c4de;">:accessor</span> error.condition <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:condition</span> <span style="color: #b0c4de;">:initform</span> nil)
   (backtrace <span style="color: #b0c4de;">:accessor</span> error.backtrace <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:backtrace</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Generic component for showing server side
 error conditions. Unlike ERROR-MESSAGE this component also
 attempts to display a backtrace."</span>)
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class))
</pre>


<h5>message</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/message.lisp">src/components/message.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">info-message</span> ()
  ((message <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:message</span> <span style="color: #b0c4de;">:accessor</span> message)
   (ok-text <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:ok-text</span> <span style="color: #b0c4de;">:accessor</span> ok-text <span style="color: #b0c4de;">:initform</span> <span style="color: #b3b3b3;">"Ok."</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Component for showing a message to the user.

If the OK-TEXT slot is non-NIL component will use that as the
text for a link which, when clicked, causes the component to
answer. It follows that if OK-TEXT is NIL this component will
never answer."</span>)
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class))
</pre>


<h5>option-dialog</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/option-dialog.lisp">src/components/option-dialog.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">option-dialog</span> (template-component)
  ((message) (options) (confirm))
  (<span style="color: #b0c4de;">:default-initargs</span> <span style="color: #b0c4de;">:template-name</span> <span style="color: #b3b3b3;">"ucw/option-dialog.tal"</span>)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Component for querying the user.

The value of the slot MESSAGE is used as a general heading.

The OPTIONS slot must be an alist of (VALUE . LABEL). LABEL (a
string) will be used as the text of a link which, when clikced,
will answer VALUE.

If the CONFIRM slot is T the user will be presented with a second
OPTION-DIALOG asking the user if they are sure they want to
submit that value."</span>)
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class))
</pre>

<p>A macro to present an option dialog is provided.</p>

<pre class="src">
(<span style="color: #00ffff;">defmacro</span> <span style="color: #87cefa;">option-dialog</span> ((message-spec <span style="color: #98fb98;">&amp;rest</span> message-args) <span style="color: #98fb98;">&amp;body</span> options)
  ...)
</pre>

<p><code>message-spec</code> is passed to <code>format</code> if <code>message-args</code> are supplied, and
used as a string literal otherwise. This does not provide a way to set
the confirm property which makes the macro not so generally useful.</p>


<h4><a name="sec11" id="sec11"></a>
Forms</h4>

<p class="first">Reasonably useful forms library that integrates easily with TAL.</p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/form.lisp">src/components/form.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">form-field</span> ()
  ((validators <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"List of validators which will be
               applied to this field."</span>)
   (initially-validate <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"When non-NIL the
                       validators will be run as soon as the page
                       is rendered."</span>)))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">value</span> (form-field)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"The lispish translated value that represents the form-field."</span>))

(<span style="color: #00ffff;">defgeneric</span> (<span style="color: #87cefa;">setf value)</span> (new-value form-field)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Set the value of a form-field with translation to client."</span>))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">generic-html-input</span> (form-field html-element)
  ((client-value <span style="color: #b0c4de;">:accessor</span> client-value <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:client-value</span>
                 <span style="color: #b0c4de;">:initform</span> <span style="color: #b3b3b3;">""</span>
                 <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"The string the client submitted along with this field."</span>)
   (name <span style="color: #b0c4de;">:accessor</span> name <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:name</span> <span style="color: #b0c4de;">:initform</span> nil)
   (accesskey <span style="color: #b0c4de;">:accessor</span> accesskey <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:accesskey</span> <span style="color: #b0c4de;">:initform</span> nil)
   (tooltip <span style="color: #b0c4de;">:accessor</span> tooltip <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:tooltip</span> <span style="color: #b0c4de;">:initform</span> nil)
   (tabindex <span style="color: #b0c4de;">:accessor</span> tabindex <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:tabindex</span> <span style="color: #b0c4de;">:initform</span> nil))
  (<span style="color: #b0c4de;">:default-initargs</span> <span style="color: #b0c4de;">:dom-id</span> (js:gen-js-name-string <span style="color: #b0c4de;">:prefix</span> <span style="color: #b3b3b3;">"_ucw_"</span>)))
</pre>

<p>Fields are rendered into the extended <code>&lt;ucw:input</code> yaclml tag which
supports a few fancy features. The <code>:accessor</code> for all form elements is
set to <code>(client-value FIELD)</code>, and you should use <code>value</code> to access the
Lisp value associated with it.</p>

<pre class="src">
(deftag-macro &lt;ucw:input (<span style="color: #98fb98;">&amp;attribute</span> accessor action reader writer name id (default nil)
                          <span style="color: #98fb98;">&amp;allow-other-attributes</span> others)
  <span style="color: #b3b3b3;">"Generic INPUT tag replacement.

If the ACCESSOR attribute is specified then it must be a PLACE
and it's value will be used to fill the input, when the form is
submitted it will be set to the new value.

If ACTION is specefied then when the form is submitted via this
input type=\"submit\" tag the form will be eval'd. when the
submit (or image) is clicked. DEFAULT means that the ACTION
provided for this input tag will be the default action of the
form when pressing enter in a form field. If more then one, then
the latest wins."</span>)
</pre>

<p>Validation of form fields are supported by adding to the validators
list.</p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">validator</span> ()
  ((message <span style="color: #b0c4de;">:accessor</span> message <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:message</span> <span style="color: #b0c4de;">:initform</span> nil)))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">validate</span> (field validator)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Validate a form-field with a validator."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">javascript-check</span> (field validator)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Generate javascript code for checking FIELD against VALIDATOR.

This is the convenience entry point to generate-javascript-check,
methods defined on this generic funcition should return a list of
javascript code (as per parenscript) which tests against the
javascript variable value."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">javascript-invalid-handler</span> (field validator)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"The javascript code body for when a field is invalid."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">javascript-valid-handler</span> (field validator)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Generate the javascript body for when a field is valid."</span>))
</pre>

<h5>Standard Form Fields</h5>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">string-field</span> (generic-html-input)
  ((input-size) (maxlength)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">password-field</span> (string-field))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">number-field</span> (string-field))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">integer-field</span> (number-field))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">in-field-string-field</span> (string-field)
  ((in-field-label <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"This slot, if non-NIL, will be
                   used as an initial field label. An initial
                   field label is a block of text which is placed
                   inside the input element and removed as soon
                   as the user edits the field. Obviously this
                   field is overidden by an initial :client-value
                   argument."</span>)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">textarea-field</span> (generic-html-input)
  ((rows) (cols)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">date-field</span> (form-field widget-component)
  ((year) (month) (day)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">dmy-date-field</span> (date-field)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Date fields which orders the inputs day/month/year"</span>))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">mdy-date-field</span> (date-field))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">select-field</span> (generic-html-input)
  ((data-set <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"The values this select chooses
             from."</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Form field used for selecting one value from a
  list of available options."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">render-value</span> (select-field value)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"This function will be passed each value in the field's
   data-set and must produce the body of the corresponding
   &lt;ucw:option tag."</span>))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">mapping-select-field</span> (select-field)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Class used when we want to chose the values of
  a certain mapping based on the keys. We render the keys in the
  select and return the corresponding value from the VALUE
  method."</span>))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">hash-table-select-field</span> (mapping-select-field))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">alist-select-field</span> (mapping-select-field))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">plist-select-field</span> (mapping-select-field))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">radio-group</span> (generic-html-input)
  ((value-widgets)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">radio-button</span> (generic-html-input)
  ((value)
   (group <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"The RADIO-GROUP this button is a part
          of."</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A widget representing a single radio
  button. Should be used in conjunction with a RADIO-GROUP."</span>))

(<span style="color: #00ffff;">defmethod</span> <span style="color: #87cefa;">add-value</span> ((group radio-group) value)
  <span style="color: #b3b3b3;">"Adds radio-button with value to group"</span>)

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">checkbox-field</span> (generic-html-input))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">file-upload-field</span> (generic-html-input))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">submit-button</span> (generic-html-input)
  ((label)))
</pre>

<h5>File Upload Field</h5>

<p>Calling <code>value</code> on a <code>file-upload-field</code> returns a mime encoded body
part. <code>(mime-part-body (value FIELD))</code> will return a <strong>binary stream</strong>
attached to the contents of the file. The <code>Content-Type</code> header should
be set to the MIME type of the file being uploaded.</p>

<pre class="src">
(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">mime-part-headers</span> (mime-part)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Returns an alist of the headers of MIME-PART.

The alist must be of the form (NAME . VALUE) where both NAME and
VALUE are strings."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">mime-part-body</span> (mime-part)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Returns the body of MIME-PART."</span>))
</pre>


<h5>Standard Validators</h5>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">not-empty-validator</span> (validator))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">value-validator</span> (validator)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Validators that should only be applied if there is a value.
That is, they always succeed on nil."</span>))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">length-validator</span> (value-validator)
  ((min-length <span style="color: #b0c4de;">:accessor</span> min-length <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:min-length</span>
               <span style="color: #b0c4de;">:initform</span> nil)
   (max-length <span style="color: #b0c4de;">:accessor</span> max-length <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:max-length</span>
               <span style="color: #b0c4de;">:initform</span> nil)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">string=-validator</span> (validator)
  ((other-field <span style="color: #b0c4de;">:accessor</span> other-field <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:other-field</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Ensures that a field is string= to another one."</span>))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">regex-validator</span> (value-validator)
  ((regex <span style="color: #b0c4de;">:accessor</span> regex <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:regex</span> <span style="color: #b0c4de;">:initform</span> nil)))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">e-mail-address-validator</span> (regex-validator))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">phone-number-validator</span> (regex-validator))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">is-a-number-validator</span> (value-validator))
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">is-an-integer-validator</span> (is-a-number-validator))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">number-range-validator</span> (is-a-number-validator)
  ((min-value <span style="color: #b0c4de;">:accessor</span> min-value <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:min-value</span> <span style="color: #b0c4de;">:initform</span> nil)
   (max-value <span style="color: #b0c4de;">:accessor</span> max-value <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:max-value</span> <span style="color: #b0c4de;">:initform</span> nil)))
</pre>


<h5>Simple Form Helper</h5>

<p>UCW provides a helper class for developing forms. Subclass and add the
elements you wish to include in the form. A <code>:wrapping</code> method renders
the form boilerplate and then calls your <code>render</code>.</p>

<pre class="src">
(defcomponent simple-form (html-element)
  ((submit-method <span style="color: #b0c4de;">:accessor</span> submit-method
                  <span style="color: #b0c4de;">:initform</span> <span style="color: #b3b3b3;">"post"</span>
                  <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:submit-method</span>)
   (dom-id <span style="color: #b0c4de;">:accessor</span> dom-id
           <span style="color: #b0c4de;">:initform</span> (js:gen-js-name-string <span style="color: #b0c4de;">:prefix</span> <span style="color: #b3b3b3;">"_ucw_simple_form_"</span>)
           <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:dom-id</span>))
  (<span style="color: #b0c4de;">:default-initargs</span> <span style="color: #b0c4de;">:dom-id</span> <span style="color: #b3b3b3;">"ucw-simple-form"</span>))
</pre>


<h4><a name="sec12" id="sec12"></a>
Templates</h4>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/template.lisp">src/components/template.lisp</a></p>

<p>Infrastructure for loading TAL templates as a view of a component.</p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">template-component</span> (component))
(defcomponent simple-template-component (template-component)
  ((environment <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:environment</span> <span style="color: #b0c4de;">:initform</span> nil)))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">template-component-environment</span> (component)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Create the TAL environment for rendering COMPONENT's template.

Methods defined on this generic function must return a TAL
environment: a list of TAL binding sets (see the documentation
for YACLML:MAKE-STANDARD-ENVIRONMENT for details on TAL
environments.)"</span>)
  (<span style="color: #b0c4de;">:method-combination</span> nconc))

(<span style="color: #00ffff;">defmethod</span> <span style="color: #87cefa;">template-component-environment</span> nconc ((component template-component))
  <span style="color: #b3b3b3;">"Create the basic TAL environment.

Binds the symbol ucw:component to the component object itself,
also puts the object COMPONENT on the environment (after the
binding of ucw:component) so that slots are, by default,
visable."</span>
  (make-standard-environment `((component . ,component)) component))

(<span style="color: #00ffff;">defmethod</span> <span style="color: #87cefa;">render</span> ((component template-component))
  <span style="color: #b3b3b3;">"Render a template based component.

Calls the component's template. The name of the template is the
value returned by the generic function
template-component.template-name, the template will be rendered
in the environment returned by the generic function
template-component-environment."</span>
  (render-template *context*
                   (template-component.template-name component)
                   (template-component-environment component)))

</pre>

<p>Subclass and override methods. <code>simple-template-component</code> only provides
the ability to set environment variables in initarg. Subclass to
provide automagic template file name generation and such.</p>


<h4><a name="sec13" id="sec13"></a>
Utility Mixin Components</h4>

<h5>Range View</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/range-view.lisp">src/components/range-view.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">range-view</span> (template-component)
  (<span style="color: #b0c4de;">:default-initargs</span> <span style="color: #b0c4de;">:template-name</span> <span style="color: #b3b3b3;">"ucw/range-view.tal"</span>)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Component for showing the user a set of data one \"window\" at a time.

The data set is presented one \"window\" at a time with links to
the the first, previous, next and last window. Each window shows
at most WINDOW-SIZE elements of the data. The data is passed to
the range-view at instance creation time via the :DATA initarg.

The generic function RENDER-RANGE-VIEW-ITEM is used to render
each item of DATA.

In order to change the rendering of the single elements of a
range view developer's should create a sub class of RANGE-VIEW
and define their RENDER-RANGE-VIEW-ITEM methods on that."</span>)
  (<span style="color: #b0c4de;">:metaclass</span> standard-component-class))
</pre>

<pre class="src">
(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">render-range-view-item</span> (range-view item)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Render a single element of a range-view."</span>)
  (<span style="color: #b0c4de;">:method</span> ((range-view range-view) (item t))
    <span style="color: #b3b3b3;">"Standard implementation of RENDER-RANGE-VIEW-ITEM. Simply
applies ITEM to princ (via &lt;:as-html)."</span>
    (<span style="color: #00ffff;">declare</span> (ignore range-view))
    (&lt;:as-html item)))
</pre>


<h5>Widget</h5>

<p>Mixin with existing component to wrap in a div or span. This is handy
for defining lightweight widgets embedded within other components.</p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/html-element.lisp">src/components/html-element.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">html-element</span> (component)
  ((css-class)
   (dom-id)
   (css-style)
   (extra-tags)
   (events))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"An HTML element.

HTML elements control aspects that are relevant to almost all tags.

Firstly they provide a place to store the class, id, and style of the
component. The specific render methods of the components themselves
must pass these values to whatever code is used to render the actual
tag.

Secondly, they allow javascript event handlers to be registered for a
tag. The events slot can be filled with a list of lists in the form

 (event parenscript-statement*)

For example (\"onclick\" (alert \"You clicked!\") (return nil)). If
the element has a dom-id, these event handlers are automatically
added."</span>))
</pre>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/widget.lisp">src/components/widget.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">widget-component</span> (html-element)
  ()
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A widget which should be wrapped in a &lt;div&gt;."</span>))

(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">inline-widget-component</span> (html-element)
  ()
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A widget which should be wrapped in &lt;span&gt; and not &lt;div&gt;"</span>))

(<span style="color: #00ffff;">defmethod</span> <span style="color: #87cefa;">render</span> <span style="color: #b0c4de;">:wrap-around</span> ((widget widget-component)))
(<span style="color: #00ffff;">defmethod</span> <span style="color: #87cefa;">render</span> <span style="color: #b0c4de;">:wrap-around</span> ((widget inline-widget-component)))
</pre>


<h5>Transactions</h5>

<p>A mixin to provide transactions. <code>(open-transaction component)</code> and
<code>(close-transaction component)</code> open and closed nested
transactions. After a transaction has been closed an attempt to
backtrack into a step inside the transaction will result in jumping up
one level of transactions (or out of the transaction entirely if at
the top level). This ensures that the transaction is only run once,
naturally.</p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/transaction-mixin.lisp">src/components/transaction-mixin.lisp</a></p>

<pre class="src">
(defcomponent transaction-mixin ()
  (...))

(defmethod/cc open-transaction ((comp transaction-mixin)))
(defmethod/cc close-transaction ((comp transaction-mixin)))
</pre>


<h5>Task</h5>

<p><code>(defaction start ...)</code> on subclass to run a series of actions bundled
into a task.</p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/task.lisp">src/components/task.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">task-component</span> (standard-component)
  (...)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A controller for a single task or operation to
  be performed by the user.

  A task component's START action is called as soon as the
component is instantiated. Task components do not have their own
RENDER method, in fact they have no graphical representation but
serve only to order a sequence of other components."</span>))

(defgeneric/cc start (task)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"action which gets called automatically when
task-component is active. Use defaction to define your own
\"start\" action"</span>))
</pre>


<h5>Cached</h5>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/components/cached.lisp">src/components/cached.lisp</a></p>

<pre class="src">
(defcomponent cached-component ()
  ((cached-output <span style="color: #b0c4de;">:accessor</span> cached-output <span style="color: #b0c4de;">:initform</span> nil
                  <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"A string holding the output to
                  use for this component. This string will be
                  written directly to the html stream and is
                  changed by the REFRESH-COMPONENT-OUTPUT
                  method."</span> )
   (timeout <span style="color: #b0c4de;">:accessor</span> timeout <span style="color: #b0c4de;">:initarg</span> <span style="color: #b0c4de;">:timeout</span>
            <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"An value specifying how often this
            component needs to be refreshed. The exact
            interpretation of the value depends on the type of
            caching used class."</span>))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Component which caches its output.

The component caching API is built around the generic functions
COMPONENT-DIRTY-P and REFRESH-COMPONENT-OUTPUT and a method on
RENDER, see the respective docstrings for more details.

Do not use CACHED-COMPONENT directly, use one its subclasses."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">component-dirty-p</span> (component)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Returns T is COMPONENT's cache is invalid."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">update-cache</span> (component)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Update COMPONENT's cache variables after a refresh."</span>))

(defcomponent timeout-cache-component (cached-component)
  ((last-refresh <span style="color: #b0c4de;">:accessor</span> last-refresh <span style="color: #b0c4de;">:initform</span> nil
                 <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"The time, exrpessed as a
                 universal time, when the component was last rendered."</span>))
  (<span style="color: #b0c4de;">:default-initargs</span>
   <span style="color: #b0c4de;">:timeout</span> (* 30 60 60))
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Render the component at most every TIMEOUT seconds."</span>))

(defcomponent num-hits-cache-component (cached-component)
  ((hits-since-refresh <span style="color: #b0c4de;">:accessor</span> hits-since-refresh
                       <span style="color: #b0c4de;">:initform</span> nil
                       <span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Number of views since last refresh."</span>))
  (<span style="color: #b0c4de;">:default-initargs</span> <span style="color: #b0c4de;">:timeout</span> 10)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Render the component every TIMEOUT views."</span>))
</pre>

<p>Subclass and override <code>component-dirty-p</code> to do something useful
(e.g. flip mark bit when object being presented changes).</p>


<h3><a name="sec14" id="sec14"></a>
Control Flow</h3>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/standard-component/control-flow.lisp">src/rerl/standard-component/control-flow.lisp</a></p>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/standard-action.lisp">src/rerl/standard-action.lisp</a></p>

<h4><a name="sec15" id="sec15"></a>
Calling</h4>

<p class="first">Most of what you do in UCW will be calling components so this is a bit
important. Note that calling interrupts the current control flow so if
you want to render a component in place as part of another component
just call <code>render</code> on it instead.</p>

<pre class="src">
(<span style="color: #00ffff;">defmacro</span> <span style="color: #87cefa;">call</span> (component-type <span style="color: #98fb98;">&amp;rest</span> component-init-args)
  <span style="color: #b3b3b3;">"Stop the execution of the current action and pass control to
a freshly created component of type COMPONENT-TYPE.

COMPONENT-INIT-ARGS are passed directly to the underlying
make-instance call. This form will return if and when the call'd
component calls answer, the value returned by this form is
whatever the call'd component passed to answer.

Notes:

This macro assumes that the lexcial variable UCW:SELF is bound to
the calling component."</span>)

(answer VAL) <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">answer parent component ONLY IN ACTIONS
</span>
(ok SELF VAL) <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">Used to answer a component anywhere and what answer
</span>              <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">expands into
</span>
(jump COMPONENT-NAME <span style="color: #98fb98;">&amp;REST</span> ARGS) <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">is similar to call, but replaces
</span>                                 <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">the current component with the new
</span>                                 <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">one and drops any backtracks (back
</span>                                 <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">button will no longer work)
</span></pre>

<p><code>(call COMPONENT-NAME &amp;ARGS INIT-ARGS)</code> calls <code>COMPONENT-NAME</code> and returns
the value returned by <code>(ok SELF RETURN-VALUE)</code> called from within
<code>COMPONENT-NAME</code></p>


<h4><a name="sec16" id="sec16"></a>
Actions</h4>

<p class="first">Actions are methods on components. The first argument <strong>must</strong> be a
component for most of UCW to work.</p>

<pre class="src">
(defaction NAME (first ...) ...)
 <span style="color: #ff7f24;">;  </span><span style="color: #ff7f24;">(roughly) expands into
</span>(defmethod/cc NAME (first ...)
  (<span style="color: #00ffff;">let</span> ((self first))
    ...))
</pre>

<p><code>Self</code> being bound in the current lexical environment is required for
most UCW control flow things to work. <code>defaction</code> hides this from you,
and was a big source of confusion for me early on (mostly &quot;hmm, why is
this not working ... where did that come from in the
macroexpansion!&quot;).</p>


<h4><a name="sec17" id="sec17"></a>
Entry Points</h4>

<pre class="src">
(defentry-point url (<span style="color: #b0c4de;">:application</span> APPLICATION
                     <span style="color: #b0c4de;">:class</span> DISPATCHER-CLASS)
   (PARAM1 ... PARAMN) <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">GET / POST vars, bound in body
</span>  body)
</pre>

<p>An entry point is what it sounds like: a static URL matched using the
mater of <code>DISPATCHER-CLASS</code> that enters into <code>APPLICATION</code> running the
code in <code>body</code>. An example from a test program I have written
follows. The entry point allows files to be streamed to user when the
url audio.ucw?file=FOO is used.</p>

<pre class="src">
(defentry-point <span style="color: #b3b3b3;">"^(audio.ucw|)$"</span> (<span style="color: #b0c4de;">:application</span> *golf-test-app*
                                  <span style="color: #b0c4de;">:class</span> regexp-dispatcher)
    (file)
  (call 'audio-file-window
   <span style="color: #b0c4de;">:audio-file</span> (make-instance 'audio-file
                <span style="color: #b0c4de;">:type</span> <span style="color: #b0c4de;">:vorbis</span>
                <span style="color: #b0c4de;">:data</span> (file-&gt;bytes (open
                                    file
                                    <span style="color: #b0c4de;">:element-type</span> 'unsigned-byte)))))
</pre>


<h3><a name="sec18" id="sec18"></a>
Dispatching</h3>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/rerl/standard-dispatcher.lisp">src/rerl/standard-dispatcher.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">matcher-match</span> (matcher application context)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Abstract method for subclasses to implement a
matcher.  This method would return multiple-values according to
matcher internal nature.

No methods defined on this function may rebind *context*, nor
change CONTEXT's application. Only if the method matches the
request, it is allowed to modify CONTEXT or APPLICATION, even in
that case methods defined on this function must not modify
CONTEXT's application nor rebind *context*."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">handler-handle</span> (handler application context matcher-result)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Abstract function for handler classes to
implement in order to handle a request matched by relevant
matcher.

These methods may modify context as they wish since they'r
matched, request will be closed after this method is run."</span>))

(<span style="color: #00ffff;">defgeneric</span> <span style="color: #87cefa;">dispatch</span> (dispatcher application context)
  (<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"Entry point into a dispatcher. Must return T
  if the context has been handled or NIL if it hasn't.

No methods defined on this function may rebind *context*, nor
change CONTEXT's application. Only if the method returns T is it
allowed to modify CONTEXT or APPLICATION, even in that case
methods defined on this function must not modify CONTEXT's
application nor rebind *context*."</span>))
</pre>

<pre class="src">
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">my-matcher</span>    (abstract-matcher)    ...)
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">my-handler</span>    (abstract-handler)    ...)
(<span style="color: #00ffff;">defclass</span> <span style="color: #98fb98;">my-dispatcher</span> (abstract-dispatcher my-matcher my-handler)
  ...)
</pre>

<h4><a name="sec19" id="sec19"></a>
Simple Dispatcher</h4>

<pre class="src">
(<span style="color: #b0c4de;">:documentation</span> <span style="color: #b3b3b3;">"This class of dispatchers avoids all of UCW's
  standard call/cc (and therefore frame/backtracking/component)
  mechanism.

Unlike all other UCW dispatchers a simple-dispatcher must not use
CALL, and must perform the rendering directly within the handler."</span>)
</pre>


<h3><a name="sec20" id="sec20"></a>
Server</h3>

<p><a href="http://www.uncommon-web.com/darcsweb/darcsweb.cgi?r=ucw_dev;a=headblob;f=/src/control.lisp">src/control.lisp</a></p>

<pre class="src">
(<span style="color: #00ffff;">defun</span> <span style="color: #87cefa;">create-server</span> (<span style="color: #98fb98;">&amp;key</span>
                      (backend `(,*ucw-backend-type* <span style="color: #b0c4de;">:host</span> ,*ucw-backend-host*
                                 <span style="color: #b0c4de;">:port</span> ,*ucw-backend-port*))
                      (applications *ucw-applications*)
                      (start-p t)
                      (server-class *ucw-server-class*)
                      (log-root-directory (truename *ucw-log-root-directory*))
                      (log-level *ucw-log-level*))
  <span style="color: #b3b3b3;">"Creates and returns a UCW server according to SERVER-CLASS, HOST and
PORT. Affects *DEFAULT-SERVER*.

BACKEND is a list of (BACKEND-TYPE &amp;rest INITARGS). BACKEND-TYPE
may be :HTTPD, :MOD-LISP, :ASERVE, :ARANEIDA, an existing
backend, an existing UCW server backend or :DEFAULT in which case
it attempts to return a sane default from the UCW backends loaded
and available, or any other value for which a valid MAKE-BACKEND
method has been defined. INITARGS will be passed, unmodified, to
MAKE-BACKEND.

APPLICATIONS is a list of defined applications to be loaded into the
server.

Logs are generated in verbosity defined by LOG-LEVEL and directed to
LOG-ROOT-DIRECTORY if defined."</span>
  ...
  server) <span style="color: #ff7f24;">; </span><span style="color: #ff7f24;">return server, naturally
</span></pre>


<h3><a name="sec21" id="sec21"></a>
Debugging</h3>

<h4><a name="sec22" id="sec22"></a>
Inspector</h4>

<p><a href="/home/clinton/src/ucw/darcs/ucw_dev/src/components/ucw-inspector.lisp">/home/clinton/src/ucw/darcs/ucw_dev/src/components/ucw-inspector.lisp</a></p>

<pre class="src">
(defaction call-inspector ((component component) datum)
  <span style="color: #b3b3b3;">"Call an inspector for DATUM on the component COMPONENT."</span>
  (call 'ucw-inspector <span style="color: #b0c4de;">:datum</span> datum))
</pre>


<h2><a name="sec23" id="sec23"></a>
Tips</h2>

<h3><a name="sec24" id="sec24"></a>
Getting dojo to load</h3>

<p class="first">I had some trouble getting dojo to work properly with UCW. The way
that the <code>:www-roots</code> option for an application works is a bit
confusing, and it is unforgiving if you mess the pathname up. A
directory <strong>must</strong> have a <code>/</code> at the end, and the directory you are serving
must also have the <code>/</code> (which is counterintuitive given the behavior of
most unix things that don't want the <code>/</code> at the end of the name).</p>

<pre class="src">
<span style="color: #b0c4de;">:www-roots</span> (list '(<span style="color: #b3b3b3;">"dojo/"</span> .
                   #P<span style="color: #b3b3b3;">"/home/clinton/src/ucw/darcs/ucw_dev/wwwroot/dojo/"</span>))
</pre>


<h3><a name="sec25" id="sec25"></a>
Specials Bound During Rendering</h3>

<p class="first">The current request context is bound to <code>ucw:*context*</code>, and the current
component is bound to <code>ucw:*current-component*</code> in the dynamic extent of
<code>render</code>.</p>


<h3><a name="sec26" id="sec26"></a>
Printing to the yaclml stream</h3>

<p class="first">Occasionally it can be useful to do something like write a byte array
as an ascii string to the client. Inside of <code>render</code> the variable
<code>yaclml:*yaclml-stream*</code> is bound to the stream that you can write to if
you wish to have content interspersed with yaclml tags.</p>


  <!-- Page published by Emacs Muse ends here -->

  <p class="cke-buttons">
    <!-- validating badges, any browser, etc -->
    <a href="http://validator.w3.org/check/referer"><img
	src="http://www.w3.org/Icons/valid-xhtml10"
	alt="Valid XHTML 1.0!" /></a>
    
    <a href="http://www.anybrowser.org/campaign/"><img
	src="img/buttons/w3c_ab.png" alt="[ Viewable With Any Browser
	]" /></a>

    <a href="http://www.debian.org/"><img
	src="img/buttons/debian.png" alt="[ Powered by Debian ]" /></a>
    
    <a href="http://hcoop.net/">
      <img src="img/buttons/hcoop.png" 
	alt="[ Hosted by HCoop]" />
    </a>

    <a href="http://www.fsf.org/register_form?referrer=114">
      <img src="img/buttons/fsf_member.png"
	alt="[ FSF Associate Member ]" />
    </a>
  </p>

<p class="cke-footer">                     How can you accept social supression                      
                      This weak state of mind in our time                      
                        I demand release from hypocrisy                        
                 I'd rather die than be held down, forced down                 

</p>
<p class="cke-timestamp">Last Modified:
    March 13, 2008</p>
  </body>
</html>