UnCommon Web Documentation
Let me make this clear from the beginning. Do not make the same mistake I made, which was to look for UCW documentation on the web. If you even happen to find any that doesn't 404, don't use it. The only up-to-date and relevant documentation for UCW is pretty much the source code and the getting-started.txt file included with the library. Above all, avoid the Trac site like the plague.
That being said, it's now obvious that if you are the type of person who will only learn a new language/framework/technology as long as there are instructions every step of the way, UCW isn't for you. But then again, the same applies to Lisp. Hopefully, this blog will help a few would-be web-lispers to take the plunge.
What is UnCommon Web?
Straight from the getting started file:
UCW is a multi-paradigm framework for building Web based applications in Common Lisp. It has an extensible core, the RERL, that enables many methods and styles of web development, and can operate using almost web server as a front end, including a few that come built in.
UCW includes a component oriented system allows both the graphical and the presentation logic to be easily reused and adapted, and has features that allow developers to write complex page flow as if it was a "regular" sequence of function calls.
UCW has been used to develop all kinds of web sites and applications just using the standard library (ucw-standard) but also serves as an excellent platform for developing higher-level frameworks, such as lisp-on-lines, ucw_ajax and core-server.
UCW is not a full-stack, all or nothing approach. UCW does not include form builders, Object/Relational mapping or any database support. UCW deals only with the web side of things, like dealing with HTTP requests, sessions, marshalling/unmarshalling of GET/POST variables and the like.
Users are encouraged to explore the higher-level ucw-based frameworks once a solid grounding in UCW concepts has been acheived.
I also recommend the features page from the UCW website.
Why UnCommon Web?
Not having used UCW yet, the question I am striving to answer is: Why is UnCommon Web the best web framework out there? For now I have faith that it actually is, but I need to get my hands dirty and experience why. I have some ideas in which UCW will help me come up with a solid and effective foundation for developing web apps. I see UCW the same way I see Lisp: powerful, expressive, and elegant.
One reason my interest in UCW is particularly piqued has a lot to do with Drew Crampsie's lisp-on-lines (aka lol), which is built on UCW and abstracts Pascal Costanza's CLOS extension for context-oriented programming, ContextL.
Homework—Light Reading
One thing not clearly expressed in the getting started doc (although it becomes apparent once you see the code snippets), is how heavily based on CLOS (Common Lisp Object System) it is. I'd go as far as saying that it pretty much seems like an extension to CLOS for the web. Moreover, it uses the CLOS Metaobject Protocol (MOP) for defining components.
That being said, I recommend the following light reading:
From Practical Common Lisp:
Object Reorientation: Generic Functions
Object Reorientation: Classes
From the Common Lisp Cookbook:
Fundamentals of CLOS
Additionally, if you're not familiar with the term or concept, you may want to read on what continuation-passing style (CPS) is, as UCW's control flow logic is implemented as a CPS interpreter (Common Lisp does not support native CPS).
Last but not least, if you would like to get a head start, you can go ahead and read the getting started doc which is included once you've downloaded the library. Following instructions in the next section, it will be located at /path/to/clbuild/source/ucw/doc/getting-started.txt. (Update: I recommend enabling org-mode for this file in Emacs. Since it is in outline format, it will be easier to follow.)
Installing UCW with Quicklisp
(Updated) You should use Quicklisp to install UCW and its dependencies. If you haven't installed it already, now would be a great time.
To download UCW and its dependencies once quicklisp is installed, run (ql:quickload "ucw" "puri" "rfc2388-binary") at the REPL and you should be good to go.
Starting the demo
Once you've installed UCW and all its dependencies, go ahead and launch SLIME in Emacs. Compile UCW and it's dependent packages, and enter the UCW package:
CL-USER> (require 'ucw) CL-USER> (in-package :ucw)
Then, load the demo and run it by typing the following:
UCW> (load "/path/to/clbuild/source/ucw/demo/demo.lisp") UCW> (startup-demo)
You should see something like this:
1:02 UCW INFO Spawned new worker thread # 01:02 UCW INFO Spawned new worker thread # 01:02 UCW INFO Started standard-server # with backend #
Note the last line, where the app has started on the localhost server on port 9090. To try it out, open a browser window and go to http://localhost:9090/demo/index.ucw.
Click around and enjoy! Take a look at the demo.lisp source code to see what's going on. However, there are two things from the demo code that caught my attention that I needed some clarification on. First, the usage of defcomponent over defclass (inconsistent with getting started doc). Thanks to unknown_lamer from #ucw, defcomponent is pretty much syntactic sugar for
(defclass ...
(:metaclass standard-component-class))
Second is that, being unfamiliar with CLOS, I wanted to find out why (defmethod render ((self ...)) ...) was being used so much. The answer was provided by drewc:
The reason you see SELF a lot in the UCW source code is historical more than anything, and I personally think it's bad style. In older versions of UCW, CALL was a macro that relied on a hidden lexical variable, SELF, that DEFACTION would set up. This meant that, unless you named the component SELF in the RENDER method definition, you couldn't do something like (<ucw:a :action (call ...)) in a RENDER method.
CALL has since been completely re-written, but my fingers tend to still type (defmethod render ((self ...))) automatically some times, and a lot of older source code still uses the convention. I'd love to eradicate parameters named SELF from the UCW code, but it's not a major priority.
In closing...
Well they're you have it. You should be ready to start playing around with UCW, and you should be able to follow along with my posts. For next time, we can start writing a hello world program.
If you find any problems while toying around with UCW, there is a #ucw channel on freenode. (Tip: You can ask a question and then idle in the chat until someone notices and gives an answer.)
Subscribe to my posterous blog with the link at the bottom of the page, or you should follow me on twitter here. Expect new blog posts every other week, if not sooner.
