PageRenderTime 81ms CodeModel.GetById 26ms RepoModel.GetById 0ms app.codeStats 1ms

/site/ucw-boxset/ucw_ajax/docs/ucw-intro/ucw-intro.html

https://github.com/vikram/lisplibraries
HTML | 1448 lines | 1402 code | 19 blank | 27 comment | 0 complexity | bbd353aeba5610d7e4175fbb3d19ecb0 MD5 | raw file
Possible License(s): LGPL-2.0, LGPL-2.1, CC-BY-SA-3.0, LGPL-3.0, BSD-3-Clause, GPL-2.0

Large files files are truncated, but you can click here to view the full file

  1. <html>
  2. <head>
  3. <title>UCW intro</title>
  4. <link rel='stylesheet' type='text/css' href='style.css'>
  5. </head>
  6. <!--Creative Commons License-->
  7. <a rel="license"
  8. href="http://creativecommons.org/licenses/by-nc-sa/2.5/"><img
  9. alt="Creative Commons License"
  10. align='right'
  11. src="http://creativecommons.org/images/public/somerights20.png"
  12. border="0">
  13. </a>
  14. <!--/Creative Commons License--><!-- <rdf:RDF xmlns="http://web.resource.org/cc/" xmlns:dc="http://purl.org/dc/elements/1.1/"
  15. xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
  16. <Work rdf:about="">
  17. <license rdf:resource="http://creativecommons.org/licenses/by-nc-sa/2.5/" />
  18. <dc:title>UCW intro</dc:title>
  19. <dc:date>2006</dc:date>
  20. <dc:description>You don't have to mention
  21. my name or where you got the content from if you want to use this
  22. work for your own purposes, just keep by this license (why would of
  23. course be another question ;)). If you want
  24. to use any of this for commercial use or in another way that's not
  25. covered by the licence, just send me an email (see somewhere on the
  26. page if present) and we can probably work something out.</dc:description>
  27. <dc:creator><Agent><dc:title>Ties Stuij</dc:title></Agent></dc:creator>
  28. <dc:rights><Agent><dc:title>Ties Stuij</dc:title></Agent></dc:rights>
  29. <dc:source rdf:resource="www.fallenfrukt.com" />
  30. </Work>
  31. <License
  32. rdf:about="http://creativecommons.org/licenses/by-nc-sa/2.5/"><permits
  33. rdf:resource="http://web.resource.org/cc/Reproduction"/><permits
  34. rdf:resource="http://web.resource.org/cc/Distribution"/><requires
  35. rdf:resource="http://web.resource.org/cc/Notice"/><requires
  36. rdf:resource="http://web.resource.org/cc/Attribution"/><prohibits
  37. rdf:resource="http://web.resource.org/cc/CommercialUse"/><permits
  38. rdf:resource="http://web.resource.org/cc/DerivativeWorks"/><requires
  39. rdf:resource="http://web.resource.org/cc/ShareAlike"/></License></rdf:RDF> -->
  40. <body>
  41. <h1>UCW intro</h1>
  42. <p>advertisement: ucw is now easily installable!! (experimental)
  43. <br>
  44. Get <a href='http://common-lisp.net/project/ucw/ucw-boxset.tar.gz'>http://common-lisp.net/project/ucw/ucw-boxset.tar.gz</a>, untar it, cd into the dir and execute:</p>
  45. <pre>
  46. YOURLISPHERE (-)-load start.lisp
  47. </pre>
  48. <p>last modified 4th of may 2006</p>
  49. <p>- added ucw-boxset info
  50. <br>
  51. - added debugging tools chapter
  52. <br>
  53. - added tabbed pane info in the templating chapter
  54. <br>
  55. - added info on slightly changed startup procedure
  56. <br>
  57. - fixed bugs concerning variable passing between pages in basics.lisp
  58. <br>
  59. - fixed little bug in the spliced-href slot</p>
  60. <p>table of content:
  61. <ul>
  62. <li><a href='#intro'>Introduction</a></li>
  63. <li><a href='#install'>Installation</a></li>
  64. <li><a href='#extra'>Add-ons</a></li>
  65. <li><a href='#testing'>Testing/Quickstart</a></li>
  66. <li><a href='#configure'>Configuration</a></li>
  67. <li><a href='#environment'>Setting up the environment (and a hello world on the side)</a></li>
  68. <li><a href='#mechanics'>Basic ucw mechanics</a></li>
  69. <li><a href='#templating'>Templating: nested components, containers and TAL</a></li>
  70. <li>Login sessions</li>
  71. <li>Downloading files</li>
  72. <li>Advanced form handling</li>
  73. <li>To backtrack or not to backtrack</li>
  74. <li>Ajax</li>
  75. <li>Really, really, really cool example application</li>
  76. <li><a href='#debugging'>Debugging tools</a></li>
  77. <li><a href='#source'>Source</a></li>
  78. <li><a href='#miscellaneous'>Miscellaneous</a></li>
  79. </ul>
  80. </p>
  81. <p><span id='intro'></span></p>
  82. <h2>Introduction</h2>
  83. <p>This text will introduce you in a mild mannered pace to the ways of this as of yet UnCommon Web
  84. framework, which is a framework to write web applications as you would write normal applications; e.g. with state. Check ucw's
  85. <a href='http://common-lisp.net/project/ucw/features.html'>features page</a> to get an impression of its features. Ucw is an
  86. open source project. Various people donate code on a regular basis. Check the
  87. <a href='http://common-lisp.net/cgi-bin/mailman/listinfo/bese-devel'>mailing list</a> for a flavour of the current topics. If you're
  88. wondering about the merits and weaknesses of either state or stateless web development check
  89. <a href='http://common-lisp.net/project/ucw/docs/html/rest/rest.html'>this rather nice one-page email conversation</a>
  90. between the creator of ucw and a non-believer. If you want to use ucw on a windows machine, I have got no experience or information on
  91. workability, but i would very much like to hear about your experiences.</p>
  92. <p>This introduction wants to introduce UCW in a slow and concise manner. We will start with
  93. the installation and an initial setup. Then slowly, through simple examples, the reader will be introduced to the
  94. various components. We will delve from the outside in and will perhaps some day hit upon the burning hot core. For the
  95. brilliant and the impatient this pace will just be to damn slow. Them I advice to read and watch some
  96. other tutorials and documentation. They are:</p>
  97. <ul>
  98. <li><a href='http://www.cliki.net/ucw%20Tutorial'>UCW Tutorial</a> - a cliki tutorial in progress, not dissimilar to mine, which
  99. sets up a quick working environment and explains the different components with a lot of code.</li>
  100. <li><a href='http://common-lisp.net/project/ucw/documentation.html'>the ucw documentation page</a> - diverse documentation sources
  101. which are a bit out of date. The email conversations are very interesting to get a good grasp of the use and limitations of ucw, and the
  102. video, although out of date, is interesting because you get to see ucw in action. Be warned: the source-code and the wiki example are a bit
  103. out of date last time I checked. Better to just download the source code, in which you will also find the wiki example.</li>
  104. <li>the source code - the docs section of the source code unlocks apache setup code, two quickstarts which may be a bit out of date, and
  105. more. Also check the examples directory relative to the root. It gives you a good idea how to code up various aspects of ucw and it harbors
  106. the wiki-example. It might just be a bit obvious but in the source code you can also read the source code; it offers great insight in the way ucw is put together.</li>
  107. </ul>
  108. <p><span id='install'></span></p>
  109. <h2>Installation</h2>
  110. <p>First off UCW doesn't do version numbers. Some people may remember it did and it did, but it doesn't anymore. Still there are two versions
  111. of UCW to choose from: ucw_dev and ucw_public, both held in a Darcs repository. ucw_dev is controlled by Marco Baringer, creator of
  112. ucw. Ucw_public is world writable. At the moment I would advise to go with ucw_dev which is also the focus of this intro. _public is not always in sync with _dev, although lately it does a good job of keeping up.</p>
  113. <h3>The (experimental) easy way</h3>
  114. <p>There's a shortcut nowadays. Marco Baringer made a UCW candybox
  115. with all the dependencies boxed up and ready to fire. At the moment
  116. it's quite experimental, but if it doesn't work at least you've got all
  117. the dependencies in one go. Try:</p>
  118. <p>wget <a href='http://common-lisp.net/project/ucw/ucw-boxset.tar.gz'>http://common-lisp.net/project/ucw/ucw-boxset.tar.gz</a>
  119. tar -zxf ucw-boxset.tar.gz
  120. cd ucw-boxset
  121. YOURLISPHERE (-)-load start.lisp</p>
  122. <p>This will start UCW with the built in httpd server backend. But if you
  123. want to get the dependencies seperately or want a different initial setup,
  124. read and get some of the following:</p>
  125. <h3>The (old and boring) hard way</h3>
  126. <p>To get _dev or _public, install Darcs on your computer and execute:</p>
  127. <pre>
  128. darcs get http://common-lisp.net/project/ucw/repos/ucw_dev
  129. </pre>
  130. <p>or</p>
  131. <pre>
  132. darcs get http://common-lisp.net/project/ucw/repos/ucw_public
  133. </pre>
  134. <p>Daily snapshots for ucw_dev are available at
  135. <a href='http://common-lisp.net/project/ucw/tarballs/ucw_dev-latest.tar.gz'>http://common-lisp.net/project/ucw/tarballs/ucw_dev-latest.tar.gz</a></p>
  136. <p>Daily snapshots for ucw_public are available at
  137. <a href='http://common-lisp.net/project/ucw/tarballs/ucw_public-latest.tar.gz'>http://common-lisp.net/project/ucw/tarballs/ucw_public-latest.tar.gz</a></p>
  138. <p>Now it is time for the dependencies. A word of caution: ucw has it's own versions for a number of libraries so even if
  139. you already have the latest version of some package, check this documentation or the readme supplied with the
  140. sources. As a rule of thumb, get the latest of everything and the ucw version if supplied.</p>
  141. <p>At the moment UCW requires the following
  142. dependencies:</p>
  143. <ul>
  144. <li><a href='#implementation'>a lisp implementation - one of the following: sbcl, cmucl, allegro, lispworks, openmcl</a></li>
  145. <li><a href='#arnesi'>arnesi - an all purpose lisp toolkit</a></li>
  146. <li><a href='#yaclml'>yaclml - yet another common lisp markup language</a></li>
  147. <li><a href='#parenscript'>parenscript - javascript in common-lisp</a></li>
  148. <li><a href='#iterate'>iterate - a lispy loop</a></li>
  149. <li><a href='#rfc2388'>rfc2388 - implements multipart/form specification</a></li>
  150. <li><a href='#rfc2109'>rfc2109 - implements cookie specification</a></li>
  151. <li><a href='#split-sequence'>split-sequence - splits sequences</a></li>
  152. <li><a href='#slime'>slime - Superior Lisp Interaction Mode for Emacs</a></li>
  153. <li><a href='#cl-ppcre'>cl-ppcre - regular expressions lib</a></li>
  154. <li><a href='#trivial-sockets'>trivial-sockets - handles stream sockets for undemanding network applications</a></li>
  155. <li><a href='#puri'>net.uri or PURI - parses URI's according to the RFC 2396 specification</a></li>
  156. <li><a href='#cl-fad'>cl-fad - a portable pathname library based on code from PCL</a></li>
  157. <li><a href='#cl-launch'>cl-launch - invokes lisp code from the command line</a></li>
  158. <li><a href='#detachtty'>detachtty - a screen-like detachment tool to be able to detach and reattach the lisp server from and to a console</a></li>
  159. <li><a href='#backend'>a server backend - be it mod_lisp (apache 1 or 2), araneida, allegroserve, portable aserve or the built in httpd server</a></li>
  160. <li><a href='#asdf'>asdf - a package loader facility</a></li>
  161. </ul>
  162. <p>A note on compatibility: Some configurations of implementation and server work better than others. Just report your bugs in the
  163. <a href='http://common-lisp.net/cgi-bin/mailman/listinfo/bese-devel'>mailinglist</a>, the list is quite responsive. As a pointer, an
  164. implementation/server-pair of sbcl or openmcl and mod_lisp seem too see the heaviest testing. The built-in httpd server also works well but
  165. isn't fit for production use.</p>
  166. <p><span id='implementation'></span></p>
  167. <h4>Implementation.</h4>
  168. <p>Pick one in the list above.</p>
  169. <h4>Debian</h4>
  170. <p>Someone from Debian (Luca Capello) is working hard to to support ucw out of the box, but he is not quite there yet. Keep an eye on the
  171. cl-debian mailing list
  172. (<a href='http://common-lisp.net/pipermail/cl-debian/2006-March/001113.html'>UCW status, seeing the light at the end of the tunnel</a>) for the latest developments.</p>
  173. <p><span id='arnesi'></span></p>
  174. <h4>Dependencies</h4>
  175. <h5>arnesi</h5>
  176. <p>Arnesi is a Common Lisp utility suite. It contains various "bits 'n
  177. pieces" of code which were useful while developing other code. It can
  178. be found on <a href='http://common-lisp.net/project/bese/arnesi.html'>http://common-lisp.net/project/bese/arnesi.html</a>.</p>
  179. <p>You will need the latest version:</p>
  180. <pre>
  181. darcs get http://common-lisp.net/project/bese/repos/arnesi_dev/
  182. </pre>
  183. <p>Daily snapshots are available at
  184. <a href='http://common-lisp.net/project/bese/tarballs/arnesi_dev-latest.tar.gz'>http://common-lisp.net/project/bese/tarballs/arnesi_dev-latest.tar.gz</a></p>
  185. <p><span id='yaclml'></span></p>
  186. <h5>yaclml</h5>
  187. <p>yaclml is a collection of macros and utilities for generating XML/HTML
  188. like markup from lisp code. It can be found on
  189. <a href='http://common-lisp.net/project/bese/yaclml.html'>http://common-lisp.net/project/bese/yaclml.html</a>. </p>
  190. <p>You will need the latest version:</p>
  191. <pre>
  192. darcs get http://common-lisp.net/project/bese/repos/yaclml/
  193. </pre>
  194. <p>Daily snapshots are available at: <a href='http://common-lisp.net/project/bese/tarballs/yaclml-latest.tar.gz'>http://common-lisp.net/project/bese/tarballs/yaclml-latest.tar.gz</a></p>
  195. <p><span id='parenscript'></span></p>
  196. <h5>parenscript - ucw version</h5>
  197. <p>Parenscript is a javascript compiler. You will need to get the latest development version:</p>
  198. <pre>
  199. darcs get http://common-lisp.net/project/ucw/repos/parenscript/
  200. </pre>
  201. <p>Daily snapshots are available at: <a href='http://common-lisp.net/project/ucw/tarballs/parenscript-latest.tar.gz'>http://common-lisp.net/project/ucw/tarballs/parenscript-latest.tar.gz</a></p>
  202. <p><span id='iterate'></span></p>
  203. <h5>iterate</h5>
  204. <p>Iterate is an iteration construct for Common Lisp. It can be found on</p>
  205. <a href='http://common-lisp.net/project/iterate/'>http://common-lisp.net/project/iterate/</a>
  206. <p>Download link: <a href='http://common-lisp.net/project/iterate/releases/iterate-current.tar.gz'>http://common-lisp.net/project/iterate/releases/iterate-current.tar.gz</a></p>
  207. <p><span id='rfc2388'></span></p>
  208. <h5>rfc2388 - ucw version</h5>
  209. <p>Rfc2388 is a lisp implemantation of RFC 2388, which is used to process form
  210. data posted with HTTP POST method using enctype "multipart/form-data".</p>
  211. <p>UCW uses its own fork of rfc2388. You can get the latest code from the
  212. darcs repository located at
  213. <a href='http://common-lisp.net/project/ucw/repos/rfc2388'>http://common-lisp.net/project/ucw/repos/rfc2388</a>:</p>
  214. <pre>
  215. darcs get http://common-lisp.net/project/ucw/repos/rfc2388/
  216. </pre>
  217. <p>Daily snapshots are available at <a href='http://common-lisp.net/project/ucw/tarballs/rfc2388-latest.tar.gz'>http://common-lisp.net/project/ucw/tarballs/rfc2388-latest.tar.gz</a></p>
  218. <p><span id='rfc2109'></span></p>
  219. <h5>rfc2109 - ucw version</h5>
  220. <p>Rfc2109 is the lisp implementation of the cookie protocol. You can get
  221. it at:
  222. <a href='http://common-lisp.net/project/rfc2109'>http://common-lisp.net/project/rfc2109/</a>:</p>
  223. <pre>
  224. darcs get http://common-lisp.net/project/rfc2109/rfc2109
  225. </pre>
  226. <p>Daily snapshots are available at
  227. <a href='http://www.common-lisp.net/project/rfc2109/release/rfc2109-latest.tar.gz '>http://www.common-lisp.net/project/rfc2109/release/rfc2109-latest.tar.gz </a></p>
  228. <p><span id='split-sequence'></span></p>
  229. <h5>split-sequence</h5>
  230. <p>splits sequences</p>
  231. <p>info: <a href='http://www.cliki.net/SPLIT-SEQUENCE'>http://www.cliki.net/SPLIT-SEQUENCE</a></p>
  232. <p>download: <a href='http://ww.telent.net/cclan/split-sequence.tar.gz'>http://ww.telent.net/cclan/split-sequence.tar.gz</a>
  233. (you might have to select a mirror first)</p>
  234. <p>If said link is dead, go to <a href='http://ww.telent.net/cclan-choose-mirror'>http://ww.telent.net/cclan-choose-mirror</a>
  235. to delete your CCLAN-SITE cookie and choose another mirror. At least some of them are definitely working. </p>
  236. <p><span id='slime'></span></p>
  237. <h5>SLIME</h5>
  238. <p>The Superior Lisp Interaction Mode for Emacs.</p>
  239. <p>Download and install the latest CVS version of SLIME from
  240. <a href='http://common-lisp.net/project/slime'>http://common-lisp.net/project/slime</a>.</p>
  241. <p>To checkout from CVS you must first login to the repository:</p>
  242. <pre>
  243. export CVSROOT=:pserver:anonymous@common-lisp.net:/project/slime/cvsroot
  244. cvs login
  245. </pre>
  246. <p>Enter anonymous when prompted for the password. You can then check out the latest version with:</p>
  247. <pre>
  248. cvs checkout slime
  249. </pre>
  250. <p>It's swank you want to add to your asd systems dir. To solve a current problem
  251. with cl-launch you might want to overwrite your swank.asd file with this one:</p>
  252. <a href='http://cl-debian.alioth.debian.org/repository/pvaneynd/slime/debian/swank.asd'>http://cl-debian.alioth.debian.org/repository/pvaneynd/slime/debian/swank.asd</a>
  253. <p>Check the description on cl-launch to see why.</p>
  254. <p><span id='cl-ppcre'></span></p>
  255. <h5>cl-ppcre</h5>
  256. <p>Edi Weitz's regular expression library: <a href='http://www.weitz.de/cl-ppcre/'>http://www.weitz.de/cl-ppcre/</a>.</p>
  257. <p>Download the latest version: <a href='http://weitz.de/files/cl-ppcre.tar.gz'>http://weitz.de/files/cl-ppcre.tar.gz</a></p>
  258. <p><span id='trivial-sockets'></span></p>
  259. <h5>trivial-sockets</h5>
  260. <p>Networking library to create small server applications. Download the latest version from:
  261. <a href='http://ww.telent.net/cclan/trivial-sockets.tar.gz'>http://ww.telent.net/cclan/trivial-sockets.tar.gz</a>
  262. (you might have to select a mirror first.</p>
  263. <p>If said link is dead, go to <a href='http://ww.telent.net/cclan-choose-mirror'>http://ww.telent.net/cclan-choose-mirror</a>
  264. to delete your CCLAN-SITE cookie and choose another mirror. At least some of them are definitely working. </p>
  265. <p>Or use asdf install.</p>
  266. <p><span id='puri'></span></p>
  267. <h5>net.uri/PURI</h5>
  268. <p>All of the backends (except araneida) depend on Franz's open-source
  269. net.uri library. It only works on Allegro but Kevin Rosenberg has made a portable version called PURI.</p>
  270. <p>For allegro users, NET.URI can be downloaded from here (it may be included in your
  271. version of acl):
  272. <a href='http://opensource.franz.com/uri/index.html'>http://opensource.franz.com/uri/index.html</a> </p>
  273. <p>If you're not using allegro you'll need puri which can be
  274. downloaded from <a href='http://puri.b9.com/download.html'>http://puri.b9.com/download.html</a></p>
  275. <p><span id='cl-fad'></span></p>
  276. <h5>cl-fad</h5>
  277. <p>A portable pathname library based on code from Peter Seibels book Practical Common Lisp. </p>
  278. <p>info: <a href='http://www.cliki.net/CL-FAD'>http://www.cliki.net/CL-FAD</a></p>
  279. <p>download: <a href='http://weitz.de/files/cl-fad.tar.gz'>http://weitz.de/files/cl-fad.tar.gz</a></p>
  280. <p><span id='cl-launch'></span></p>
  281. <h5>cl-launch</h5>
  282. <p>A bash script to make your Lisp software easily invokable from the shell command-line.</p>
  283. <p>info: <a href='http://www.cliki.net/cl-launch'>http://www.cliki.net/cl-launch</a></p>
  284. <p>download page: <a href='http://fare.tunes.org/files/cl-launch/'>http://fare.tunes.org/files/cl-launch/</a></p>
  285. <p>Download and add to your shell executable search path so ucw can find it while loading. Cl-launch can either be called cl-launch or
  286. cl-launch.sh, ucw will check for both. Also cl-launch depends on swank behavior other than that of the current cvs code, at least under sbcl, eg via swank-loader it looks for files under the load path, which is not what you want if you made a symbolic link to another dir. The easiest way to get around this problem is to overwrite your swank.asd file (in the slime directory root), with this one:</p>
  287. <a href='http://cl-debian.alioth.debian.org/repository/pvaneynd/slime/debian/swank.asd'>http://cl-debian.alioth.debian.org/repository/pvaneynd/slime/debian/swank.asd</a>
  288. <p>The downside might be that swank won't work anymore as it should, although i haven't heard anyone about this yet. Another approach is to copy your swank*.fasls from the slime directory to the relevant shadow directory under ~/.cache/...</p>
  289. <p>Check this thread for more info:</p>
  290. <a href='http://common-lisp.net/pipermail/slime-devel/2006-March/004664.html'>http://common-lisp.net/pipermail/slime-devel/2006-March/004664.html</a>
  291. <p>Yes, ucw is bleeding edge ;)</p>
  292. <p><span id='detachtty'></span></p>
  293. <h5>detachtty - ucw version</h5>
  294. <p>A screen-like detachment tool to be able to detach and re-attach the lisp server from and to a console.
  295. Ucw uses a custom detachtty version, e.g. detachtty-9 plus a patch by Kevin Rosenberg. It accepts an eval argument when
  296. invoking a lisp, with obvious benefits. Get it through Darcs:</p>
  297. <pre>
  298. darcs get http://common-lisp.net/project/bese/repos/detachtty/
  299. </pre>
  300. <p>Go to the directory root and compile and install:</p>
  301. <pre>
  302. make
  303. make install
  304. </pre>
  305. <p><span id='backend'></span></p>
  306. <h4>the backend</h4>
  307. <p>Ucw supports all the popular lisp backends. Whichever floats your boat. If you've got no clue which to choose I'd advice
  308. to go for mod_lisp. It works well with other languages, you get the benefit of apaches options and extras and all it does
  309. is pump the code straight to ucw so there's no trouble with quirks in the intermediate layer. Apache requires some work
  310. to function correctly, read the text below. The other backends should work out of the box, as long as they're recognized by
  311. asdf. aserve as well as portable aserve are in the package systems of gentoo and debian. Gentoo also supports mod_lisp
  312. and mod_lisp2 for apache and araneida. Read <a href='http://bc.tech.coop/blog/051219.html'>this blog post</a> by
  313. Bill Clementson to form a more balanced opinion.</p>
  314. <h5>mod_lisp/mod_lisp2 for apache</h5>
  315. <p>You can choose between apache 1 and 2. First of course you have to have a Apache web
  316. server up and runnnig; then you have to add the mod-lisp module by Marc
  317. Battyani which you find at <a href='http://www.fractalconcept.com/asp/html/mod_lisp.html'>http://www.fractalconcept.com/asp/html/mod_lisp.html</a></p>
  318. <p>First download the mod_lisp c file. Watch out, don't follow the logic of the website. Except for the windows version the
  319. info is outdated concerning the apache 1 version and info about apache 2 is non-existent. Go to subversion from the
  320. download page or click the links below:</p>
  321. <ul>
  322. <li>apache 1 .c file -
  323. <a href='http://www.fractalconcept.com:8000/public/open-source/mod_lisp/mod_lisp.c'>mod_lisp.c</a></li>
  324. <li>apache 1 binaries for windows - there is a link on the site for version 2.32 but it leads to nowhere</li>
  325. <li>apache 2 .c file - <a href='http://www.fractalconcept.com:8000/public/open-source/mod_lisp/mod_lisp2.c'>mod_lisp2.c</a></li>
  326. <li>apache 2 windows binary -
  327. <a href='http://www.fractalconcept.com:8000/public/open-source/mod_lisp/windows/mod_lisp2.zip'>mod_lisp2.zip</a></li>
  328. </ul>
  329. <p>As stated in the intro, if you want to use ucw on a windows machine you're on your own. I have got no experience or information.</p>
  330. <p>If you went for the c module on a unix clone, use the command.</p>
  331. <pre>
  332. apxs -i -c mod_lisp.c
  333. </pre>
  334. <p>or</p>
  335. <pre>
  336. apxs2 -i -c mod_lisp2.c
  337. </pre>
  338. <p>for respectively apache 1 or 2. This will install the module in the appropriate apache directory. Debian users using apt-get should get one
  339. of the apache dev versions to get apxs(2) installed. Then add the following lines to 'httpd.conf' or other relevant configure file in your
  340. apache configuration directory for both apache 1 and 2. Just be sure to change mod_lisp.so to mod_lisp2.so for apache 2.</p>
  341. <pre>
  342. LoadModule lisp_module /path/to/modules/directory/mod_lisp.so
  343. </pre>
  344. <pre>
  345. LispServer 127.0.0.1 3001 ucw
  346. </pre>
  347. <pre>
  348. &lt;LocationMatch "/path/.*\.ucw"&gt;
  349. SetHandler lisp-handler
  350. &lt;/LocationMatch&gt;
  351. </pre>
  352. <p>This means that ucw INTERNALLY talks to apache on port 3001 at the internet address 127.0.0.1 (so in this case your
  353. localhost). The locationmatch part redirects all traffic from (in this case) 127.0.0.1 with prefix "/path/" and files ending
  354. on .ucw to ucw. So http://127.0.0.1/path/something.ucw as well as
  355. http://127.0.0.1/path/anotherpath/somethingelse.ucw will be redirected, but not http://127.0.0.1/somethingfaulty.ucw or
  356. http://127.0.0.1/path/somethingfaulty.html .</p>
  357. <h5>allegroserve or portableaserve</h5>
  358. <p>Should you want to use the aserve backend you will need to download
  359. and install either the AllegroServe if you use acl or portableaserve for any other. AllegroServe doesn't seem to have an
  360. asdf file, you're going to have to load it manually or however AllegroServe handles it's own files. Portableaserve does however.</p>
  361. <p>AllegroServe can be downloaded from here (it may be included in
  362. your version of acl): <a href='http://opensource.franz.com/aserve/'>http://opensource.franz.com/aserve/</a></p>
  363. <p>portableaserve is hosted on sourceforge: <a href='http://portableaserve.sf.net'>http://portableaserve.sf.net</a></p>
  364. <p>portableaserve download: <a href='http://constantly.at/lisp/aserve.tar.gz'>http://constantly.at/lisp/aserve.tar.gz</a></p>
  365. <p>To use portableaserve you'll also need the Allegro Common Lisp compatibility package (acl-compat). It's part of
  366. portableaserve and so it's home is also the before-mentioned sourceforge site.</p>
  367. <p>acl-compat download: <a href='http://constantly.at/lisp/acl-compat.tar.gz'>http://constantly.at/lisp/acl-compat.tar.gz</a></p>
  368. <h5>araneida</h5>
  369. <p>Should you want to use the araneida backend you will need to download araneida. Get the latest version just to be on the
  370. safe side. Originally araneida was meant to live behind apache and it can of course still be configured as
  371. such. Explaining this is beyond the scope of this document but have a look at this
  372. <a href='http://www.accela.net/~dankna/guide.html'>site</a> for more info.</p>
  373. <p>info: <a href='http://www.cliki.net/Araneida'>http://www.cliki.net/Araneida</a>}</p>
  374. <p>download: <a href='http://common-lisp.net/project/araneida/release/araneida-latest.tar.gz'>http://common-lisp.net/project/araneida/release/araneida-latest.tar.gz</a></p>
  375. <p>or use darcs, although the connection seems a bit slow:</p>
  376. <pre>
  377. darcs get http://verisons.telent.net/araneida/
  378. </pre>
  379. <h5>httpd</h5>
  380. <p>Ucw's in-house server. It's a simple server bundled with ucw. Nice for testing.</p>
  381. <p><span id='asdf'></span></p>
  382. <h3>asdf</h3>
  383. <p>To download it or read up on it go to <a href='http://cliki.net/ASDF'>http://cliki.net/ASDF</a></p>
  384. <p>Asdf makes sure common lisp packages and the files in those packages get loaded in the correct order. I would
  385. suggest you read the manual at
  386. <a href='http://constantly.at/lisp/asdf/'>http://constantly.at/lisp/asdf/</a>. Really the first
  387. <a href='http://constantly.at/lisp/asdf/Using-asdf-to-load-systems.html#Using%20asdf%20to%20load%20system'>link</a>
  388. is all you need to know right now.</p>
  389. <p>Basically every lisp package you downloaded so far has defined an .asd file. Usually in the root of the directory. This
  390. file has to appear in the search path of asdf, which is a list of directories defined by the special variable
  391. asdf:*central-registry*. The directories are typically called "systems". Under a unix clone, make a symbolic link to a systems dir
  392. as described in the document or as shown below. If a package defines
  393. more than one .asd file, just shove the whole dir on the *central-registry*, again as described in the document or as shown below.</p>
  394. <p>For example: on some linux installations the directory /usr/share/common-lisp/systems is in the list of asdf:*central-registry*.
  395. Now create a symlink from a particular .asd file to
  396. /usr/share/common-lisp/systems :</p>
  397. <pre>
  398. ln -s /path/to/library/lib.asd /usr/share/common-lisp/systems
  399. </pre>
  400. <p>To shove a whole directory on the *central-registry* do the following in your lisp startup file or in the repl:</p>
  401. <pre>
  402. (push #P"/path/to/asd/files/" asdf:*central-registry*)
  403. </pre>
  404. <p>All the required packages need to be recognized by asdf if you don't want to load every file by yourself.</p>
  405. <p><span id='extra'></span></p>
  406. <h2>Add-ons</h2>
  407. <p>Ucw also provides some packages which are kept out of the core so as not to bloat the program. Well two to be exact: the ucw presentations package and the ucw forms package.</p>
  408. <h5>presentations</h5>
  409. <p>An advanced CRUD interface for UCW.</p>
  410. <pre>
  411. darcs get http://common-lisp.net/project/ucw/repos/ucw-presentations
  412. </pre>
  413. <h5>forms</h5>
  414. <p>A more advanced HTML form toolkit for ucw than the one that is used in the core package, uses yaclml and dojo.</p>
  415. <pre>
  416. darcs get http://common-lisp.net/project/repos/ucw-forms
  417. </pre>
  418. <p><span id='testing'></span></p>
  419. <h2>Testing/Quickstart (for the non-boxset way)</h2>
  420. <p>When you have set up all your dependencies correctly, you can test ucw by first creating the directory /etc/ucw/applications.d, firing up your favorite distribution and:</p>
  421. <pre>
  422. (load "/path/to/ucw/etc/start.lisp")
  423. </pre>
  424. <p>If all went well, you have started ucw with the httpd backend. Surf to
  425. <a href='http://127.0.0.1:8080'>http://127.0.0.1:8080</a> and again if all went well you should see the example page. That's it! Start hacking!!</p>
  426. <p><span id='configure'></span></p>
  427. <h2>Configuration</h2>
  428. <p>At the moment the methods to configure and start ucw are a bit under development. But things seem to be stabling out. The elegant production compliant way of starting ucw is by launching ucwctl, found in /path/to/ucw/bin/ucwctl. This will start your lisp as a deamon. To let ucw find the proper configuration files, copy the files under /path/to/ucw/etc/ to either /your/home/.ucw or /etc/ucw.</p>
  429. <p>Ucwctl depends on cl-launch, to which a number of ucwtl's configure options are passed. It provides a suite of launch options to invoke lisp from the command-line. Be sure to put a link to cl-launch somewhere in your application search path. For general cl-launch understanding, read the cl-launch documentation.</p>
  430. <p>It's of course convenient to put ucwctl in the *nix executable search path but contrary to cl-launch it is not mandatory. Here's the configuration part of the ucwctl help output; -a, -c, -l, -k, -s and -t are passed to cl-launch:</p>
  431. <pre>
  432. -a, --asdf-root DIRECTORY Register asdf search DIRECTORY
  433. -c, --config-file FILE Read FILE as config file.
  434. -h, --help Display this help and exit.
  435. -k, --stop-file FILE Use FILE as stop file.
  436. -l, --lisp NAME Use NAME (without PATH) as Common Lisp
  437. implementation.
  438. --log-root DIRECTORY Save the logs in DIRECTORY, overriding the
  439. --var-root option.
  440. --run-root DIRECTORY Created pid/socket in DIRECTORY, overriding the
  441. --var-root option.
  442. -s, --start-file FILE Use FILE as start file.
  443. -t, --timeout SECONDS Set timeout in SECONDS when trying to stop a
  444. a running session.
  445. -u, --ucwctl-file FILE Read FILE as the ucwctl.conf file.
  446. --var-root DIRECTORY Save the logs in DIRECTORU/log/ucw and create
  447. pid/socket in DIRECTORY/run/ucw, if the two
  448. options --log-root and --run-root are not set.
  449. </pre>
  450. <p>In /path/to/configdir/ucwctl.conf default values are provided except for the lisp implementation and the .asd directory. So at the least you'd want to change them to point to the proper lisp and dir, or just specify those on the commandline. If you want to specify different paths for --log-root and --run-root in your config file, add LOGROOT=/path/to/log-root and RUNROOT=/path/to/run-root, leaving VARROOT empty. If you run ucwctl as user and didn't change ucwctl or supplied different paths for log-root and run-root (which default to paths under /var) on the commandline, they will default to paths under /your/home/dir/var. You can also specify a different ucwctl.conf file instead of /path/to/config-dir.</p>
  451. <p>To be clear this is the hierarchy of where ucwctl will pick its configuration from. Higher up the list will be chosen over lower on the list:</p>
  452. <p>1) command line options
  453. <br>
  454. 2) -u|--ucwctl-file (if specified, exit if it cannot be read)
  455. <br>
  456. 3) ~/.ucw/ucwctl.conf (if it exists)
  457. <br>
  458. 4) /etc/ucw/ucwctl.conf (if it exists)</p>
  459. <p>A deeper discussion is available at:</p>
  460. <p>http://common-lisp.net/pipermail/bese-devel/2006-April/001932.html
  461. <br>
  462. http://common-lisp.net/pipermail/bese-devel/2006-April/001961.html
  463. <br>
  464. </p>
  465. <p>Now you can start ucw by invoking:</p>
  466. <pre>
  467. ucwctl start
  468. </pre>
  469. <p>Without having configured anything (in /path/to/conf.lisp) this will start ucw with the built-in httpd server, just as with cl-launch. But
  470. now you have log files and more importantly you are not tied to a particular console. Point your browser at
  471. <a href='http://127.0.0.1:8080/'>http://127.0.0.1:8080/</a> and hope for the best. Hook up slime through port 4005 if you also actually want to code something.</p>
  472. <p>To stop ucw type:</p>
  473. <pre>
  474. ucwctl stop
  475. </pre>
  476. <p>To attach to a running ucw server type:</p>
  477. <pre>
  478. ucwctl attach
  479. </pre>
  480. <p>This calls attachtty, installed alongside detachtty, and passes attachy the socket, the path of which is defined in the ucwctl startup script. De-attach attachtty by giving it a sighup signal, eg by closing your terminal window or by pressing ctl-\. Note that you should be a bit careful when you attach to a socket and you start typing away at the repl. By default cl-launch will terminate the running process when the debugger is invoked. This behavior is changeable; check the cl-launch script (or not, someone on the mailing-list pointed out a bug).</p>
  481. <p>To test if ucw works with your chosen backend open /path/to/conf.lisp (to be found in /etc/ucw/conf.lisp if you copied it from
  482. /path/to/ucw_dev/bin/etc/) and change:</p>
  483. <pre>
  484. (setf *ucw-backend-type* ':httpd)
  485. (setf *ucw-backend-host* "127.0.0.1")
  486. (setf *ucw-backend-port* 8080)
  487. </pre>
  488. <p>to:</p>
  489. <pre>
  490. (setf *ucw-backend-type* ':mod-lisp)
  491. (setf *ucw-backend-host* "127.0.0.1")
  492. (setf *ucw-backend-port* 3001)
  493. </pre>
  494. <p>or to:</p>
  495. <pre>
  496. (setf *ucw-backend-type* ':araneida)
  497. (setf *ucw-backend-host* "127.0.0.1")
  498. (setf *ucw-backend-port* 8080)
  499. </pre>
  500. <p>or to:</p>
  501. <pre>
  502. (setf *ucw-backend-type* ':aserve)
  503. (setf *ucw-backend-host* "127.0.0.1")
  504. (setf *ucw-backend-port* 8080)
  505. </pre>
  506. <p>Repeat your chosen startup procedure for ucwctl with th note that if you use mod_lisp you have
  507. to point your browser at
  508. <a href='http://127.0.0.1/index.ucw'>http://127.0.0.1/path/you/specified/in/apache/this/link/goes/to/the/root/index.ucw</a>, without
  509. the 8080 (defaults to the server root here).</p>
  510. <p>note also that the default conf.lisp configuration defaults to the configuration in /path/to/ucw_dev/src/default.lisp which is the default
  511. configuration ;-) So if you don't change anything in conf.lisp you might just as well omit it. </p>
  512. <p>The variables in conf.lisp that we didn't cover yet are:</p>
  513. <pre>
  514. (setf *ucw-swank-port* 4005)
  515. </pre>
  516. <p>- used to connect to emacs, et al.</p>
  517. <pre>
  518. (setf *ucw-server-class* 'standard-server)
  519. </pre>
  520. <p>- leave as is. I'm not even sure if there is a non-standard server we should be interested in.</p>
  521. <pre>
  522. (setf *ucw-inspector* t)
  523. </pre>
  524. <p>- let's you inspect ucw inside the html pages you made when set to t. Seeing is believing. Set to nil to see the page as normal.</p>
  525. <pre>
  526. (setf *ucw-debugger* t)
  527. </pre>
  528. <p>- sends debugging html to the client when set to t. Seeing is believing. Set to nil to not send debugging info to the client and to invoke the debugger in your editor.</p>
  529. <pre>
  530. (setf *ucw-log-level* '+INFO+)
  531. </pre>
  532. <p>- Sets the log-level threshold for the information that will be logged by the base ucw logger and which will be pumped to the ucw.log
  533. file. these are the log levels to choose from, together with their value:</p>
  534. <p>+dribble+ = 0
  535. <br>
  536. +debug+ = 1
  537. <br>
  538. +info+ = 2
  539. <br>
  540. +warn+ = 3
  541. <br>
  542. +error+ = 4
  543. <br>
  544. +fatal+ = 5</p>
  545. <p>So in our example debug info and dribble will not be logged to ucw.log.</p>
  546. <pre>
  547. (setf *ucw-applications-directory* "/etc/ucw/applications.d/")
  548. </pre>
  549. <p>- sets the applications directory, see next chapter</p>
  550. <pre>
  551. (setf *ucw-systems* '(:ucw.admin :ucw.examples))
  552. (setf *ucw-applications* '(it.bese.ucw::*admin-application*
  553. it.bese.ucw-user::*example-application*))
  554. </pre>
  555. <p>- supply ucw applications to load. See next chapter.</p>
  556. <p><span id='environment'></span></p>
  557. <h2>Setting up the environment (and a hello world on the side)</h2>
  558. <p>Note that this procedure is not strict necessary, you could just fiddle around in ucw-user, but you will want to have
  559. your own proper environment sooner or later. To get the best of both worlds (being lazy and having a proper set up
  560. environment), just download the <a href='ucw-intro_source.tar'>code</a> we're going to create below (mod_lisp
  561. users, check the www-dir stuff below for a correct setup). For the less lazy, create a directory where you want
  562. to keep your application code. (halfway ripped from the cliki tutorial. thanks ;-)).</p>
  563. <p>Create an asdf file called ucw-intro.asd will contain:</p>
  564. <pre>
  565. (defpackage :ucw.intro.system
  566. (:use :cl :asdf))
  567. </pre>
  568. <pre>
  569. (in-package :ucw.intro.system)
  570. </pre>
  571. <pre>
  572. (defsystem ucw-intro
  573. :version "0.0.0.0.1"
  574. :depends-on (:ucw)
  575. :author "a lonely clown"
  576. :components ((:file "packages")
  577. (:file "config" :depends-on ("packages"))
  578. (:file "hello-world" :depends-on ("config"))))
  579. </pre>
  580. <p>and a package file called packages.lisp:</p>
  581. <pre>
  582. (in-package :cl-user)
  583. </pre>
  584. <pre>
  585. (defpackage :ucw-intro
  586. (:use :common-lisp
  587. :it.bese.ucw
  588. :it.bese.arnesi
  589. :it.bese.yaclml))
  590. </pre>
  591. <p>make a symlink from your asd file to the applications.d dir you defined in the last chapter.</p>
  592. <p>Important: when ucw loads it checks this directory for .asd files of your ucw applications. To let them load
  593. correctly you have to synchronize four names in your applications with standard pre- and suffixes:
  594. <ul>
  595. <li>the name of your applications asd file: name.asd (in this case ucw-intro.asd)</li>
  596. <li>the name of your applications package: :name (in this case :ucw-intro)</li>
  597. <li>the name of your application: *name-application* (in this case *ucw-intro-application*, see below in the ucw-intro.lisp code)</li>
  598. <li>the asdf system name of your package as defined with defsystem: :name (in this case :ucw-intro)</li>
  599. </ul>
  600. </p>
  601. <p>This procedure might be streamlined in the future, but for now we have to deal with it.</p>
  602. <p>There is also an alternative way of loading your applications when loading ucw. In /etc/ucw/conf.lisp (or where-ever you decided
  603. to put the file), push the name of your applications asd system name on *ucw-systems* and push it's application name (see below in the
  604. ucw-intro.lisp code), on *ucw-applications* like it's done for the ucws example applications:</p>
  605. <pre>
  606. (defvar *ucw-systems* '(:ucw.admin :ucw.examples))
  607. (defvar *ucw-applications* '(it.bese.ucw::*admin-application*
  608. it.bese.ucw-user::*example-application*))
  609. </pre>
  610. <p>If you don't want them to load, take them away from both conf.lisp and /path/to/ucw_dev/src/default.lisp.</p>
  611. <p>Just loading the three files we define(d) in this chapter while ucw is running will also register them correctly, no matter how we name the
  612. before-mentioned names.</p>
  613. <p>We also need a www root directory. This is the directory where we store static files for the http server to see: css and
  614. javascript files, pictures and the like. Lisp servers handle the www directory a bit different than mod_lisp so we have
  615. to make apt provisions. Lisp servers can themselves map a path from an incoming uri to the underlying directories on a
  616. server. When we use mod_lisp we have to tell apache as well as lisp where to go.</p>
  617. <p>When you use a lisp server backend, just create a directory in the tutorial root and call it www if you
  618. want to be in sync with this tutorial. With mod_lisp make a link from a directory somewhere in the apache www tree and in range of
  619. the mod_lisp search path as explained in the installation section. With apache 2 a typical path would be
  620. /var/www/locahost/htdocs/. The apache 1 www root normally also lies somewhere within that vicinity.</p>
  621. <pre>
  622. ln -s /path/to/ucw-intro/www var/www/localhost/htdocs/ucw-intro
  623. </pre>
  624. <p>Or link the other way around. </p>
  625. <p>Now we create two new file in our example application root called ucw-intro.lisp and config.lisp. config.lisp:</p>
  626. <pre>
  627. (in-package :ucw-intro)
  628. </pre>
  629. <pre>
  630. (defvar *www-root*
  631. (merge-pathnames
  632. (make-pathname :directory '(:relative "www"))
  633. (asdf:component-pathname (asdf:find-system :ucw-intro))))
  634. </pre>
  635. <pre>
  636. (defparameter *ucw-intro-application*
  637. (make-instance 'cookie-session-application
  638. :url-prefix "/ucw-intro/"
  639. :www-roots (list *www-root*)
  640. :dispatchers (list (make-instance 'ucw::action-dispatcher)
  641. ;; hello world
  642. (url-dispatcher "hello-world.ucw"
  643. (call 'hello-world)))
  644. :debug-on-error t))
  645. </pre>
  646. <p>hello-world.lisp:</p>
  647. <pre>
  648. (in-package :ucw-intro)
  649. </pre>
  650. <pre>
  651. (defcomponent hello-world (simple-window-component) ()
  652. (:default-initargs :title "hi"
  653. :stylesheet '("stylesheet.css" "stylesheet2.css")
  654. :content-type "text/html; charset=utf-8;"
  655. :javascript '((:src "dojo.js")
  656. (:js (dojo.require "dojo.event.*"))
  657. (:script "var foo = 3;")))
  658. ;; (:entry-point "hello-world.ucw" (:application *ucw-intro-application* :class url-dispatcher))
  659. (:render () (&lt;:as-html "hello world")))
  660. </pre>
  661. <p>Load the files into your image and surf to http://127.0.0.1(:8080)/ucw-intro/hello-world.ucw, cross your fingers... and... now you've printed "hello world"! (If the heavens are willing).</p>
  662. <p>In the next chapter we will see what applications actually are, and we will examine the contents of ucw-intro.lisp. Also we will discuss
  663. the mechanics of ucw. Actually the next chapter is the most important chapter of this intro. Finally the foreplay is
  664. over.</p>
  665. <p><span id='mechanics'></span></p>
  666. <h2>Basic ucw mechanics</h2>
  667. <p>In the course of this chapter we will take a flight through website-making history. We begin with traditional website-making
  668. techniques and we will quickly work our way up. In the process you
  669. can't help but be introduced to the basic building blocks of a ucw program: components, actions, entry-points, applications and
  670. render methods. <a href='ucw-intro_source.tar'>Ready made source</a> is available.</p>
  671. <h4>Components, render methods, applications and entry points</h4>
  672. <h5>Components</h5>
  673. <p>Component have more than one role. First they act as your
  674. basic storage unit. They are classes and you can define them in the same way, but they have added
  675. functionality given through meta object protocol modifications. To explain these modifications we need some background
  676. on the inner workings of ucw: When ucw receives a http request it checks if the request is a part of user session
  677. already in progress. If not it creates a new one. Such a session is made up of frames. Every new request makes a new
  678. frame which is referenced by a random string. Every frame copies the values of relevant components and their slots from
  679. the frame before, except of course when the values of a given class have changed. If a user wants to go back to a
  680. previous page, the appropriate frame is looked up with the help of the identifier string (be it through get or a cookie),
  681. and the original values are restored. So frames are the memory of a ucw session. Some of the modifications made to
  682. components facilitate this process of getting and setting values in frames under the cover.</p>
  683. <p>Components are also clothes-hangers for html output. You generate html by defining render methods on them. In the case of
  684. our example the method renders (as you say) the simple-window-component hello-world, which is a pre-defined component to create an empty
  685. canvas. You can nest render methods of other components, in which case you piece the data together to form a complete page. With this
  686. information we can step through conf.lisp and hello-world.lisp from the last chapter:</p>
  687. <p>config.lisp:</p>
  688. <pre>
  689. (in-package :ucw-intro)
  690. </pre>
  691. <pre>
  692. (defvar *www-root*
  693. (merge-pathnames
  694. (make-pathname :directory '(:relative "www"))
  695. (asdf:component-pathname (asdf:find-system :ucw-intro))))
  696. </pre>
  697. <pre>
  698. (defparameter *ucw-intro-application*
  699. (make-instance 'cookie-session-application
  700. :url-prefix "/ucw-intro/"
  701. :www-roots (list *www-root*)
  702. :dispatchers (list (make-instance 'ucw::action-dispatcher)
  703. ;; hello world
  704. (url-dispatcher "hello-world.ucw"
  705. (call 'hello-world)))
  706. :debug-on-error t))
  707. </pre>
  708. <pre>
  709. (in-package :ucw-intro)
  710. </pre>
  711. <p>hello-world.lisp:</p>
  712. <pre>
  713. (defcomponent hello-world (simple-window-component) ()
  714. (:default-initargs :title "hi"
  715. :stylesheet '("stylesheet.css" "stylesheet2.css")
  716. :content-type "text/html; charset=utf-8;"
  717. :javascript '((:src "dojo.js")
  718. (:js (dojo.require "dojo.event.*"))
  719. (:script "var foo = 3;")))
  720. ;; (:entry-point "hello-world.ucw" (:application *ucw-intro-application* :class url-dispatcher))
  721. (:render () (&lt;:as-html "hello world")))
  722. </pre>
  723. <h5>Applications</h5>
  724. <p>First we define the filesystem directory which is going to function as www-root for static data such as images, style-sheets and
  725. the like. We feed it to the definition of our
  726. first application object. An application is an arbitrary conceptual construct with which you define a number of
  727. options for a block of web-pages/site-logic. It lets you specify if you want to use cookies, what charset you want to use,
  728. etc. A quick tour of the chosen options: In this instance we want to use cookies, which means that ucw starts searching
  729. for certain cookie information after it has looked for information in other places. The url
  730. prefix is the browser path relative to the server root. Www-roots is a list of pathnames the application searches to get
  731. to static data relative to the the APPLICATION root. They are set relative to the
  732. url-prefix, eg in this example from the outside the www-root of ucw-intro is 127.0.0.1/ucw-intro/. Debug-on-error will or will not throw you in the debugger when things go wrong in this application, depending on if it is set to t or nil. The dispatchers we will cover later on.</p>
  733. <h5>defcomponent and render methods</h5>
  734. <p>The simple-window-component class and the defmethod macro that defines it can together be seen as as a convenience layer which
  735. constructs the underlying building blocks a standard application wants to have. In this section you will learn the
  736. semantics of both and you will learn how to define the building blocks without them.</p>
  737. <p>A simple-window-component sets up your basic html layout. You can feed a title, stylesheets, content-types, and
  738. different ways to insert javascript to :default-initargs. All of them accept a list as well as a
  739. basic unit suitable for the keyword, although you probably don't want to pass a list to the title argument as that will just print a quoted
  740. list. You can specify one or more javascript source files with the :src key, using :script lets you insert javascript as
  741. is and :js lets you insert javascript in parenscript syntax. With this information it sets up a whole page, except for
  742. the body. That's left for the render method.</p>
  743. <p>Defcomponent defines components almost the same as defclass defines classes. :default-initargs, slots, etc... are simply passed
  744. to the underlying defclass. But it has some extra options. You can supply a default backtrack function with :default-backtrack, you can supply a render method with :render, you can supply an entry-point with
  745. :entry-point and you can supply an action with :action. More on those last two in the next section, and more on :default-backtrack in a future chapter.</p>
  746. <p>As stated before, a render method is a regular method that specializes on a given component to output html. It is called when the program
  747. decides when it's time to put together a page to show the user. More on program flow in the next section of this chapter. The
  748. defcomponent macro passes the arguments from the :render form to a defmethod and let's it specialize on the name given
  749. to defcomponent. If no name is given the name default

Large files files are truncated, but you can click here to view the full file