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">
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" />
11 content=
"width=device-width, initial-scale=1.0" />
12 <link href=
"https://feeds.unknownlamer.org/rss/site-updates"
13 rel=
"alternate" type=
"application/rss+xml" title=
"Updates Feed" />
15 <link rel=
"stylesheet" href=
"default.css" />
18 <h1>Roadmap to UCW Codebase
</h1>
19 <div class=
"contents">
22 <a href=
"#sec1">Abstract
</a>
25 <a href=
"#sec2">Roadmap
</a>
30 <a href=
"#sec3">Applications
</a>
35 <a href=
"#sec4">Cookie
</a>
38 <a href=
"#sec5">L10n
</a>
41 <a href=
"#sec6">Secure
</a>
46 <a href=
"#sec7">Components
</a>
51 <a href=
"#sec8">Windows
</a>
54 <a href=
"#sec9">Containers
</a>
57 <a href=
"#sec10">Dialogs
</a>
60 <a href=
"#sec11">Forms
</a>
63 <a href=
"#sec12">Templates
</a>
66 <a href=
"#sec13">Utility Mixin Components
</a>
71 <a href=
"#sec14">Control Flow
</a>
76 <a href=
"#sec15">Calling
</a>
79 <a href=
"#sec16">Actions
</a>
82 <a href=
"#sec17">Entry Points
</a>
87 <a href=
"#sec18">Dispatching
</a>
92 <a href=
"#sec19">Simple Dispatcher
</a>
97 <a href=
"#sec20">Server
</a>
100 <a href=
"#sec21">Debugging
</a>
105 <a href=
"#sec22">Inspector
</a>
112 <a href=
"#sec23">Tips
</a>
117 <a href=
"#sec24">Getting dojo to load
</a>
120 <a href=
"#sec25">Specials Bound During Rendering
</a>
123 <a href=
"#sec26">Printing to the yaclml stream
</a>
131 <!-- Page published by Emacs Muse begins here -->
132 <h2><a name=
"sec1" id=
"sec1"></a>
135 <p><a href=
"http://common-lisp.net/project/ucw/">UnCommon Web
</a> is a very powerful and mature web framework for Common
136 Lisp, but is a bit difficult to learn. It is documented
137 extensively
—in the form of docstrings. These are extremely helpful
138 once you've figured out the rough structure of UCW, but they are of no
139 help when first learning unless you just read most of the source. I
140 ended up having to do that, and after some urging along by folks in
141 <code>#ucw
</code> I decided to clean up my planner notes and publish them for
142 public consumption.
</p>
144 <p>The roadmap is presented with major sections ordered in a logical
145 order for learning the framework. The sections are ordered internally
146 in order of most immediately useful to least, but it may be worth
147 hopping between major sections before reading all of the details. I
148 have used abridged class definitions and docstrings with occasional
149 commentary to clarify things.
</p>
152 <h2><a name=
"sec2" id=
"sec2"></a>
155 <h3><a name=
"sec3" id=
"sec3"></a>
158 <p class=
"first">Applications are a bundle of entry points. The base class is,
159 naturally,
<code>standard-application
</code>, but you should instead derive your
160 application class from
<code>modular-application
</code> and any standard or custom
161 application mixins you find useful.
</p>
163 <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>
166 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">standard-application
</span> (application)
167 ((url-prefix
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:url-prefix
</span>
168 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A string specifying the
169 start (prefix) of all the urls this app should handle.
171 This value is used by the standard-server to decide what app a
172 particular request is aimed at and for generating links to
173 actions within the app. "</span>)
174 (www-roots
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:www-roots
</span>
175 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A list of directories (pathname
176 specifiers) or cons-cell (URL-subdir . pathname) to use when looking for static files."</span>)
177 (dispatchers
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:dispatchers
</span>
178 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A list of request
179 dispatchers. The user supplied list of dispatchers is extended
180 with other dispatchers that are required for UCW to function
181 properly (action-dispatcher, a parenscript-dispatcher, etc). If
182 you want full control over the active dispatchers use the (setf
183 application.dispatchers) accessor or, if you want control over
184 the order of the dispathcers, (slot-value instance
185 'dispatchers)."</span>))
186 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"The default UCW application class."</span>))
189 <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>
192 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">modular-application-mixin
</span> ()
194 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Superclass for all application mixins."</span>))
196 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">modular-application
</span> (standard-application modular-application-mixin)
200 <h4><a name=
"sec4" id=
"sec4"></a>
203 <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>
206 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">cookie-session-application-module
</span> (modular-application-mixin)
207 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Class for applications which use cookies for sesion tracking.
209 Cookie session applications work exactly like
210 standard-applications except that when the session is not found
211 using the standard mechanisms the id is looked for in a cookie."</span>))
214 <p>This is the most useful of the application components. It makes your
215 application urls readable by stashing the session id into a cookie
216 rather than as a set of long and ugly GET parameters.
</p>
219 <h4><a name=
"sec5" id=
"sec5"></a>
222 <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>
225 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">l10n-application-module
</span> (modular-application-mixin)
226 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Application class which can handle l10n requests."</span>))
230 <h4><a name=
"sec6" id=
"sec6"></a>
233 <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>
236 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">secure-application-module
</span> (modular-application-mixin)
237 (
<span class=
"emacs-face-builtin">:documentation
</span>
238 <span class=
"emacs-face-doc">"Mixin class for applications which require authorized access.
239 Concrete application must specialize the following methods:
240 APPLICATION-FIND-USER (APPLICATION USERNAME)
241 APPLICATION-CHECK-PASSWORD (APPLICATION USER PASSWORD)
242 APPLICATION-AUTHORIZE-CALLZE-CALL (APPLICATION USER FROM-COMPONENT TO-COMPONENT)."</span>))
247 <h3><a name=
"sec7" id=
"sec7"></a>
250 <p class=
"first">A component is a special class that handles the complexities of
251 continuation suspension and such for you. New components are derived
252 from the existing ones by using
<code>defcomponent
</code> instead of
<code>defclass
</code>. This
253 adds a few extra slot and class options, and ensures that the proper
254 metaclass is set.
</p>
256 <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>
259 (
<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)
260 <span class=
"emacs-face-doc">"Macro for defining a component class.
262 This macro is used to create component classes and provides
263 options for easily creating the methods which often accompany a
264 component definition.
266 NAME, SUPERS and SLOTS as treated as per defclass. The following
267 extra options are allowed:
269 (:ENTRY-POINT url (&key application class)) - Define an
270 entry-point on the url URL which simply calls an instance of
271 this component. Any request parameters passed to the entry-point
272 are used to initialize the slots in the component. This option
273 may appear multiple times.
275 (:DEFAULT-BACKTRACK function-designator) - Unless the slots
276 already have a :backtrack option FUNCTION-DESIGNATOR is
277 added. As with the 'regular' :backtrack options if you pass T
278 here it is assumed to mean #'IDENTITY.
280 (:RENDER (&optional COMPONENT) &body BODY) - Generate a render
281 method specialized to COMPONENT. COMPONENT may be a symbol, in
282 which case the method will be specialized on the componnet
283 class. If COMPONNET is omited the component is bound to a
284 variable with the same name as the class.
286 (:ACTION &optional NAME) - Generate a defaction form named
287 NAME (which defaults to the name of the component) which simply
288 CALL's this component class passing all the arguments passed to
289 the action as initargs."</span>)
291 <span class=
"emacs-face-comment-delimiter">;;;
</span><span class=
"emacs-face-comment">Extra Slot Options
292 </span><span class=
"emacs-face-string">"Other than the initargs for standard slots the following
293 options can be passed to component slots:
295 :backtrack [ T | NIL | FUNCTION-NAME ] - Specify that this slot
296 should be backtracked (or not if NIL is passed as the value). If
297 the value is neither T nor NIL then it must be a function which
298 will be used as the copyer.
300 :component [ TYPE | ( TYPE &rest INITARGS ) ] - Specify that this
301 slot is actually a nested component of type TYPE. When instances
302 of the class are created this slot will be set to an instance of
303 type TYPE and it's place will be set to this slot. If a list is
304 passed to :component then TYPE (which isn't evaluated) will be
305 passed as the first argument to make-instance. The INITARGS will
306 be eval'd and apply'd to make-instance. The result of this call
307 to make-instance will be used as the effective component
311 <h4><a name=
"sec8" id=
"sec8"></a>
314 <p class=
"first">A window-component represents a top level browser window, naturally.
</p>
316 <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>
319 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">window-component
</span> ()
322 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">simple-window-component
</span> (window-component)
325 (javascript
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"List of javascript includes.
327 Each element must be a list whose first value is either the
330 (:SRC url) - writes <script src=\"URL\
"></script> tag.
331 (:JS form) - equivalent to (:SCRIPT (js:js* form))
332 (:SCRIPT string) - write <script>STRING</script>.
334 The elements will be rendered in order."</span>)
338 <p><code>window-component
</code> could be useful for doing things like dumping binary
339 data to the user, or just deriving your own funky top level window
342 <p><code>simple-window-component
</code> is the easiest for displaying standard
343 webpage. It provides a wrapping method on render that displays the
344 html boilerplate based on your component slot values which is what one
345 wants most of the time. The initargs to
<code>simple-window-component
</code> have
346 the same names as the slots.
</p>
350 <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>
352 <p>There is a generic status bar interface. Messages severity is one of
353 <code>(:error :warn :info)
</code>. Note that the default status bar render method
354 just shows a div with status messages. A derivative could be defined
355 to insert messages into the browser status bar.
</p>
358 (defcomponent status-bar ()
359 ((messages
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"An ALIST of the messages to
360 show. Each element is a cons of the form (SEVERITY .
361 MESSAGE). SEVERITY is one of :ERROR, :WARN, :INFO and MESSAGE is
362 a string which will be html-escaped."</span>)
364 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Stateless status bar to display messages."</span>))
366 (
<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>)
367 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Add the message text MSG to STATUS-BAR with
368 severity SEVERITY."</span>))
372 (defcomponent status-bar-mixin ()
373 ((status-bar
<span class=
"emacs-face-builtin">:accessor
</span> status-bar
374 <span class=
"emacs-face-builtin">:initarg
</span> status-bar
375 <span class=
"emacs-face-builtin">:component
</span> (status-bar))))
377 (
<span class=
"emacs-face-keyword">defmethod
</span> <span class=
"emacs-face-function-name">show-status-bar
</span> ((win status-bar-mixin))
378 (render (status-bar win)))
380 (
<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>)
381 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Show a message in the status bar. Only works if
382 current window is a status-bar-mixin"</span>))
388 <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>
391 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">redirect-component
</span> ()
392 ((target
<span class=
"emacs-face-builtin">:accessor
</span> target
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:target
</span>))
393 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class)
394 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Send a client redirect.
396 This component, which must be used as a window-component,
397 redirects the client to the url specified in the target slot. A
398 302 (as opposed to 303) response code is sent to ensure
399 compatability with older browsers.
401 The redirect component never answers."</span>))
404 <p>There is also a
<code>meta-refresh
</code> procedure.
</p>
407 (defun/cc meta-refresh ()
408 <span class=
"emacs-face-string">"Cause a meta-refresh (a freshly got (GET) url) at this point.
409 This is useful in order to have a GET url after a form POST's
410 actions have completed running. The user can then refresh to his
411 heart's content."</span>)
416 <h4><a name=
"sec9" id=
"sec9"></a>
419 <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>
422 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">container
</span> ()
424 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class)
425 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Allow multiple components to share the same place.
427 The container component serves to manage a set of components.
428 It does not provide any render impementation, which is the
429 resposibility of the subclasses (e.g. switching-container or
432 Each contained component has a \"key\
" associated with it which
433 is used to retrieve a particular component. Keys are compared with
436 The :contents inintarg, if provided, must be either a list of (key .
437 component) or a list of components. In the latter case it will
438 be converted into (component . component) form."</span>))
444 <li><code>child-components
</code></li>
445 <li><code>find-component CONTAINER KEY
</code></li>
446 <li><code>remove-component
</code></li>
447 <li><code>(setf find-component CONTAINER KEY) COMPONENT
</code> -
>
448 <code>add-component CONTAINER COMPONENT KEY
</code></li>
452 <h5>Switching Container
</h5>
454 <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>
457 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">switching-container
</span> ...
458 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A simple renderable container component.
460 This component is like the regular CONTAINER but serves to manage a set
461 of components which share the same place in the UI. Therefore it provides
462 an implementation of RENDER which simply renders its current component.
464 The switching-container component class is generally used as the super
465 class for navigatation components and tabbed-pane like
466 components."</span>))
469 <p>Subclass and
<code>(defmethod render :around ...)
</code> to render navigation using
470 <code>(call-next-method)
</code> to render the selected component.
</p>
475 <li><code>container.current-component COMPONENT
</code></li>
476 <li><code>(setf container.current-component CONTAINER) COMPONENT
</code></li>
483 <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>
486 (defcomponent tabbed-pane (switching-container)
487 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Component for providing the user with a standard \"tabbed pane\
" GUI widget."</span>))
490 <p>Provides a generic tabbed pane that renders a nested div split into a
491 naviation and content box. The navigation box is a set of styled divs
492 containing the navigation links.
</p>
496 <h4><a name=
"sec10" id=
"sec10"></a>
499 <p class=
"first">A few convenience dialogs are provided for grabbing data from the
504 <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>
507 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">login
</span> ()
508 ((username) (password) (message))
509 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Generic login (input username and password) component.
511 This component, which must be embedded in another component,
512 presents the user with a simple two fielded login form.
514 When the user attempts a login the action try-login is called,
515 try-login calls the generic function check-credentials passing it
516 the login component. If check-credentials returns true then the
517 login-successful action is called, otherwise the message slot of
518 the login component is set (to a generic \"bad username\
"
521 The default implementaion of login-successful simply answers t,
522 no default implementation of check-credentials is
523 provided. Developers should use sub-classes of login for which
524 all the required methods have been definined."</span>)
525 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class))
529 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">check-credentials
</span> (login)
530 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Returns T if LOGIN is valid."</span>))
532 (defaction login-successful ((l login))
536 <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>
539 (defcomponent user-login (simple-window-component status-bar-mixin)
540 ((username string-field) (password password-field)))
543 <p>Used by
<code>secure-application-module
</code> to provide a user login. Relevant
544 protocol details follow.
</p>
547 (
<span class=
"emacs-face-keyword">defmethod
</span> <span class=
"emacs-face-function-name">check-credentials
</span> ((self user-login))
548 (
<span class=
"emacs-face-keyword">let*
</span> ((username (value (username self)))
549 (password (value (password self)))
550 (user (find-application-user username)))
551 (
<span class=
"emacs-face-keyword">when
</span> (and user (
<span class=
"emacs-face-warning">check-user-password
</span> user password))
554 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">application-find-user
</span> (application username)
555 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Find USER by USERNAME for APPLICATION."</span>))
561 <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>
564 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">error-message
</span> (simple-window-component)
565 ((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>))
566 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Generic component for showing server side
567 error messages."</span>)
568 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class))
570 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">error-component
</span> (error-message)
571 ((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)
572 (backtrace
<span class=
"emacs-face-builtin">:accessor
</span> error.backtrace
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:backtrace
</span>))
573 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Generic component for showing server side
574 error conditions. Unlike ERROR-MESSAGE this component also
575 attempts to display a backtrace."</span>)
576 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class))
582 <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>
585 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">info-message
</span> ()
586 ((message
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:message
</span> <span class=
"emacs-face-builtin">:accessor
</span> message)
587 (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>))
588 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Component for showing a message to the user.
590 If the OK-TEXT slot is non-NIL component will use that as the
591 text for a link which, when clicked, causes the component to
592 answer. It follows that if OK-TEXT is NIL this component will
593 never answer."</span>)
594 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class))
598 <h5>option-dialog
</h5>
600 <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>
603 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">option-dialog
</span> (template-component)
604 ((message) (options) (confirm))
605 (
<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>)
606 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Component for querying the user.
608 The value of the slot MESSAGE is used as a general heading.
610 The OPTIONS slot must be an alist of (VALUE . LABEL). LABEL (a
611 string) will be used as the text of a link which, when clikced,
614 If the CONFIRM slot is T the user will be presented with a second
615 OPTION-DIALOG asking the user if they are sure they want to
616 submit that value."</span>)
617 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class))
620 <p>A macro to present an option dialog is provided.
</p>
623 (
<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)
627 <p><code>message-spec
</code> is passed to
<code>format
</code> if
<code>message-args
</code> are supplied, and
628 used as a string literal otherwise. This does not provide a way to set
629 the confirm property which makes the macro not so generally useful.
</p>
633 <h4><a name=
"sec11" id=
"sec11"></a>
636 <p class=
"first">Reasonably useful forms library that integrates easily with TAL.
</p>
638 <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>
641 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">form-field
</span> ()
642 ((validators
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"List of validators which will be
643 applied to this field."</span>)
644 (initially-validate
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"When non-NIL the
645 validators will be run as soon as the page
646 is rendered."</span>)))
648 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">value
</span> (form-field)
649 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"The lispish translated value that represents the form-field."</span>))
651 (
<span class=
"emacs-face-keyword">defgeneric
</span> (
<span class=
"emacs-face-function-name">setf value
</span>) (new-value form-field)
652 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Set the value of a form-field with translation to client."</span>))
654 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">generic-html-input
</span> (form-field html-element)
655 ((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>
656 <span class=
"emacs-face-builtin">:initform
</span> <span class=
"emacs-face-string">""</span>
657 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"The string the client submitted along with this field."</span>)
658 (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)
659 (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)
660 (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)
661 (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))
662 (
<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>)))
665 <p>Fields are rendered into the extended
<code><ucw:input
</code> yaclml tag which
666 supports a few fancy features. The
<code>:accessor
</code> for all form elements is
667 set to
<code>(client-value FIELD)
</code>, and you should use
<code>value
</code> to access the
668 Lisp value associated with it.
</p>
671 (deftag-macro
<ucw:input (
<span class=
"emacs-face-type">&attribute
</span> accessor action reader writer name id (default nil)
672 <span class=
"emacs-face-type">&allow-other-attributes
</span> others)
673 <span class=
"emacs-face-string">"Generic INPUT tag replacement.
675 If the ACCESSOR attribute is specified then it must be a PLACE
676 and it's value will be used to fill the input, when the form is
677 submitted it will be set to the new value.
679 If ACTION is specefied then when the form is submitted via this
680 input type=\"submit\
" tag the form will be eval'd. when the
681 submit (or image) is clicked. DEFAULT means that the ACTION
682 provided for this input tag will be the default action of the
683 form when pressing enter in a form field. If more then one, then
684 the latest wins."</span>)
687 <p>Validation of form fields are supported by adding to the validators
691 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">validator
</span> ()
692 ((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)))
694 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">validate
</span> (field validator)
695 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Validate a form-field with a validator."</span>))
697 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">javascript-check
</span> (field validator)
698 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Generate javascript code for checking FIELD against VALIDATOR.
700 This is the convenience entry point to generate-javascript-check,
701 methods defined on this generic funcition should return a list of
702 javascript code (as per parenscript) which tests against the
703 javascript variable value."</span>))
705 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">javascript-invalid-handler
</span> (field validator)
706 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"The javascript code body for when a field is invalid."</span>))
708 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">javascript-valid-handler
</span> (field validator)
709 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Generate the javascript body for when a field is valid."</span>))
712 <h5>Standard Form Fields
</h5>
715 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">string-field
</span> (generic-html-input)
716 ((input-size) (maxlength)))
718 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">password-field
</span> (string-field))
719 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">number-field
</span> (string-field))
720 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">integer-field
</span> (number-field))
722 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">in-field-string-field
</span> (string-field)
723 ((in-field-label
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"This slot, if non-NIL, will be
724 used as an initial field label. An initial
725 field label is a block of text which is placed
726 inside the input element and removed as soon
727 as the user edits the field. Obviously this
728 field is overidden by an initial :client-value
731 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">textarea-field
</span> (generic-html-input)
734 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">date-field
</span> (form-field widget-component)
735 ((year) (month) (day)))
737 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">dmy-date-field
</span> (date-field)
738 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Date fields which orders the inputs day/month/year"</span>))
739 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">mdy-date-field
</span> (date-field))
741 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">select-field
</span> (generic-html-input)
742 ((data-set
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"The values this select chooses
744 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Form field used for selecting one value from a
745 list of available options."</span>))
747 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">render-value
</span> (select-field value)
748 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"This function will be passed each value in the field's
749 data-set and must produce the body of the corresponding
750 <ucw:option tag."</span>))
752 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">mapping-select-field
</span> (select-field)
753 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Class used when we want to chose the values of
754 a certain mapping based on the keys. We render the keys in the
755 select and return the corresponding value from the VALUE
758 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">hash-table-select-field
</span> (mapping-select-field))
759 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">alist-select-field
</span> (mapping-select-field))
760 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">plist-select-field
</span> (mapping-select-field))
762 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">radio-group
</span> (generic-html-input)
765 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">radio-button
</span> (generic-html-input)
767 (group
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"The RADIO-GROUP this button is a part
769 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A widget representing a single radio
770 button. Should be used in conjunction with a RADIO-GROUP."</span>))
772 (
<span class=
"emacs-face-keyword">defmethod
</span> <span class=
"emacs-face-function-name">add-value
</span> ((group radio-group) value)
773 <span class=
"emacs-face-doc">"Adds radio-button with value to group"</span>)
775 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">checkbox-field
</span> (generic-html-input))
776 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">file-upload-field
</span> (generic-html-input))
777 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">submit-button
</span> (generic-html-input)
781 <h5>File Upload Field
</h5>
783 <p>Calling
<code>value
</code> on a
<code>file-upload-field
</code> returns a mime encoded body
784 part.
<code>(mime-part-body (value FIELD))
</code> will return a
<strong>binary stream
</strong>
785 attached to the contents of the file. The
<code>Content-Type
</code> header should
786 be set to the MIME type of the file being uploaded.
</p>
789 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">mime-part-headers
</span> (mime-part)
790 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Returns an alist of the headers of MIME-PART.
792 The alist must be of the form (NAME . VALUE) where both NAME and
793 VALUE are strings."</span>))
795 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">mime-part-body
</span> (mime-part)
796 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Returns the body of MIME-PART."</span>))
801 <h5>Standard Validators
</h5>
804 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">not-empty-validator
</span> (validator))
806 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">value-validator
</span> (validator)
807 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Validators that should only be applied if there is a value.
808 That is, they always succeed on nil."</span>))
810 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">length-validator
</span> (value-validator)
811 ((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>
812 <span class=
"emacs-face-builtin">:initform
</span> nil)
813 (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>
814 <span class=
"emacs-face-builtin">:initform
</span> nil)))
816 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">string=-validator
</span> (validator)
817 ((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>))
818 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Ensures that a field is string= to another one."</span>))
820 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">regex-validator
</span> (value-validator)
821 ((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)))
823 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">e-mail-address-validator
</span> (regex-validator))
825 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">phone-number-validator
</span> (regex-validator))
827 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">is-a-number-validator
</span> (value-validator))
828 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">is-an-integer-validator
</span> (is-a-number-validator))
830 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">number-range-validator
</span> (is-a-number-validator)
831 ((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)
832 (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)))
836 <h5>Simple Form Helper
</h5>
838 <p>UCW provides a helper class for developing forms. Subclass and add the
839 elements you wish to include in the form. A
<code>:wrapping
</code> method renders
840 the form boilerplate and then calls your
<code>render
</code>.
</p>
843 (defcomponent simple-form (html-element)
844 ((submit-method
<span class=
"emacs-face-builtin">:accessor
</span> submit-method
845 <span class=
"emacs-face-builtin">:initform
</span> <span class=
"emacs-face-string">"post"</span>
846 <span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:submit-method
</span>)
847 (dom-id
<span class=
"emacs-face-builtin">:accessor
</span> dom-id
848 <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>)
849 <span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:dom-id
</span>))
850 (
<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>))
855 <h4><a name=
"sec12" id=
"sec12"></a>
858 <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>
860 <p>Infrastructure for loading TAL templates as a view of a component.
</p>
863 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">template-component
</span> (component))
864 (defcomponent simple-template-component (template-component)
865 ((environment
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:environment
</span> <span class=
"emacs-face-builtin">:initform
</span> nil)))
867 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">template-component-environment
</span> (component)
868 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Create the TAL environment for rendering COMPONENT's template.
870 Methods defined on this generic function must return a TAL
871 environment: a list of TAL binding sets (see the documentation
872 for YACLML:MAKE-STANDARD-ENVIRONMENT for details on TAL
873 environments.)"</span>)
874 (
<span class=
"emacs-face-builtin">:method-combination
</span> nconc))
876 (
<span class=
"emacs-face-keyword">defmethod
</span> <span class=
"emacs-face-function-name">template-component-environment
</span> nconc ((component template-component))
877 <span class=
"emacs-face-string">"Create the basic TAL environment.
879 Binds the symbol ucw:component to the component object itself,
880 also puts the object COMPONENT on the environment (after the
881 binding of ucw:component) so that slots are, by default,
883 (make-standard-environment `((component . ,component)) component))
885 (
<span class=
"emacs-face-keyword">defmethod
</span> <span class=
"emacs-face-function-name">render
</span> ((component template-component))
886 <span class=
"emacs-face-doc">"Render a template based component.
888 Calls the component's template. The name of the template is the
889 value returned by the generic function
890 template-component.template-name, the template will be rendered
891 in the environment returned by the generic function
892 template-component-environment."</span>
893 (render-template *context*
894 (template-component.template-name component)
895 (template-component-environment component)))
899 <p>Subclass and override methods.
<code>simple-template-component
</code> only provides
900 the ability to set environment variables in initarg. Subclass to
901 provide automagic template file name generation and such.
</p>
904 <h4><a name=
"sec13" id=
"sec13"></a>
905 Utility Mixin Components
</h4>
909 <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>
912 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">range-view
</span> (template-component)
913 (
<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>)
914 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Component for showing the user a set of data one \"window\
" at a time.
916 The data set is presented one \"window\
" at a time with links to
917 the the first, previous, next and last window. Each window shows
918 at most WINDOW-SIZE elements of the data. The data is passed to
919 the range-view at instance creation time via the :DATA initarg.
921 The generic function RENDER-RANGE-VIEW-ITEM is used to render
924 In order to change the rendering of the single elements of a
925 range view developer's should create a sub class of RANGE-VIEW
926 and define their RENDER-RANGE-VIEW-ITEM methods on that."</span>)
927 (
<span class=
"emacs-face-builtin">:metaclass
</span> standard-component-class))
931 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">render-range-view-item
</span> (range-view item)
932 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Render a single element of a range-view."</span>)
933 (
<span class=
"emacs-face-builtin">:method
</span> ((range-view range-view) (item t))
934 <span class=
"emacs-face-string">"Standard implementation of RENDER-RANGE-VIEW-ITEM. Simply
935 applies ITEM to princ (via <:as-html)."</span>
936 (
<span class=
"emacs-face-keyword">declare
</span> (ignore range-view))
937 (
<:as-html item)))
943 <p>Mixin with existing component to wrap in a div or span. This is handy
944 for defining lightweight widgets embedded within other components.
</p>
946 <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>
949 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">html-element
</span> (component)
955 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"An HTML element.
957 HTML elements control aspects that are relevant to almost all tags.
959 Firstly they provide a place to store the class, id, and style of the
960 component. The specific render methods of the components themselves
961 must pass these values to whatever code is used to render the actual
964 Secondly, they allow javascript event handlers to be registered for a
965 tag. The events slot can be filled with a list of lists in the form
967 (event parenscript-statement*)
969 For example (\"onclick\
" (alert \"You clicked!\
") (return nil)). If
970 the element has a dom-id, these event handlers are automatically
974 <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>
977 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">widget-component
</span> (html-element)
979 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A widget which should be wrapped in a <div>."</span>))
981 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">inline-widget-component
</span> (html-element)
983 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A widget which should be wrapped in <span> and not <div>"</span>))
985 (
<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)))
986 (
<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)))
990 <h5>Transactions
</h5>
992 <p>A mixin to provide transactions.
<code>(open-transaction component)
</code> and
993 <code>(close-transaction component)
</code> open and closed nested
994 transactions. After a transaction has been closed an attempt to
995 backtrack into a step inside the transaction will result in jumping up
996 one level of transactions (or out of the transaction entirely if at
997 the top level). This ensures that the transaction is only run once,
1000 <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>
1003 (defcomponent transaction-mixin ()
1006 (defmethod/cc open-transaction ((comp transaction-mixin)))
1007 (defmethod/cc close-transaction ((comp transaction-mixin)))
1013 <p><code>(defaction start ...)
</code> on subclass to run a series of actions bundled
1016 <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>
1019 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">task-component
</span> (standard-component)
1021 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A controller for a single task or operation to
1022 be performed by the user.
1024 A task component's START action is called as soon as the
1025 component is instantiated. Task components do not have their own
1026 RENDER method, in fact they have no graphical representation but
1027 serve only to order a sequence of other components."</span>))
1029 (defgeneric/cc start (task)
1030 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"action which gets called automatically when
1031 task-component is active. Use defaction to define your own
1032 \"start\
" action"</span>))
1038 <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>
1041 (defcomponent cached-component ()
1042 ((cached-output
<span class=
"emacs-face-builtin">:accessor
</span> cached-output
<span class=
"emacs-face-builtin">:initform
</span> nil
1043 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"A string holding the output to
1044 use for this component. This string will be
1045 written directly to the html stream and is
1046 changed by the REFRESH-COMPONENT-OUTPUT
1048 (timeout
<span class=
"emacs-face-builtin">:accessor
</span> timeout
<span class=
"emacs-face-builtin">:initarg
</span> <span class=
"emacs-face-builtin">:timeout
</span>
1049 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"An value specifying how often this
1050 component needs to be refreshed. The exact
1051 interpretation of the value depends on the type of
1052 caching used class."</span>))
1053 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Component which caches its output.
1055 The component caching API is built around the generic functions
1056 COMPONENT-DIRTY-P and REFRESH-COMPONENT-OUTPUT and a method on
1057 RENDER, see the respective docstrings for more details.
1059 Do not use CACHED-COMPONENT directly, use one its subclasses."</span>))
1061 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">component-dirty-p
</span> (component)
1062 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Returns T is COMPONENT's cache is invalid."</span>))
1064 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">update-cache
</span> (component)
1065 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Update COMPONENT's cache variables after a refresh."</span>))
1067 (defcomponent timeout-cache-component (cached-component)
1068 ((last-refresh
<span class=
"emacs-face-builtin">:accessor
</span> last-refresh
<span class=
"emacs-face-builtin">:initform
</span> nil
1069 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"The time, exrpessed as a
1070 universal time, when the component was last rendered."</span>))
1071 (
<span class=
"emacs-face-builtin">:default-initargs
</span>
1072 <span class=
"emacs-face-builtin">:timeout
</span> (*
30 60 60))
1073 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Render the component at most every TIMEOUT seconds."</span>))
1075 (defcomponent num-hits-cache-component (cached-component)
1076 ((hits-since-refresh
<span class=
"emacs-face-builtin">:accessor
</span> hits-since-refresh
1077 <span class=
"emacs-face-builtin">:initform
</span> nil
1078 <span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Number of views since last refresh."</span>))
1079 (
<span class=
"emacs-face-builtin">:default-initargs
</span> <span class=
"emacs-face-builtin">:timeout
</span> 10)
1080 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Render the component every TIMEOUT views."</span>))
1083 <p>Subclass and override
<code>component-dirty-p
</code> to do something useful
1084 (e.g. flip mark bit when object being presented changes).
</p>
1089 <h3><a name=
"sec14" id=
"sec14"></a>
1092 <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>
1094 <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>
1096 <h4><a name=
"sec15" id=
"sec15"></a>
1099 <p class=
"first">Most of what you do in UCW will be calling components so this is a bit
1100 important. Note that calling interrupts the current control flow so if
1101 you want to render a component in place as part of another component
1102 just call
<code>render
</code> on it instead.
</p>
1105 (
<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)
1106 <span class=
"emacs-face-doc">"Stop the execution of the current action and pass control to
1107 a freshly created component of type COMPONENT-TYPE.
1109 COMPONENT-INIT-ARGS are passed directly to the underlying
1110 make-instance call. This form will return if and when the call'd
1111 component calls answer, the value returned by this form is
1112 whatever the call'd component passed to answer.
1116 This macro assumes that the lexcial variable UCW:SELF is bound to
1117 the calling component."</span>)
1119 (answer VAL)
<span class=
"emacs-face-comment">; answer parent component ONLY IN ACTIONS
1121 (ok SELF VAL)
<span class=
"emacs-face-comment">; Used to answer a component anywhere and what answer
1122 </span> <span class=
"emacs-face-comment">; expands into
1124 (jump COMPONENT-NAME
<span class=
"emacs-face-type">&REST
</span> ARGS)
<span class=
"emacs-face-comment">; is similar to call, but replaces
1125 </span> <span class=
"emacs-face-comment">; the current component with the new
1126 </span> <span class=
"emacs-face-comment">; one and drops any backtracks (back
1127 </span> <span class=
"emacs-face-comment">; button will no longer work)
1130 <p><code>(call COMPONENT-NAME
&ARGS INIT-ARGS)
</code> calls
<code>COMPONENT-NAME
</code> and returns
1131 the value returned by
<code>(ok SELF RETURN-VALUE)
</code> called from within
1132 <code>COMPONENT-NAME
</code></p>
1135 <h4><a name=
"sec16" id=
"sec16"></a>
1138 <p class=
"first">Actions are methods on components. The first argument
<strong>must
</strong> be a
1139 component for most of UCW to work.
</p>
1142 (defaction NAME (first ...) ...)
1143 <span class=
"emacs-face-comment">; (roughly) expands into
1144 </span>(defmethod/cc NAME (first ...)
1145 (
<span class=
"emacs-face-keyword">let
</span> ((self first))
1149 <p><code>Self
</code> being bound in the current lexical environment is required for
1150 most UCW control flow things to work.
<code>defaction
</code> hides this from you,
1151 and was a big source of confusion for me early on (mostly
"hmm, why is
1152 this not working ... where did that come from in the
1153 macroexpansion!
").
</p>
1156 <h4><a name=
"sec17" id=
"sec17"></a>
1160 (defentry-point url (
<span class=
"emacs-face-builtin">:application
</span> APPLICATION
1161 <span class=
"emacs-face-builtin">:class
</span> DISPATCHER-CLASS)
1162 (PARAM1 ... PARAMN)
<span class=
"emacs-face-comment">; GET / POST vars, bound in body
1166 <p>An entry point is what it sounds like: a static URL matched using the
1167 mater of
<code>DISPATCHER-CLASS
</code> that enters into
<code>APPLICATION
</code> running the
1168 code in
<code>body
</code>. An example from a test program I have written
1169 follows. The entry point allows files to be streamed to user when the
1170 url audio.ucw?file=FOO is used.
</p>
1173 (defentry-point
<span class=
"emacs-face-string">"^(audio.ucw|)$"</span> (
<span class=
"emacs-face-builtin">:application
</span> *golf-test-app*
1174 <span class=
"emacs-face-builtin">:class
</span> regexp-dispatcher)
1176 (call 'audio-file-window
1177 <span class=
"emacs-face-builtin">:audio-file
</span> (make-instance 'audio-file
1178 <span class=
"emacs-face-builtin">:type
</span> <span class=
"emacs-face-builtin">:vorbis
</span>
1179 <span class=
"emacs-face-builtin">:data
</span> (file-
>bytes (open
1181 <span class=
"emacs-face-builtin">:element-type
</span> 'unsigned-byte)))))
1186 <h3><a name=
"sec18" id=
"sec18"></a>
1189 <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>
1192 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">matcher-match
</span> (matcher application context)
1193 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Abstract method for subclasses to implement a
1194 matcher. This method would return multiple-values according to
1195 matcher internal nature.
1197 No methods defined on this function may rebind *context*, nor
1198 change CONTEXT's application. Only if the method matches the
1199 request, it is allowed to modify CONTEXT or APPLICATION, even in
1200 that case methods defined on this function must not modify
1201 CONTEXT's application nor rebind *context*."</span>))
1203 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">handler-handle
</span> (handler application context matcher-result)
1204 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Abstract function for handler classes to
1205 implement in order to handle a request matched by relevant
1208 These methods may modify context as they wish since they'r
1209 matched, request will be closed after this method is run."</span>))
1211 (
<span class=
"emacs-face-keyword">defgeneric
</span> <span class=
"emacs-face-function-name">dispatch
</span> (dispatcher application context)
1212 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"Entry point into a dispatcher. Must return T
1213 if the context has been handled or NIL if it hasn't.
1215 No methods defined on this function may rebind *context*, nor
1216 change CONTEXT's application. Only if the method returns T is it
1217 allowed to modify CONTEXT or APPLICATION, even in that case
1218 methods defined on this function must not modify CONTEXT's
1219 application nor rebind *context*."</span>))
1223 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">my-matcher
</span> (abstract-matcher) ...)
1224 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">my-handler
</span> (abstract-handler) ...)
1225 (
<span class=
"emacs-face-keyword">defclass
</span> <span class=
"emacs-face-type">my-dispatcher
</span> (abstract-dispatcher my-matcher my-handler)
1229 <h4><a name=
"sec19" id=
"sec19"></a>
1230 Simple Dispatcher
</h4>
1233 (
<span class=
"emacs-face-builtin">:documentation
</span> <span class=
"emacs-face-doc">"This class of dispatchers avoids all of UCW's
1234 standard call/cc (and therefore frame/backtracking/component)
1237 Unlike all other UCW dispatchers a simple-dispatcher must not use
1238 CALL, and must perform the rendering directly within the handler."</span>)
1243 <h3><a name=
"sec20" id=
"sec20"></a>
1246 <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>
1249 (
<span class=
"emacs-face-keyword">defun
</span> <span class=
"emacs-face-function-name">create-server
</span> (
<span class=
"emacs-face-type">&key
</span>
1250 (backend `(,*ucw-backend-type*
<span class=
"emacs-face-builtin">:host
</span> ,*ucw-backend-host*
1251 <span class=
"emacs-face-builtin">:port
</span> ,*ucw-backend-port*))
1252 (applications *ucw-applications*)
1254 (server-class *ucw-server-class*)
1255 (log-root-directory (truename *ucw-log-root-directory*))
1256 (log-level *ucw-log-level*))
1257 <span class=
"emacs-face-doc">"Creates and returns a UCW server according to SERVER-CLASS, HOST and
1258 PORT. Affects *DEFAULT-SERVER*.
1260 BACKEND is a list of (BACKEND-TYPE &rest INITARGS). BACKEND-TYPE
1261 may be :HTTPD, :MOD-LISP, :ASERVE, :ARANEIDA, an existing
1262 backend, an existing UCW server backend or :DEFAULT in which case
1263 it attempts to return a sane default from the UCW backends loaded
1264 and available, or any other value for which a valid MAKE-BACKEND
1265 method has been defined. INITARGS will be passed, unmodified, to
1268 APPLICATIONS is a list of defined applications to be loaded into the
1271 Logs are generated in verbosity defined by LOG-LEVEL and directed to
1272 LOG-ROOT-DIRECTORY if defined."</span>
1274 server)
<span class=
"emacs-face-comment">; return server, naturally
1278 <h3><a name=
"sec21" id=
"sec21"></a>
1281 <h4><a name=
"sec22" id=
"sec22"></a>
1284 <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>
1287 (defaction call-inspector ((component component) datum)
1288 <span class=
"emacs-face-string">"Call an inspector for DATUM on the component COMPONENT."</span>
1289 (call 'ucw-inspector
<span class=
"emacs-face-builtin">:datum
</span> datum))
1295 <h2><a name=
"sec23" id=
"sec23"></a>
1298 <h3><a name=
"sec24" id=
"sec24"></a>
1299 Getting dojo to load
</h3>
1301 <p class=
"first">I had some trouble getting dojo to work properly with UCW. The way
1302 that the
<code>:www-roots
</code> option for an application works is a bit
1303 confusing, and it is unforgiving if you mess the pathname up. A
1304 directory
<strong>must
</strong> have a
<code>/
</code> at the end, and the directory you are serving
1305 must also have the
<code>/
</code> (which is counterintuitive given the behavior of
1306 most unix things that don't want the
<code>/
</code> at the end of the name).
</p>
1309 <span class=
"emacs-face-builtin">:www-roots
</span> (list '(
<span class=
"emacs-face-string">"dojo/"</span> .
1310 #P
<span class=
"emacs-face-string">"/home/clinton/src/ucw/darcs/ucw_dev/wwwroot/dojo/"</span>))
1314 <h3><a name=
"sec25" id=
"sec25"></a>
1315 Specials Bound During Rendering
</h3>
1317 <p class=
"first">The current request context is bound to
<code>ucw:*context*
</code>, and the current
1318 component is bound to
<code>ucw:*current-component*
</code> in the dynamic extent of
1319 <code>render
</code>.
</p>
1322 <h3><a name=
"sec26" id=
"sec26"></a>
1323 Printing to the yaclml stream
</h3>
1325 <p class=
"first">Occasionally it can be useful to do something like write a byte array
1326 as an ascii string to the client. Inside of
<code>render
</code> the variable
1327 <code>yaclml:*yaclml-stream*
</code> is bound to the stream that you can write to if
1328 you wish to have content interspersed with yaclml tags.
</p>
1332 <!-- Page published by Emacs Muse ends here -->
1334 <p class=
"cke-buttons">
1335 <!-- validating badges, any browser, etc -->
1336 <a href=
"https://validator.w3.org/check/referer"><img
1337 src=
"https://www.w3.org/Icons/valid-xhtml10"
1338 alt=
"Valid XHTML 1.0!" /></a>
1340 <a href=
"https://www.anybrowser.org/campaign/"><img
1341 src=
"img/buttons/w3c_ab.png" alt=
"[ Viewable With Any Browser
1344 <a href=
"https://www.debian.org/"><img
1345 src=
"img/buttons/debian.png" alt=
"[ Powered by Debian ]" /></a>
1347 <a href=
"https://hcoop.net/">
1348 <img src=
"img/buttons/hcoop.png"
1349 alt=
"[ Hosted by HCoop]" />
1352 <a href=
"https://www.fsf.org/register_form?referrer=114">
1353 <img src=
"img/buttons/fsf_member.png"
1354 alt=
"[ FSF Associate Member ]" />
1358 <p class=
"cke-footer">If nothing in the world can change our children will inherit nothing
1360 <p class=
"cke-timestamp">Last Modified:
1361 January
21,
2013</p>