Compojure 0.4.0 released

[James Reeves]

Hi folks,

Compojure 0.4.0 has (finally) been released.

It's more or less the same as 0.4.0-RC3, but I updated the Ring
dependency to 0.2.3, and I sneakily added response type handling for
ISeq and InputStream.

- James

[Brian Carper]

On Jun 23, 1:19 pm, James Reeves <weavejes...@googlemail.com> wrote:
> Hi folks,
>
> Compojure 0.4.0 has (finally) been released.

Congrats! It's a fine piece of work. Thanks for your efforts.

Is there work underway to provide more complete documentation for
Compojure? I may soon have some time to help in that area, if you're
interested.

--Brian

[James Reeves]

On 24 June 2010 02:16, Brian Carper <brian...@gmail.com> wrote:
> Is there work underway to provide more complete documentation for
> Compojure?  I may soon have some time to help in that area, if you're
> interested.

The documentation for Compojure itself is fairly complete already, but
that's because Compojure has factored out most of its functionality to
Ring. Documentation on things like Ring sessions would be useful.

To that end, I've been considering setting up a site for Clojure web
development, which would start by covering the basic ideas of Ring,
and then discuss how to use Ring in conjunction with libraries like
Compojure or Moustache, how to generate HTML with Hiccup or Enlive,
and so forth. I was thinking something similar in style to the Git
Community Book [http://book.git-scm.com/].

Does this sound like a good idea to you?

- James

[Keith Lancaster]

+1

> --
> You received this message because you are subscribed to the Google Groups "Compojure" group.
> To post to this group, send email to comp...@googlegroups.com.
> To unsubscribe from this group, send email to compojure+...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/compojure?hl=en.
>

Keith Lancaster
klancas...@acm.org

[Anders Rune Jensen]

More documentation would be very welcome :-)

--
Anders Rune Jensen

[Brian Carper]

On Jun 24, 6:01 am, James Reeves <jree...@weavejester.com> wrote:
> To that end, I've been considering setting up a site for Clojure web
> development, which would start by covering the basic ideas of Ring,
> and then discuss how to use Ring in conjunction with libraries like
> Compojure or Moustache, how to generate HTML with Hiccup or Enlive,
> and so forth. I was thinking something similar in style to the Git
> Community Book [http://book.git-scm.com/].
>
> Does this sound like a good idea to you?

Yes, this sounds great. The Compojure and Ring documentation often
assumes too high a level of knowledge, in my opinion. You dive right
into "Here's how to define a route", but what is a "route"? What is
"middleware"? What are the advantages of doing things this way?
Ring uses the word "app" a lot, what is that? If you haven't already
used another toolkit from another language, these things aren't going
to be clear at all. I had to read the source code for Compojure to
figure out what it does, in a lot of areas.

In http://wiki.github.com/weavejester/compojure/route-syntax, it says
to refer to Clojure's own destructuring docs, but Compojure's syntax
doesn't look much at all like Clojure's syntax. It might be nice to
show the equivalence explicitly:

(let [{:foo foo} request] ...)
=> (GET "/" [] {:foo foo} ...)

Even this won't make sense unless you know exactly how Ring works,
that your routes are dealing with a Ring request map that always has
certain standard keys. A note saying "Go read the Ring SPEC document
to see what keys are available, and keep in mind that more keys may be
added by middleware" would be helpful here.

The docs say:

> If the binding is a vector, the request parameters are
> bound to the symbols in the vector. If an & more form
> is used, the map of parameters that have not been bound
> to a symbol are bound to more.

Which parameters? POST? GET? Route?

A lot of examples are given like this:

(PUT "/user/:id" [id & updated-attrs]
(update-user id updated-attrs))

OK, so what does that do exactly? What is the value of updated-attrs
now? It'd be nice to spell it out explicitly. Or if I want to figure
out what it does myself, how do I inspect it? How do you debug a
Compojure app? I still don't really know if I'm doing it the best way
sometimes, to be honest. I println from my handlers, or have a route
return {:body (pr-str request)}, or I throw an exception with an
object I want to inspect and use stacktrace-dumping-to-HTML middleware
to look at it.

The examples for Ring and Compojure both are always at a "hello world"
level, which is OK, but I've seen a lot of people ask for more
complex / real-world examples. Examples of integrating with Hiccup or
Enlive would be excellent, as you mention, because a user is almost
certainly going to need one of those (or equivalent).

And then there's the "Now how do I deploy it?" issue, which would
benefit greatly from documentation.

If not for this group and for reading the source for most of Compojure
and Ring, personally I would still be in the dark about how a lot of
things work. I guess I prefer my documentation dumbed down a few
notches. A book-style document would be a great way to solve most or
all of this, so I think it's a great idea. Distributing the doc-
writing work to the community is also a good idea.

--Brian