HCoop Git - clinton/website/site/unknownlamer.org.git/blame_incremental

... / ...

Commit	Line	Data
	1	<?xml version="1.0" encoding="utf-8" ?>
	2	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
	3	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
	4	<html xmlns="http://www.w3.org/1999/xhtml">
	5	<head>
	6	<title>Roadmap to UCW Codebase</title>
	7	<meta name="generator" content="muse.el" />
	8	<meta http-equiv="Content-Type"
	9	content="text/html; charset=utf-8" />
	10	<link href="http://feeds.unknownlamer.org/rss/site-updates"
	11	rel="alternate" type="application/rss+xml" title="Updates Feed" />
	12
	13	<link rel="stylesheet" href="default.css" />
	14	</head>
	15	<body>
	16	<h1>Roadmap to UCW Codebase</h1>
	17	<div class="contents">
	18	<dl>
	19	<dt>
	20	<a href="#sec1">Abstract</a>
	21	</dt>
	22	<dt>
	23	<a href="#sec2">Roadmap</a>
	24	</dt>
	25	<dd>
	26	<dl>
	27	<dt>
	28	<a href="#sec3">Applications</a>
	29	</dt>
	30	<dd>
	31	<dl>
	32	<dt>
	33	<a href="#sec4">Cookie</a>
	34	</dt>
	35	<dt>
	36	<a href="#sec5">L10n</a>
	37	</dt>
	38	<dt>
	39	<a href="#sec6">Secure</a>
	40	</dt>
	41	</dl>
	42	</dd>
	43	<dt>
	44	<a href="#sec7">Components</a>
	45	</dt>
	46	<dd>
	47	<dl>
	48	<dt>
	49	<a href="#sec8">Windows</a>
	50	</dt>
	51	<dt>
	52	<a href="#sec9">Containers</a>
	53	</dt>
	54	<dt>
	55	<a href="#sec10">Dialogs</a>
	56	</dt>
	57	<dt>
	58	<a href="#sec11">Forms</a>
	59	</dt>
	60	<dt>
	61	<a href="#sec12">Templates</a>
	62	</dt>
	63	<dt>
	64	<a href="#sec13">Utility Mixin Components</a>
	65	</dt>
	66	</dl>
	67	</dd>
	68	<dt>
	69	<a href="#sec14">Control Flow</a>
	70	</dt>
	71	<dd>
	72	<dl>
	73	<dt>
	74	<a href="#sec15">Calling</a>
	75	</dt>
	76	<dt>
	77	<a href="#sec16">Actions</a>
	78	</dt>
	79	<dt>
	80	<a href="#sec17">Entry Points</a>
	81	</dt>
	82	</dl>
	83	</dd>
	84	<dt>
	85	<a href="#sec18">Dispatching</a>
	86	</dt>
	87	<dd>
	88	<dl>
	89	<dt>
	90	<a href="#sec19">Simple Dispatcher</a>
	91	</dt>
	92	</dl>
	93	</dd>
	94	<dt>
	95	<a href="#sec20">Server</a>
	96	</dt>
	97	<dt>
	98	<a href="#sec21">Debugging</a>
	99	</dt>
	100	<dd>
	101	<dl>
	102	<dt>
	103	<a href="#sec22">Inspector</a>
	104	</dt>
	105	</dl>
	106	</dd>
	107	</dl>
	108	</dd>
	109	<dt>
	110	<a href="#sec23">Tips</a>
	111	</dt>
	112	<dd>
	113	<dl>
	114	<dt>
	115	<a href="#sec24">Getting dojo to load</a>
	116	</dt>
	117	<dt>
	118	<a href="#sec25">Specials Bound During Rendering</a>
	119	</dt>
	120	<dt>
	121	<a href="#sec26">Printing to the yaclml stream</a>
	122	</dt>
	123	</dl>
	124	</dd>
	125	</dl>
	126	</div>
	127
	128
	129	<!-- Page published by Emacs Muse begins here --><h2><a name="sec1" id="sec1"></a>
	130	Abstract</h2>
	131
	132	<p><a href="http://common-lisp.net/project/ucw/">UnCommon Web</a> is a very powerful and mature web framework for Common
	133	Lisp, but is a bit difficult to learn. It is documented
	134	extensively—in the form of docstrings. These are extremely helpful
	135	once you've figured out the rough structure of UCW, but they are of no
	136	help when first learning unless you just read most of the source. I
	137	ended up having to do that, and after some urging along by folks in
	138	<code>#ucw</code> I decided to clean up my planner notes and publish them for
	139	public consumption.</p>
	140
	141	<p>The roadmap is presented with major sections ordered in a logical
	142	order for learning the framework. The sections are ordered internally
	143	in order of most immediately useful to least, but it may be worth
	144	hopping between major sections before reading all of the details. I
	145	have used abridged class definitions and docstrings with occasional
	146	commentary to clarify things.</p>
	147
	148
	149	<h2><a name="sec2" id="sec2"></a>
	150	Roadmap</h2>
	151
	152	<h3><a name="sec3" id="sec3"></a>
	153	Applications</h3>
	154
	155	<p class="first">Applications are a bundle of entry points. The base class is,
	156	naturally, <code>standard-application</code>, but you should instead derive your
	157	application class from <code>modular-application</code> and any standard or custom
	158	application mixins you find useful.</p>
	159
	160	<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>
	161
	162	<pre class="src">
	163	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">standard-application</span> (application)
	164	((url-prefix <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:url-prefix</span>
	165	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A string specifying the
	166	start (prefix) of all the urls this app should handle.
	167
	168	This value is used by the standard-server to decide what app a
	169	particular request is aimed at and for generating links to
	170	actions within the app. "</span>)
	171	(www-roots <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:www-roots</span>
	172	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A list of directories (pathname
	173	specifiers) or cons-cell (URL-subdir . pathname) to use when looking for static files."</span>)
	174	(dispatchers <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:dispatchers</span>
	175	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A list of request
	176	dispatchers. The user supplied list of dispatchers is extended
	177	with other dispatchers that are required for UCW to function
	178	properly (action-dispatcher, a parenscript-dispatcher, etc). If
	179	you want full control over the active dispatchers use the (setf
	180	application.dispatchers) accessor or, if you want control over
	181	the order of the dispathcers, (slot-value instance
	182	'dispatchers)."</span>))
	183	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"The default UCW application class."</span>))
	184	</pre>
	185
	186	<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>
	187
	188	<pre class="src">
	189	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">modular-application-mixin</span> ()
	190	()
	191	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Superclass for all application mixins."</span>))
	192
	193	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">modular-application</span> (standard-application modular-application-mixin)
	194	...)
	195	</pre>
	196
	197	<h4><a name="sec4" id="sec4"></a>
	198	Cookie</h4>
	199
	200	<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>
	201
	202	<pre class="src">
	203	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">cookie-session-application-module</span> (modular-application-mixin)
	204	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Class for applications which use cookies for sesion tracking.
	205
	206	Cookie session applications work exactly like
	207	standard-applications except that when the session is not found
	208	using the standard mechanisms the id is looked for in a cookie."</span>))
	209	</pre>
	210
	211	<p>This is the most useful of the application components. It makes your
	212	application urls readable by stashing the session id into a cookie
	213	rather than as a set of long and ugly GET parameters.</p>
	214
	215
	216	<h4><a name="sec5" id="sec5"></a>
	217	L10n</h4>
	218
	219	<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>
	220
	221	<pre class="src">
	222	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">l10n-application-module</span> (modular-application-mixin)
	223	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Application class which can handle l10n requests."</span>))
	224	</pre>
	225
	226
	227	<h4><a name="sec6" id="sec6"></a>
	228	Secure</h4>
	229
	230	<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>
	231
	232	<pre class="src">
	233	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">secure-application-module</span> (modular-application-mixin)
	234	(<span class="emacs-face-builtin">:documentation</span>
	235	<span class="emacs-face-string">"Mixin class for applications which require authorized access.
	236	Concrete application must specialize the following methods:
	237	APPLICATION-FIND-USER (APPLICATION USERNAME)
	238	APPLICATION-CHECK-PASSWORD (APPLICATION USER PASSWORD)
	239	APPLICATION-AUTHORIZE-CALLZE-CALL (APPLICATION USER FROM-COMPONENT TO-COMPONENT)."</span>))
	240	</pre>
	241
	242
	243
	244	<h3><a name="sec7" id="sec7"></a>
	245	Components</h3>
	246
	247	<p class="first">A component is a special class that handles the complexities of
	248	continuation suspension and such for you. New components are derived
	249	from the existing ones by using <code>defcomponent</code> instead of <code>defclass</code>. This
	250	adds a few extra slot and class options, and ensures that the proper
	251	metaclass is set.</p>
	252
	253	<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>
	254
	255	<pre class="src">
	256	(<span class="emacs-face-keyword">defmacro</span> <span class="emacs-face-function-name">defcomponent</span> (name supers slots <span class="emacs-face-type">&rest</span> options)
	257	<span class="emacs-face-doc">"Macro for defining a component class.
	258
	259	This macro is used to create component classes and provides
	260	options for easily creating the methods which often accompany a
	261	component definition.
	262
	263	NAME, SUPERS and SLOTS as treated as per defclass. The following
	264	extra options are allowed:
	265
	266	(:ENTRY-POINT url (&key application class)) - Define an
	267	entry-point on the url URL which simply calls an instance of
	268	this component. Any request parameters passed to the entry-point
	269	are used to initialize the slots in the component. This option
	270	may appear multiple times.
	271
	272	(:DEFAULT-BACKTRACK function-designator) - Unless the slots
	273	already have a :backtrack option FUNCTION-DESIGNATOR is
	274	added. As with the 'regular' :backtrack options if you pass T
	275	here it is assumed to mean #'IDENTITY.
	276
	277	(:RENDER (&optional COMPONENT) &body BODY) - Generate a render
	278	method specialized to COMPONENT. COMPONENT may be a symbol, in
	279	which case the method will be specialized on the componnet
	280	class. If COMPONNET is omited the component is bound to a
	281	variable with the same name as the class.
	282
	283	(:ACTION &optional NAME) - Generate a defaction form named
	284	NAME (which defaults to the name of the component) which simply
	285	CALL's this component class passing all the arguments passed to
	286	the action as initargs."</span>)
	287
	288	<span class="emacs-face-comment-delimiter">;;; </span><span class="emacs-face-comment">Extra Slot Options
	289	</span><span class="emacs-face-string">"Other than the initargs for standard slots the following
	290	options can be passed to component slots:
	291
	292	:backtrack [ T \| NIL \| FUNCTION-NAME ] - Specify that this slot
	293	should be backtracked (or not if NIL is passed as the value). If
	294	the value is neither T nor NIL then it must be a function which
	295	will be used as the copyer.
	296
	297	:component [ TYPE \| ( TYPE &rest INITARGS ) ] - Specify that this
	298	slot is actually a nested component of type TYPE. When instances
	299	of the class are created this slot will be set to an instance of
	300	type TYPE and it's place will be set to this slot. If a list is
	301	passed to :component then TYPE (which isn't evaluated) will be
	302	passed as the first argument to make-instance. The INITARGS will
	303	be eval'd and apply'd to make-instance. The result of this call
	304	to make-instance will be used as the effective component
	305	object."</span>
	306	</pre>
	307
	308	<h4><a name="sec8" id="sec8"></a>
	309	Windows</h4>
	310
	311	<p class="first">A window-component represents a top level browser window, naturally.</p>
	312
	313	<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>
	314
	315	<pre class="src">
	316	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">window-component</span> ()
	317	((content-type)))
	318
	319	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">simple-window-component</span> (window-component)
	320	((title)
	321	(stylesheet)
	322	(javascript <span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"List of javascript includes.
	323
	324	Each element must be a list whose first value is either the
	325	symbol :SRC or :JS.
	326
	327	(:SRC url) - writes <script src=\"URL\"></script> tag.
	328	(:JS form) - equivalent to (:SCRIPT (js:js* form))
	329	(:SCRIPT string) - write <script>STRING</script>.
	330
	331	The elements will be rendered in order."</span>)
	332	...))
	333	</pre>
	334
	335	<p><code>window-component</code> could be useful for doing things like dumping binary
	336	data to the user, or just deriving your own funky top level window
	337	type.</p>
	338
	339	<p><code>simple-window-component</code> is the easiest for displaying standard
	340	webpage. It provides a wrapping method on render that displays the
	341	html boilerplate based on your component slot values which is what one
	342	wants most of the time. The initargs to <code>simple-window-component</code> have
	343	the same names as the slots.</p>
	344
	345	<h5>Status Bar</h5>
	346
	347	<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>
	348
	349	<p>There is a generic status bar interface. Messages severity is one of
	350	<code>(:error :warn :info)</code>. Note that the default status bar render method
	351	just shows a div with status messages. A derivative could be defined
	352	to insert messages into the browser status bar.</p>
	353
	354	<pre class="src">
	355	(defcomponent status-bar ()
	356	((messages <span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"An ALIST of the messages to
	357	show. Each element is a cons of the form (SEVERITY .
	358	MESSAGE). SEVERITY is one of :ERROR, :WARN, :INFO and MESSAGE is
	359	a string which will be html-escaped."</span>)
	360	...)
	361	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Stateless status bar to display messages."</span>))
	362
	363	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">add-message</span> (status-bar msg <span class="emacs-face-type">&key</span> severity <span class="emacs-face-type">&allow-other-keys</span>)
	364	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Add the message text MSG to STATUS-BAR with
	365	severity SEVERITY."</span>))
	366	</pre>
	367
	368	<pre class="src">
	369	(defcomponent status-bar-mixin ()
	370	((status-bar <span class="emacs-face-builtin">:accessor</span> status-bar
	371	<span class="emacs-face-builtin">:initarg</span> status-bar
	372	<span class="emacs-face-builtin">:component</span> (status-bar))))
	373
	374	(<span class="emacs-face-keyword">defmethod</span> <span class="emacs-face-function-name">show-status-bar</span> ((win status-bar-mixin))
	375	(render (status-bar win)))
	376
	377	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">show-message</span> (msg <span class="emacs-face-type">&key</span> severity <span class="emacs-face-type">&allow-other-keys</span>)
	378	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Show a message in the status bar. Only works if
	379	current window is a status-bar-mixin"</span>))
	380	</pre>
	381
	382
	383	<h5>Redirect</h5>
	384
	385	<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>
	386
	387	<pre class="src">
	388	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">redirect-component</span> ()
	389	((target <span class="emacs-face-builtin">:accessor</span> target <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:target</span>))
	390	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class)
	391	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Send a client redirect.
	392
	393	This component, which must be used as a window-component,
	394	redirects the client to the url specified in the target slot. A
	395	302 (as opposed to 303) response code is sent to ensure
	396	compatability with older browsers.
	397
	398	The redirect component never answers."</span>))
	399	</pre>
	400
	401	<p>There is also a <code>meta-refresh</code> procedure.</p>
	402
	403	<pre class="src">
	404	(defun/cc meta-refresh ()
	405	<span class="emacs-face-string">"Cause a meta-refresh (a freshly got (GET) url) at this point.
	406	This is useful in order to have a GET url after a form POST's
	407	actions have completed running. The user can then refresh to his
	408	heart's content."</span>)
	409	</pre>
	410
	411
	412
	413	<h4><a name="sec9" id="sec9"></a>
	414	Containers</h4>
	415
	416	<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>
	417
	418	<pre class="src">
	419	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">container</span> ()
	420	(...)
	421	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class)
	422	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Allow multiple components to share the same place.
	423
	424	The container component serves to manage a set of components.
	425	It does not provide any render impementation, which is the
	426	resposibility of the subclasses (e.g. switching-container or
	427	list-container).
	428
	429	Each contained component has a \"key\" associated with it which
	430	is used to retrieve a particular component. Keys are compared with
	431	container.key-test.
	432
	433	The :contents inintarg, if provided, must be either a list of (key .
	434	component) or a list of components. In the latter case it will
	435	be converted into (component . component) form."</span>))
	436	</pre>
	437
	438	<h5>Protocol</h5>
	439
	440	<ul>
	441	<li><code>child-components</code></li>
	442	<li><code>find-component CONTAINER KEY</code></li>
	443	<li><code>remove-component</code></li>
	444	<li><code>(setf find-component CONTAINER KEY) COMPONENT</code> ->
	445	<code>add-component CONTAINER COMPONENT KEY</code></li>
	446	</ul>
	447
	448
	449	<h5>Switching Container</h5>
	450
	451	<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>
	452
	453	<pre class="src">
	454	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">switching-container</span> ...
	455	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A simple renderable container component.
	456
	457	This component is like the regular CONTAINER but serves to manage a set
	458	of components which share the same place in the UI. Therefore it provides
	459	an implementation of RENDER which simply renders its current component.
	460
	461	The switching-container component class is generally used as the super
	462	class for navigatation components and tabbed-pane like
	463	components."</span>))
	464	</pre>
	465
	466	<p>Subclass and <code>(defmethod render :around ...)</code> to render navigation using
	467	<code>(call-next-method)</code> to render the selected component.</p>
	468
	469	<h5>Protocol</h5>
	470
	471	<ul>
	472	<li><code>container.current-component COMPONENT</code></li>
	473	<li><code>(setf container.current-component CONTAINER) COMPONENT</code></li>
	474	</ul>
	475
	476
	477
	478	<h5>Tabbed Pane</h5>
	479
	480	<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>
	481
	482	<pre class="src">
	483	(defcomponent tabbed-pane (switching-container)
	484	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Component for providing the user with a standard \"tabbed pane\" GUI widget."</span>))
	485	</pre>
	486
	487	<p>Provides a generic tabbed pane that renders a nested div split into a
	488	naviation and content box. The navigation box is a set of styled divs
	489	containing the navigation links.</p>
	490
	491
	492
	493	<h4><a name="sec10" id="sec10"></a>
	494	Dialogs</h4>
	495
	496	<p class="first">A few convenience dialogs are provided for grabbing data from the
	497	user.</p>
	498
	499	<h5>login</h5>
	500
	501	<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>
	502
	503	<pre class="src">
	504	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">login</span> ()
	505	((username) (password) (message))
	506	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Generic login (input username and password) component.
	507
	508	This component, which must be embedded in another component,
	509	presents the user with a simple two fielded login form.
	510
	511	When the user attempts a login the action try-login is called,
	512	try-login calls the generic function check-credentials passing it
	513	the login component. If check-credentials returns true then the
	514	login-successful action is called, otherwise the message slot of
	515	the login component is set (to a generic \"bad username\"
	516	message).
	517
	518	The default implementaion of login-successful simply answers t,
	519	no default implementation of check-credentials is
	520	provided. Developers should use sub-classes of login for which
	521	all the required methods have been definined."</span>)
	522	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class))
	523	</pre>
	524
	525	<pre class="src">
	526	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">check-credentials</span> (login)
	527	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Returns T if LOGIN is valid."</span>))
	528
	529	(defaction login-successful ((l login))
	530	(answer t))
	531	</pre>
	532
	533	<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>
	534
	535	<pre class="src">
	536	(defcomponent user-login (simple-window-component status-bar-mixin)
	537	((username string-field) (password password-field)))
	538	</pre>
	539
	540	<p>Used by <code>secure-application-module</code> to provide a user login. Relevant
	541	protocol details follow.</p>
	542
	543	<pre class="src">
	544	(<span class="emacs-face-keyword">defmethod</span> <span class="emacs-face-function-name">check-credentials</span> ((self user-login))
	545	(<span class="emacs-face-keyword">let*</span> ((username (value (username self)))
	546	(password (value (password self)))
	547	(user (find-application-user username)))
	548	(<span class="emacs-face-keyword">when</span> (and user (check-user-password user password))
	549	user)))
	550
	551	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">application-find-user</span> (application username)
	552	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Find USER by USERNAME for APPLICATION."</span>))
	553	</pre>
	554
	555
	556	<h5>error</h5>
	557
	558	<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>
	559
	560	<pre class="src">
	561	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">error-message</span> (simple-window-component)
	562	((message <span class="emacs-face-builtin">:accessor</span> message <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:message</span> <span class="emacs-face-builtin">:initform</span> <span class="emacs-face-string">"ERROR [no message specified]"</span>))
	563	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Generic component for showing server side
	564	error messages."</span>)
	565	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class))
	566
	567	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">error-component</span> (error-message)
	568	((condition <span class="emacs-face-builtin">:accessor</span> error.condition <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:condition</span> <span class="emacs-face-builtin">:initform</span> nil)
	569	(backtrace <span class="emacs-face-builtin">:accessor</span> error.backtrace <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:backtrace</span>))
	570	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Generic component for showing server side
	571	error conditions. Unlike ERROR-MESSAGE this component also
	572	attempts to display a backtrace."</span>)
	573	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class))
	574	</pre>
	575
	576
	577	<h5>message</h5>
	578
	579	<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>
	580
	581	<pre class="src">
	582	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">info-message</span> ()
	583	((message <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:message</span> <span class="emacs-face-builtin">:accessor</span> message)
	584	(ok-text <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:ok-text</span> <span class="emacs-face-builtin">:accessor</span> ok-text <span class="emacs-face-builtin">:initform</span> <span class="emacs-face-string">"Ok."</span>))
	585	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Component for showing a message to the user.
	586
	587	If the OK-TEXT slot is non-NIL component will use that as the
	588	text for a link which, when clicked, causes the component to
	589	answer. It follows that if OK-TEXT is NIL this component will
	590	never answer."</span>)
	591	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class))
	592	</pre>
	593
	594
	595	<h5>option-dialog</h5>
	596
	597	<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>
	598
	599	<pre class="src">
	600	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">option-dialog</span> (template-component)
	601	((message) (options) (confirm))
	602	(<span class="emacs-face-builtin">:default-initargs</span> <span class="emacs-face-builtin">:template-name</span> <span class="emacs-face-string">"ucw/option-dialog.tal"</span>)
	603	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Component for querying the user.
	604
	605	The value of the slot MESSAGE is used as a general heading.
	606
	607	The OPTIONS slot must be an alist of (VALUE . LABEL). LABEL (a
	608	string) will be used as the text of a link which, when clikced,
	609	will answer VALUE.
	610
	611	If the CONFIRM slot is T the user will be presented with a second
	612	OPTION-DIALOG asking the user if they are sure they want to
	613	submit that value."</span>)
	614	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class))
	615	</pre>
	616
	617	<p>A macro to present an option dialog is provided.</p>
	618
	619	<pre class="src">
	620	(<span class="emacs-face-keyword">defmacro</span> <span class="emacs-face-function-name">option-dialog</span> ((message-spec <span class="emacs-face-type">&rest</span> message-args) <span class="emacs-face-type">&body</span> options)
	621	...)
	622	</pre>
	623
	624	<p><code>message-spec</code> is passed to <code>format</code> if <code>message-args</code> are supplied, and
	625	used as a string literal otherwise. This does not provide a way to set
	626	the confirm property which makes the macro not so generally useful.</p>
	627
	628
	629
	630	<h4><a name="sec11" id="sec11"></a>
	631	Forms</h4>
	632
	633	<p class="first">Reasonably useful forms library that integrates easily with TAL.</p>
	634
	635	<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>
	636
	637	<pre class="src">
	638	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">form-field</span> ()
	639	((validators <span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"List of validators which will be
	640	applied to this field."</span>)
	641	(initially-validate <span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"When non-NIL the
	642	validators will be run as soon as the page
	643	is rendered."</span>)))
	644
	645	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">value</span> (form-field)
	646	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"The lispish translated value that represents the form-field."</span>))
	647
	648	(<span class="emacs-face-keyword">defgeneric</span> (<span class="emacs-face-function-name">setf value)</span> (new-value form-field)
	649	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Set the value of a form-field with translation to client."</span>))
	650
	651	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">generic-html-input</span> (form-field html-element)
	652	((client-value <span class="emacs-face-builtin">:accessor</span> client-value <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:client-value</span>
	653	<span class="emacs-face-builtin">:initform</span> <span class="emacs-face-string">""</span>
	654	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"The string the client submitted along with this field."</span>)
	655	(name <span class="emacs-face-builtin">:accessor</span> name <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:name</span> <span class="emacs-face-builtin">:initform</span> nil)
	656	(accesskey <span class="emacs-face-builtin">:accessor</span> accesskey <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:accesskey</span> <span class="emacs-face-builtin">:initform</span> nil)
	657	(tooltip <span class="emacs-face-builtin">:accessor</span> tooltip <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:tooltip</span> <span class="emacs-face-builtin">:initform</span> nil)
	658	(tabindex <span class="emacs-face-builtin">:accessor</span> tabindex <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:tabindex</span> <span class="emacs-face-builtin">:initform</span> nil))
	659	(<span class="emacs-face-builtin">:default-initargs</span> <span class="emacs-face-builtin">:dom-id</span> (js:gen-js-name-string <span class="emacs-face-builtin">:prefix</span> <span class="emacs-face-string">"_ucw_"</span>)))
	660	</pre>
	661
	662	<p>Fields are rendered into the extended <code><ucw:input</code> yaclml tag which
	663	supports a few fancy features. The <code>:accessor</code> for all form elements is
	664	set to <code>(client-value FIELD)</code>, and you should use <code>value</code> to access the
	665	Lisp value associated with it.</p>
	666
	667	<pre class="src">
	668	(deftag-macro <ucw:input (<span class="emacs-face-type">&attribute</span> accessor action reader writer name id (default nil)
	669	<span class="emacs-face-type">&allow-other-attributes</span> others)
	670	<span class="emacs-face-string">"Generic INPUT tag replacement.
	671
	672	If the ACCESSOR attribute is specified then it must be a PLACE
	673	and it's value will be used to fill the input, when the form is
	674	submitted it will be set to the new value.
	675
	676	If ACTION is specefied then when the form is submitted via this
	677	input type=\"submit\" tag the form will be eval'd. when the
	678	submit (or image) is clicked. DEFAULT means that the ACTION
	679	provided for this input tag will be the default action of the
	680	form when pressing enter in a form field. If more then one, then
	681	the latest wins."</span>)
	682	</pre>
	683
	684	<p>Validation of form fields are supported by adding to the validators
	685	list.</p>
	686
	687	<pre class="src">
	688	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">validator</span> ()
	689	((message <span class="emacs-face-builtin">:accessor</span> message <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:message</span> <span class="emacs-face-builtin">:initform</span> nil)))
	690
	691	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">validate</span> (field validator)
	692	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Validate a form-field with a validator."</span>))
	693
	694	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">javascript-check</span> (field validator)
	695	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Generate javascript code for checking FIELD against VALIDATOR.
	696
	697	This is the convenience entry point to generate-javascript-check,
	698	methods defined on this generic funcition should return a list of
	699	javascript code (as per parenscript) which tests against the
	700	javascript variable value."</span>))
	701
	702	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">javascript-invalid-handler</span> (field validator)
	703	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"The javascript code body for when a field is invalid."</span>))
	704
	705	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">javascript-valid-handler</span> (field validator)
	706	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Generate the javascript body for when a field is valid."</span>))
	707	</pre>
	708
	709	<h5>Standard Form Fields</h5>
	710
	711	<pre class="src">
	712	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">string-field</span> (generic-html-input)
	713	((input-size) (maxlength)))
	714
	715	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">password-field</span> (string-field))
	716	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">number-field</span> (string-field))
	717	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">integer-field</span> (number-field))
	718
	719	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">in-field-string-field</span> (string-field)
	720	((in-field-label <span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"This slot, if non-NIL, will be
	721	used as an initial field label. An initial
	722	field label is a block of text which is placed
	723	inside the input element and removed as soon
	724	as the user edits the field. Obviously this
	725	field is overidden by an initial :client-value
	726	argument."</span>)))
	727
	728	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">textarea-field</span> (generic-html-input)
	729	((rows) (cols)))
	730
	731	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">date-field</span> (form-field widget-component)
	732	((year) (month) (day)))
	733
	734	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">dmy-date-field</span> (date-field)
	735	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Date fields which orders the inputs day/month/year"</span>))
	736	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">mdy-date-field</span> (date-field))
	737
	738	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">select-field</span> (generic-html-input)
	739	((data-set <span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"The values this select chooses
	740	from."</span>))
	741	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Form field used for selecting one value from a
	742	list of available options."</span>))
	743
	744	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">render-value</span> (select-field value)
	745	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"This function will be passed each value in the field's
	746	data-set and must produce the body of the corresponding
	747	<ucw:option tag."</span>))
	748
	749	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">mapping-select-field</span> (select-field)
	750	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Class used when we want to chose the values of
	751	a certain mapping based on the keys. We render the keys in the
	752	select and return the corresponding value from the VALUE
	753	method."</span>))
	754
	755	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">hash-table-select-field</span> (mapping-select-field))
	756	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">alist-select-field</span> (mapping-select-field))
	757	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">plist-select-field</span> (mapping-select-field))
	758
	759	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">radio-group</span> (generic-html-input)
	760	((value-widgets)))
	761
	762	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">radio-button</span> (generic-html-input)
	763	((value)
	764	(group <span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"The RADIO-GROUP this button is a part
	765	of."</span>))
	766	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A widget representing a single radio
	767	button. Should be used in conjunction with a RADIO-GROUP."</span>))
	768
	769	(<span class="emacs-face-keyword">defmethod</span> <span class="emacs-face-function-name">add-value</span> ((group radio-group) value)
	770	<span class="emacs-face-string">"Adds radio-button with value to group"</span>)
	771
	772	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">checkbox-field</span> (generic-html-input))
	773	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">file-upload-field</span> (generic-html-input))
	774	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">submit-button</span> (generic-html-input)
	775	((label)))
	776	</pre>
	777
	778	<h5>File Upload Field</h5>
	779
	780	<p>Calling <code>value</code> on a <code>file-upload-field</code> returns a mime encoded body
	781	part. <code>(mime-part-body (value FIELD))</code> will return a <strong>binary stream</strong>
	782	attached to the contents of the file. The <code>Content-Type</code> header should
	783	be set to the MIME type of the file being uploaded.</p>
	784
	785	<pre class="src">
	786	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">mime-part-headers</span> (mime-part)
	787	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Returns an alist of the headers of MIME-PART.
	788
	789	The alist must be of the form (NAME . VALUE) where both NAME and
	790	VALUE are strings."</span>))
	791
	792	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">mime-part-body</span> (mime-part)
	793	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Returns the body of MIME-PART."</span>))
	794	</pre>
	795
	796
	797
	798	<h5>Standard Validators</h5>
	799
	800	<pre class="src">
	801	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">not-empty-validator</span> (validator))
	802
	803	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">value-validator</span> (validator)
	804	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Validators that should only be applied if there is a value.
	805	That is, they always succeed on nil."</span>))
	806
	807	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">length-validator</span> (value-validator)
	808	((min-length <span class="emacs-face-builtin">:accessor</span> min-length <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:min-length</span>
	809	<span class="emacs-face-builtin">:initform</span> nil)
	810	(max-length <span class="emacs-face-builtin">:accessor</span> max-length <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:max-length</span>
	811	<span class="emacs-face-builtin">:initform</span> nil)))
	812
	813	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">string=-validator</span> (validator)
	814	((other-field <span class="emacs-face-builtin">:accessor</span> other-field <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:other-field</span>))
	815	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Ensures that a field is string= to another one."</span>))
	816
	817	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">regex-validator</span> (value-validator)
	818	((regex <span class="emacs-face-builtin">:accessor</span> regex <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:regex</span> <span class="emacs-face-builtin">:initform</span> nil)))
	819
	820	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">e-mail-address-validator</span> (regex-validator))
	821
	822	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">phone-number-validator</span> (regex-validator))
	823
	824	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">is-a-number-validator</span> (value-validator))
	825	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">is-an-integer-validator</span> (is-a-number-validator))
	826
	827	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">number-range-validator</span> (is-a-number-validator)
	828	((min-value <span class="emacs-face-builtin">:accessor</span> min-value <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:min-value</span> <span class="emacs-face-builtin">:initform</span> nil)
	829	(max-value <span class="emacs-face-builtin">:accessor</span> max-value <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:max-value</span> <span class="emacs-face-builtin">:initform</span> nil)))
	830	</pre>
	831
	832
	833	<h5>Simple Form Helper</h5>
	834
	835	<p>UCW provides a helper class for developing forms. Subclass and add the
	836	elements you wish to include in the form. A <code>:wrapping</code> method renders
	837	the form boilerplate and then calls your <code>render</code>.</p>
	838
	839	<pre class="src">
	840	(defcomponent simple-form (html-element)
	841	((submit-method <span class="emacs-face-builtin">:accessor</span> submit-method
	842	<span class="emacs-face-builtin">:initform</span> <span class="emacs-face-string">"post"</span>
	843	<span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:submit-method</span>)
	844	(dom-id <span class="emacs-face-builtin">:accessor</span> dom-id
	845	<span class="emacs-face-builtin">:initform</span> (js:gen-js-name-string <span class="emacs-face-builtin">:prefix</span> <span class="emacs-face-string">"_ucw_simple_form_"</span>)
	846	<span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:dom-id</span>))
	847	(<span class="emacs-face-builtin">:default-initargs</span> <span class="emacs-face-builtin">:dom-id</span> <span class="emacs-face-string">"ucw-simple-form"</span>))
	848	</pre>
	849
	850
	851
	852	<h4><a name="sec12" id="sec12"></a>
	853	Templates</h4>
	854
	855	<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>
	856
	857	<p>Infrastructure for loading TAL templates as a view of a component.</p>
	858
	859	<pre class="src">
	860	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">template-component</span> (component))
	861	(defcomponent simple-template-component (template-component)
	862	((environment <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:environment</span> <span class="emacs-face-builtin">:initform</span> nil)))
	863
	864	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">template-component-environment</span> (component)
	865	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Create the TAL environment for rendering COMPONENT's template.
	866
	867	Methods defined on this generic function must return a TAL
	868	environment: a list of TAL binding sets (see the documentation
	869	for YACLML:MAKE-STANDARD-ENVIRONMENT for details on TAL
	870	environments.)"</span>)
	871	(<span class="emacs-face-builtin">:method-combination</span> nconc))
	872
	873	(<span class="emacs-face-keyword">defmethod</span> <span class="emacs-face-function-name">template-component-environment</span> nconc ((component template-component))
	874	<span class="emacs-face-string">"Create the basic TAL environment.
	875
	876	Binds the symbol ucw:component to the component object itself,
	877	also puts the object COMPONENT on the environment (after the
	878	binding of ucw:component) so that slots are, by default,
	879	visable."</span>
	880	(make-standard-environment `((component . ,component)) component))
	881
	882	(<span class="emacs-face-keyword">defmethod</span> <span class="emacs-face-function-name">render</span> ((component template-component))
	883	<span class="emacs-face-string">"Render a template based component.
	884
	885	Calls the component's template. The name of the template is the
	886	value returned by the generic function
	887	template-component.template-name, the template will be rendered
	888	in the environment returned by the generic function
	889	template-component-environment."</span>
	890	(render-template context
	891	(template-component.template-name component)
	892	(template-component-environment component)))
	893
	894	</pre>
	895
	896	<p>Subclass and override methods. <code>simple-template-component</code> only provides
	897	the ability to set environment variables in initarg. Subclass to
	898	provide automagic template file name generation and such.</p>
	899
	900
	901	<h4><a name="sec13" id="sec13"></a>
	902	Utility Mixin Components</h4>
	903
	904	<h5>Range View</h5>
	905
	906	<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>
	907
	908	<pre class="src">
	909	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">range-view</span> (template-component)
	910	(<span class="emacs-face-builtin">:default-initargs</span> <span class="emacs-face-builtin">:template-name</span> <span class="emacs-face-string">"ucw/range-view.tal"</span>)
	911	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Component for showing the user a set of data one \"window\" at a time.
	912
	913	The data set is presented one \"window\" at a time with links to
	914	the the first, previous, next and last window. Each window shows
	915	at most WINDOW-SIZE elements of the data. The data is passed to
	916	the range-view at instance creation time via the :DATA initarg.
	917
	918	The generic function RENDER-RANGE-VIEW-ITEM is used to render
	919	each item of DATA.
	920
	921	In order to change the rendering of the single elements of a
	922	range view developer's should create a sub class of RANGE-VIEW
	923	and define their RENDER-RANGE-VIEW-ITEM methods on that."</span>)
	924	(<span class="emacs-face-builtin">:metaclass</span> standard-component-class))
	925	</pre>
	926
	927	<pre class="src">
	928	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">render-range-view-item</span> (range-view item)
	929	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Render a single element of a range-view."</span>)
	930	(<span class="emacs-face-builtin">:method</span> ((range-view range-view) (item t))
	931	<span class="emacs-face-string">"Standard implementation of RENDER-RANGE-VIEW-ITEM. Simply
	932	applies ITEM to princ (via <:as-html)."</span>
	933	(<span class="emacs-face-keyword">declare</span> (ignore range-view))
	934	(<:as-html item)))
	935	</pre>
	936
	937
	938	<h5>Widget</h5>
	939
	940	<p>Mixin with existing component to wrap in a div or span. This is handy
	941	for defining lightweight widgets embedded within other components.</p>
	942
	943	<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>
	944
	945	<pre class="src">
	946	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">html-element</span> (component)
	947	((css-class)
	948	(dom-id)
	949	(css-style)
	950	(extra-tags)
	951	(events))
	952	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"An HTML element.
	953
	954	HTML elements control aspects that are relevant to almost all tags.
	955
	956	Firstly they provide a place to store the class, id, and style of the
	957	component. The specific render methods of the components themselves
	958	must pass these values to whatever code is used to render the actual
	959	tag.
	960
	961	Secondly, they allow javascript event handlers to be registered for a
	962	tag. The events slot can be filled with a list of lists in the form
	963
	964	(event parenscript-statement*)
	965
	966	For example (\"onclick\" (alert \"You clicked!\") (return nil)). If
	967	the element has a dom-id, these event handlers are automatically
	968	added."</span>))
	969	</pre>
	970
	971	<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>
	972
	973	<pre class="src">
	974	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">widget-component</span> (html-element)
	975	()
	976	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A widget which should be wrapped in a <div>."</span>))
	977
	978	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">inline-widget-component</span> (html-element)
	979	()
	980	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A widget which should be wrapped in <span> and not <div>"</span>))
	981
	982	(<span class="emacs-face-keyword">defmethod</span> <span class="emacs-face-function-name">render</span> <span class="emacs-face-builtin">:wrap-around</span> ((widget widget-component)))
	983	(<span class="emacs-face-keyword">defmethod</span> <span class="emacs-face-function-name">render</span> <span class="emacs-face-builtin">:wrap-around</span> ((widget inline-widget-component)))
	984	</pre>
	985
	986
	987	<h5>Transactions</h5>
	988
	989	<p>A mixin to provide transactions. <code>(open-transaction component)</code> and
	990	<code>(close-transaction component)</code> open and closed nested
	991	transactions. After a transaction has been closed an attempt to
	992	backtrack into a step inside the transaction will result in jumping up
	993	one level of transactions (or out of the transaction entirely if at
	994	the top level). This ensures that the transaction is only run once,
	995	naturally.</p>
	996
	997	<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>
	998
	999	<pre class="src">
	1000	(defcomponent transaction-mixin ()
	1001	(...))
	1002
	1003	(defmethod/cc open-transaction ((comp transaction-mixin)))
	1004	(defmethod/cc close-transaction ((comp transaction-mixin)))
	1005	</pre>
	1006
	1007
	1008	<h5>Task</h5>
	1009
	1010	<p><code>(defaction start ...)</code> on subclass to run a series of actions bundled
	1011	into a task.</p>
	1012
	1013	<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>
	1014
	1015	<pre class="src">
	1016	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">task-component</span> (standard-component)
	1017	(...)
	1018	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A controller for a single task or operation to
	1019	be performed by the user.
	1020
	1021	A task component's START action is called as soon as the
	1022	component is instantiated. Task components do not have their own
	1023	RENDER method, in fact they have no graphical representation but
	1024	serve only to order a sequence of other components."</span>))
	1025
	1026	(defgeneric/cc start (task)
	1027	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"action which gets called automatically when
	1028	task-component is active. Use defaction to define your own
	1029	\"start\" action"</span>))
	1030	</pre>
	1031
	1032
	1033	<h5>Cached</h5>
	1034
	1035	<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>
	1036
	1037	<pre class="src">
	1038	(defcomponent cached-component ()
	1039	((cached-output <span class="emacs-face-builtin">:accessor</span> cached-output <span class="emacs-face-builtin">:initform</span> nil
	1040	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"A string holding the output to
	1041	use for this component. This string will be
	1042	written directly to the html stream and is
	1043	changed by the REFRESH-COMPONENT-OUTPUT
	1044	method."</span> )
	1045	(timeout <span class="emacs-face-builtin">:accessor</span> timeout <span class="emacs-face-builtin">:initarg</span> <span class="emacs-face-builtin">:timeout</span>
	1046	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"An value specifying how often this
	1047	component needs to be refreshed. The exact
	1048	interpretation of the value depends on the type of
	1049	caching used class."</span>))
	1050	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Component which caches its output.
	1051
	1052	The component caching API is built around the generic functions
	1053	COMPONENT-DIRTY-P and REFRESH-COMPONENT-OUTPUT and a method on
	1054	RENDER, see the respective docstrings for more details.
	1055
	1056	Do not use CACHED-COMPONENT directly, use one its subclasses."</span>))
	1057
	1058	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">component-dirty-p</span> (component)
	1059	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Returns T is COMPONENT's cache is invalid."</span>))
	1060
	1061	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">update-cache</span> (component)
	1062	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Update COMPONENT's cache variables after a refresh."</span>))
	1063
	1064	(defcomponent timeout-cache-component (cached-component)
	1065	((last-refresh <span class="emacs-face-builtin">:accessor</span> last-refresh <span class="emacs-face-builtin">:initform</span> nil
	1066	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"The time, exrpessed as a
	1067	universal time, when the component was last rendered."</span>))
	1068	(<span class="emacs-face-builtin">:default-initargs</span>
	1069	<span class="emacs-face-builtin">:timeout</span> (* 30 60 60))
	1070	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Render the component at most every TIMEOUT seconds."</span>))
	1071
	1072	(defcomponent num-hits-cache-component (cached-component)
	1073	((hits-since-refresh <span class="emacs-face-builtin">:accessor</span> hits-since-refresh
	1074	<span class="emacs-face-builtin">:initform</span> nil
	1075	<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Number of views since last refresh."</span>))
	1076	(<span class="emacs-face-builtin">:default-initargs</span> <span class="emacs-face-builtin">:timeout</span> 10)
	1077	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Render the component every TIMEOUT views."</span>))
	1078	</pre>
	1079
	1080	<p>Subclass and override <code>component-dirty-p</code> to do something useful
	1081	(e.g. flip mark bit when object being presented changes).</p>
	1082
	1083
	1084
	1085
	1086	<h3><a name="sec14" id="sec14"></a>
	1087	Control Flow</h3>
	1088
	1089	<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>
	1090
	1091	<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>
	1092
	1093	<h4><a name="sec15" id="sec15"></a>
	1094	Calling</h4>
	1095
	1096	<p class="first">Most of what you do in UCW will be calling components so this is a bit
	1097	important. Note that calling interrupts the current control flow so if
	1098	you want to render a component in place as part of another component
	1099	just call <code>render</code> on it instead.</p>
	1100
	1101	<pre class="src">
	1102	(<span class="emacs-face-keyword">defmacro</span> <span class="emacs-face-function-name">call</span> (component-type <span class="emacs-face-type">&rest</span> component-init-args)
	1103	<span class="emacs-face-doc">"Stop the execution of the current action and pass control to
	1104	a freshly created component of type COMPONENT-TYPE.
	1105
	1106	COMPONENT-INIT-ARGS are passed directly to the underlying
	1107	make-instance call. This form will return if and when the call'd
	1108	component calls answer, the value returned by this form is
	1109	whatever the call'd component passed to answer.
	1110
	1111	Notes:
	1112
	1113	This macro assumes that the lexcial variable UCW:SELF is bound to
	1114	the calling component."</span>)
	1115
	1116	(answer VAL) <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">answer parent component ONLY IN ACTIONS
	1117	</span>
	1118	(ok SELF VAL) <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">Used to answer a component anywhere and what answer
	1119	</span> <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">expands into
	1120	</span>
	1121	(jump COMPONENT-NAME <span class="emacs-face-type">&REST</span> ARGS) <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">is similar to call, but replaces
	1122	</span> <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">the current component with the new
	1123	</span> <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">one and drops any backtracks (back
	1124	</span> <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">button will no longer work)
	1125	</span></pre>
	1126
	1127	<p><code>(call COMPONENT-NAME &ARGS INIT-ARGS)</code> calls <code>COMPONENT-NAME</code> and returns
	1128	the value returned by <code>(ok SELF RETURN-VALUE)</code> called from within
	1129	<code>COMPONENT-NAME</code></p>
	1130
	1131
	1132	<h4><a name="sec16" id="sec16"></a>
	1133	Actions</h4>
	1134
	1135	<p class="first">Actions are methods on components. The first argument <strong>must</strong> be a
	1136	component for most of UCW to work.</p>
	1137
	1138	<pre class="src">
	1139	(defaction NAME (first ...) ...)
	1140	<span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">(roughly) expands into
	1141	</span>(defmethod/cc NAME (first ...)
	1142	(<span class="emacs-face-keyword">let</span> ((self first))
	1143	...))
	1144	</pre>
	1145
	1146	<p><code>Self</code> being bound in the current lexical environment is required for
	1147	most UCW control flow things to work. <code>defaction</code> hides this from you,
	1148	and was a big source of confusion for me early on (mostly "hmm, why is
	1149	this not working ... where did that come from in the
	1150	macroexpansion!").</p>
	1151
	1152
	1153	<h4><a name="sec17" id="sec17"></a>
	1154	Entry Points</h4>
	1155
	1156	<pre class="src">
	1157	(defentry-point url (<span class="emacs-face-builtin">:application</span> APPLICATION
	1158	<span class="emacs-face-builtin">:class</span> DISPATCHER-CLASS)
	1159	(PARAM1 ... PARAMN) <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">GET / POST vars, bound in body
	1160	</span> body)
	1161	</pre>
	1162
	1163	<p>An entry point is what it sounds like: a static URL matched using the
	1164	mater of <code>DISPATCHER-CLASS</code> that enters into <code>APPLICATION</code> running the
	1165	code in <code>body</code>. An example from a test program I have written
	1166	follows. The entry point allows files to be streamed to user when the
	1167	url audio.ucw?file=FOO is used.</p>
	1168
	1169	<pre class="src">
	1170	(defentry-point <span class="emacs-face-string">"^(audio.ucw\|)$"</span> (<span class="emacs-face-builtin">:application</span> golf-test-app
	1171	<span class="emacs-face-builtin">:class</span> regexp-dispatcher)
	1172	(file)
	1173	(call 'audio-file-window
	1174	<span class="emacs-face-builtin">:audio-file</span> (make-instance 'audio-file
	1175	<span class="emacs-face-builtin">:type</span> <span class="emacs-face-builtin">:vorbis</span>
	1176	<span class="emacs-face-builtin">:data</span> (file->bytes (open
	1177	file
	1178	<span class="emacs-face-builtin">:element-type</span> 'unsigned-byte)))))
	1179	</pre>
	1180
	1181
	1182
	1183	<h3><a name="sec18" id="sec18"></a>
	1184	Dispatching</h3>
	1185
	1186	<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>
	1187
	1188	<pre class="src">
	1189	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">matcher-match</span> (matcher application context)
	1190	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Abstract method for subclasses to implement a
	1191	matcher. This method would return multiple-values according to
	1192	matcher internal nature.
	1193
	1194	No methods defined on this function may rebind context, nor
	1195	change CONTEXT's application. Only if the method matches the
	1196	request, it is allowed to modify CONTEXT or APPLICATION, even in
	1197	that case methods defined on this function must not modify
	1198	CONTEXT's application nor rebind context."</span>))
	1199
	1200	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">handler-handle</span> (handler application context matcher-result)
	1201	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Abstract function for handler classes to
	1202	implement in order to handle a request matched by relevant
	1203	matcher.
	1204
	1205	These methods may modify context as they wish since they'r
	1206	matched, request will be closed after this method is run."</span>))
	1207
	1208	(<span class="emacs-face-keyword">defgeneric</span> <span class="emacs-face-function-name">dispatch</span> (dispatcher application context)
	1209	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"Entry point into a dispatcher. Must return T
	1210	if the context has been handled or NIL if it hasn't.
	1211
	1212	No methods defined on this function may rebind context, nor
	1213	change CONTEXT's application. Only if the method returns T is it
	1214	allowed to modify CONTEXT or APPLICATION, even in that case
	1215	methods defined on this function must not modify CONTEXT's
	1216	application nor rebind context."</span>))
	1217	</pre>
	1218
	1219	<pre class="src">
	1220	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">my-matcher</span> (abstract-matcher) ...)
	1221	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">my-handler</span> (abstract-handler) ...)
	1222	(<span class="emacs-face-keyword">defclass</span> <span class="emacs-face-type">my-dispatcher</span> (abstract-dispatcher my-matcher my-handler)
	1223	...)
	1224	</pre>
	1225
	1226	<h4><a name="sec19" id="sec19"></a>
	1227	Simple Dispatcher</h4>
	1228
	1229	<pre class="src">
	1230	(<span class="emacs-face-builtin">:documentation</span> <span class="emacs-face-string">"This class of dispatchers avoids all of UCW's
	1231	standard call/cc (and therefore frame/backtracking/component)
	1232	mechanism.
	1233
	1234	Unlike all other UCW dispatchers a simple-dispatcher must not use
	1235	CALL, and must perform the rendering directly within the handler."</span>)
	1236	</pre>
	1237
	1238
	1239
	1240	<h3><a name="sec20" id="sec20"></a>
	1241	Server</h3>
	1242
	1243	<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>
	1244
	1245	<pre class="src">
	1246	(<span class="emacs-face-keyword">defun</span> <span class="emacs-face-function-name">create-server</span> (<span class="emacs-face-type">&key</span>
	1247	(backend `(,ucw-backend-type <span class="emacs-face-builtin">:host</span> ,ucw-backend-host
	1248	<span class="emacs-face-builtin">:port</span> ,ucw-backend-port))
	1249	(applications ucw-applications)
	1250	(start-p t)
	1251	(server-class ucw-server-class)
	1252	(log-root-directory (truename ucw-log-root-directory))
	1253	(log-level ucw-log-level))
	1254	<span class="emacs-face-doc">"Creates and returns a UCW server according to SERVER-CLASS, HOST and
	1255	PORT. Affects DEFAULT-SERVER.
	1256
	1257	BACKEND is a list of (BACKEND-TYPE &rest INITARGS). BACKEND-TYPE
	1258	may be :HTTPD, :MOD-LISP, :ASERVE, :ARANEIDA, an existing
	1259	backend, an existing UCW server backend or :DEFAULT in which case
	1260	it attempts to return a sane default from the UCW backends loaded
	1261	and available, or any other value for which a valid MAKE-BACKEND
	1262	method has been defined. INITARGS will be passed, unmodified, to
	1263	MAKE-BACKEND.
	1264
	1265	APPLICATIONS is a list of defined applications to be loaded into the
	1266	server.
	1267
	1268	Logs are generated in verbosity defined by LOG-LEVEL and directed to
	1269	LOG-ROOT-DIRECTORY if defined."</span>
	1270	...
	1271	server) <span class="emacs-face-comment-delimiter">; </span><span class="emacs-face-comment">return server, naturally
	1272	</span></pre>
	1273
	1274
	1275	<h3><a name="sec21" id="sec21"></a>
	1276	Debugging</h3>
	1277
	1278	<h4><a name="sec22" id="sec22"></a>
	1279	Inspector</h4>
	1280
	1281	<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>
	1282
	1283	<pre class="src">
	1284	(defaction call-inspector ((component component) datum)
	1285	<span class="emacs-face-string">"Call an inspector for DATUM on the component COMPONENT."</span>
	1286	(call 'ucw-inspector <span class="emacs-face-builtin">:datum</span> datum))
	1287	</pre>
	1288
	1289
	1290
	1291
	1292	<h2><a name="sec23" id="sec23"></a>
	1293	Tips</h2>
	1294
	1295	<h3><a name="sec24" id="sec24"></a>
	1296	Getting dojo to load</h3>
	1297
	1298	<p class="first">I had some trouble getting dojo to work properly with UCW. The way
	1299	that the <code>:www-roots</code> option for an application works is a bit
	1300	confusing, and it is unforgiving if you mess the pathname up. A
	1301	directory <strong>must</strong> have a <code>/</code> at the end, and the directory you are serving
	1302	must also have the <code>/</code> (which is counterintuitive given the behavior of
	1303	most unix things that don't want the <code>/</code> at the end of the name).</p>
	1304
	1305	<pre class="src">
	1306	<span class="emacs-face-builtin">:www-roots</span> (list '(<span class="emacs-face-string">"dojo/"</span> .
	1307	#P<span class="emacs-face-string">"/home/clinton/src/ucw/darcs/ucw_dev/wwwroot/dojo/"</span>))
	1308	</pre>
	1309
	1310
	1311	<h3><a name="sec25" id="sec25"></a>
	1312	Specials Bound During Rendering</h3>
	1313
	1314	<p class="first">The current request context is bound to <code>ucw:context</code>, and the current
	1315	component is bound to <code>ucw:current-component</code> in the dynamic extent of
	1316	<code>render</code>.</p>
	1317
	1318
	1319	<h3><a name="sec26" id="sec26"></a>
	1320	Printing to the yaclml stream</h3>
	1321
	1322	<p class="first">Occasionally it can be useful to do something like write a byte array
	1323	as an ascii string to the client. Inside of <code>render</code> the variable
	1324	<code>yaclml:yaclml-stream</code> is bound to the stream that you can write to if
	1325	you wish to have content interspersed with yaclml tags.</p>
	1326
	1327
	1328
	1329	<!-- Page published by Emacs Muse ends here -->
	1330
	1331	<p class="cke-buttons">
	1332	<!-- validating badges, any browser, etc -->
	1333	<a href="http://validator.w3.org/check/referer"><img
	1334	src="http://www.w3.org/Icons/valid-xhtml10"
	1335	alt="Valid XHTML 1.0!" /></a>
	1336
	1337	<a href="http://www.anybrowser.org/campaign/"><img
	1338	src="img/buttons/w3c_ab.png" alt="[ Viewable With Any Browser
	1339	]" /></a>
	1340
	1341	<a href="http://www.debian.org/"><img
	1342	src="img/buttons/debian.png" alt="[ Powered by Debian ]" /></a>
	1343
	1344	<a href="http://hcoop.net/">
	1345	<img src="img/buttons/hcoop.png"
	1346	alt="[ Hosted by HCoop]" />
	1347	</a>
	1348
	1349	<a href="http://www.fsf.org/register_form?referrer=114">
	1350	<img src="img/buttons/fsf_member.png"
	1351	alt="[ FSF Associate Member ]" />
	1352	</a>
	1353	</p>
	1354
	1355	<p class="cke-footer">And did those feet in ancient times
	1356	Walk bare upon these lonely streets like mine?
	1357	Does God watch us from that penthouse high above
	1358	His children down below who live on air and love?
	1359	</p>
	1360	<p class="cke-timestamp">Last Modified:
	1361	March 13, 2008</p>
	1362	</body>
	1363	</html>