Topics for Ring book

43 views
Skip to first unread message

Brian Marick

unread,
Dec 1, 2010, 11:17:39 AM12/1/10
to ring-c...@googlegroups.com
I've signed up with the Pragmatic Bookshelf to do a book on Ring. It'll be a short (target 70 pp) ebook so that it can be kept up to date. (It'll also be available as print-on-demand.)

My tentative target audience is someone who knows Clojure well enough to have written some sort of substantial program, doesn't know Ring at all, doesn't know the Ring-equivalents in Ruby or Python, has written a webapp (even if only a trivial one before) but didn't necessarily do it in Java (so the only knowledge of servlets etc. I'll assume is the knowledge they exist).

Is that a good audience?

In keeping with the other books I've done for the Prags, it'll be pretty hands-on, with lots of "Try This Yourself" sections.

What topics would you like to see me cover?

-----
Brian Marick, Artisanal Labrador
Contract programming in Ruby and Clojure
Author of /Programming Cocoa with Ruby/
www.exampler.com, www.exampler.com/blog, www.twitter.com/marick

Constantine Vetoshev

unread,
Dec 1, 2010, 12:02:21 PM12/1/10
to ring-c...@googlegroups.com
On Wed, Dec 1, 2010 at 11:17 AM, Brian Marick <mar...@exampler.com> wrote:
> Is that a good audience?

It seems likely that web programmers disappointed with mainstream
languages will drift to Clojure over time. They will probably want to
try writing a web app first, and getting started isn't that easy right
now (although the available tools are quite good, they require
understanding). It just seems to me that the number of Ruby+Python
programmers curious about Clojure exceeds the number of experienced
Clojure programmers who have a hard time with Ring and servlets.

> What topics would you like to see me cover?

1. Interactive development in the REPL is, in my opinion, an
absolutely essential topic. It might be asking too much for a short
book to cover all the interactive-capable environments, though.

2. Middleware is an obvious one. Can't live without it.

3. I'd like to see a discussion of the tradeoffs between Lisp-syntax
server-side templates, and limiting server interaction to REST-style
services. It seems to me that Clojure is pretty unique in being great
for both.

4. (Shameless plug:) You should, of course, talk about
appengine-magic, the easiest way to get a Ring webapp in production.
:)

Timothy Licata

unread,
Dec 1, 2010, 11:47:43 AM12/1/10
to ring-c...@googlegroups.com
Just last night I was wishing there was a book on Ring. I would like
to read something that tells me what Ring is. And where do the
boundaries exist between Ring and libraries that use it, like
Compojure. I guess I'm a little fuzzy on what exactly I'd want in a
book... but that's why I'd like to read one :)

On Wed, Dec 1, 2010 at 11:17 AM, Brian Marick <mar...@exampler.com> wrote:

Brenton

unread,
Dec 1, 2010, 1:29:03 PM12/1/10
to Ring
Brian,

I am looking forward to this and am glad that you are taking the time
to do it.

I have been using Ring to build web apps for about a year now and have
learned much from my mistakes.

The main thing lacking right now is documentation. Not just technical
documentation but something which describes the philosophy of Ring and
helps users to know how to go with that philosophy and not against it.
Ring is simple and it is very easy to shape it into any form that you
like. People coming from other environments will need to resist the
temptation to transform Ring into what they are used to. The
simplicity is good, go with it.

The first step is to give readers a good feel for how simple Ring is
at its core. Next go over all of the middlewares included with Ring
with special focus on sessions (this is often a topic of confusion)
and session backing stores. At this point people will begin to see the
power of middleware as they realize that many of the features of Ring
are themselves just middleware. It is also enlightening to review this
mailing list and see how many times James was able to answer a
difficult question with a simple middleware example. You may also want
to cover some of the other interesting middleware that exists outside
of Ring.

The next most confusing and important topic to understand is routing.
I know this is not part of Ring itself, but it is very important for
any real application. What tends to happen is that people (and by
people I mean me) jump in and start using Compojure without
understanding the simple idea that you are just composing functions
into a single handler. It would great to have a whole chapter on
routing where you start with a basic Ring handler that does it's own
routing. Then you add clout to make it simpler. Next you use Compojure
to make if even simpler. Then maybe backup and do the same thing with
moustache. Finally show an example of how how routes can be composed.
For large applications it is important to understand that you don't
have to define all your routes in one place. Each component can have
it's own set of routes which may be composed at some later time. I
think we will start to see many libraries for Ring in the future that
will make use of this. The library will provide some functionality
which may be used by plugging in its routes.

That is all I can think of right now.

Brenton

Vagif Verdi

unread,
Dec 1, 2010, 9:14:35 PM12/1/10
to Ring
Skim over Compojure group and this group.
Practically any popular (discussed) question would be a good candidate
for a chapter.
Some examples:
- Deploying wars on Tomcat.
- Common scenarios for middleware (logging, authentication, sesions)
- SSL
- templates (StringTemplate), hiccup

BTW i am buying your book as soon as it's avail.

On Dec 1, 8:17 am, Brian Marick <mar...@exampler.com> wrote:

Michael Ossareh

unread,
Dec 2, 2010, 4:14:02 PM12/2/10
to ring-c...@googlegroups.com
2. Middleware is an obvious one. Can't live without it.

+1 

Particularly make clear the relationship between middleware and the request / response flow. It took me a while to grok that.

Happy to proof read, I am a little above your intended target audience - but not so far away that it sounds like 101 stuff.

James Reeves

unread,
Dec 3, 2010, 2:24:42 PM12/3/10
to ring-c...@googlegroups.com
On 1 December 2010 16:17, Brian Marick <mar...@exampler.com> wrote:
> I've signed up with the Pragmatic Bookshelf to do a book on Ring. It'll be a short (target 70 pp) ebook so that it can be kept up to date. (It'll also be available as print-on-demand.)

This is something I'll definitely look forward to! Documentation is
currently one of Ring's weak points.

> My tentative target audience is someone who knows Clojure well enough to have written some sort of substantial program, doesn't know Ring at all, doesn't know the Ring-equivalents in Ruby or Python, has written a webapp (even if only a trivial one before) but didn't necessarily do it in Java (so the only knowledge of servlets etc. I'll assume is the knowledge they exist).
>
> Is that a good audience?

That tends to be the audience I assume when I'm writing documentation.
Other books provide a good introduction to Clojure, and it's
reasonable to assume that most developers writing a web application in
Clojure will have had some past experience.

> What topics would you like to see me cover?

As other people have said, it might be a good idea to start with an
overview of how Ring is structured. An explanation of how handlers and
middleware work is probably a necessary foundation.

Coverage of the standard Ring middleware might also be useful. People
frequently ask questions about session handling on the Compojure and
Ring mailing lists. Perhaps some 3rd-party Ring libraries like sandbar
could also get a mention.

Testing Ring is something I've been thinking about a lot recently, so
perhaps a chapter on how to unit-test Ring handlers? (Shameless plug:
I'm currently writing ring-mock, a library for generating mock request
maps for tests).

It might also be worth showing people how they'd go about creating
their own middleware. For example, maybe some middleware to add a
standard template, or some middleware to translate response bodies to
JSON. Custom middleware tends to be used a lot more in Ring than in
Rack, I've found.

- James

Brian Marick

unread,
Dec 3, 2010, 3:06:55 PM12/3/10
to ring-c...@googlegroups.com

On Dec 3, 2010, at 1:24 PM, James Reeves wrote:

> Testing Ring is something I've been thinking about a lot recently, so
> perhaps a chapter on how to unit-test Ring handlers? (Shameless plug:
> I'm currently writing ring-mock, a library for generating mock request
> maps for tests).


I'm thinking of documenting existing middleware with Midje "facts".
(Midje is test framework. https://github.com/marick/Midje/blob/master/README.md)
Your ring-mock would fit in nicely. I have it flagged to check out.

-----
Brian Marick, independent consultant
Mostly on agile methods with a testing slant

jamieorc

unread,
Dec 6, 2010, 2:12:26 PM12/6/10
to Ring
The first thing I want answered when I open up your eBook is, "Why
should I use Ring?" In other words, I want compelling reasons given
for using it over higher level frameworks like Compojure and Conjure.
What are compelling use cases?

Jamie

James Reeves

unread,
Dec 6, 2010, 9:12:57 PM12/6/10
to ring-c...@googlegroups.com
Compojure is built on top of Ring, so in order to use Compojure effectively, you really need a sound understanding of Ring.

An explanation of where Ring sits in a typical Clojure web application stack might be a useful addition to the book.

- James

angelm

unread,
Dec 6, 2010, 11:26:49 PM12/6/10
to Ring
I would love to see this book on pragprog.

For newer web applications that I'm implementing, I'm trying as much
as possible to use static pages with an ajax library (Dojo, JQuery,
Sproutcore,...) using the web server as a simple REST API. My sense is
that the web is moving in that direction (slowly though).

I think Ring is a prime candidate for this type of app, so I would
like to see it covered.

Good Luck!

Sandeep

unread,
Dec 8, 2010, 1:31:36 AM12/8/10
to Ring
Three requests:
1. Please accompany it with sample code.
2. Please make sure the example is usable - maybe something that talks
to a database, does authentication and SSL. The database part is
something very important, because I dont see any examples of clojure
webapps talking to mysql or postgresql. There are a lot of existing
examples on AppEngine though.
3. Deployment - how to do something lightweight (e.g. nginx fronting
jetty) and how to create a WAR for app-server deployment

Currently, IMHO the canonical example of clojure web development is
the cow-blog (https://github.com/briancarper/cow-blog). It would be
really great if you could come up with something better.

Sandeep

unread,
Dec 8, 2010, 11:53:19 PM12/8/10
to Ring
Please include relational database interaction (via clojureql or
something) and authentication/SSL in your book. I find that too much
of the clojure webapp related material is around the AppEngine or uses
no database at all.

Nicolas Buduroi

unread,
Dec 9, 2010, 1:02:40 PM12/9/10
to Ring
For the db interaction, I'm not sure that's a good idea, this book
seems to be focused on Ring and very small. I doubt there will be
enough space to include that kind of example. Database interaction in
Clojure isn't as mature as Ring/Compojure currently, I think we've got
to wait some more time before things settle down.

ClojureQL is a big step in the right direction, but only include the
query part of database interaction now. There's some other solutions
available data definition, but no definitive one I think. Maybe I'll
find the time to salvage some of the DDL generating code from the
original CQL codebase this winter, but for now I'm happy working on
GAE! ;-)

For now you can look at Brian Carper cow-blog for a practical example
of the web app using SQL:

https://github.com/briancarper/cow-blog/blob/master/src/blog/db.clj

It's using Oyako, which is a work in progress, but good enough for a
blog application:

https://github.com/briancarper/oyako

James Reeves

unread,
Dec 9, 2010, 7:41:29 PM12/9/10
to ring-c...@googlegroups.com
On 9 December 2010 18:02, Nicolas Buduroi <nbud...@gmail.com> wrote:
> For the db interaction, I'm not sure that's a good idea, this book
> seems to be focused on Ring and very small. I doubt there will be
> enough space to include that kind of example.

I'm inclined to agree. This book seems intended to be about Ring
specifically, rather than the more general topic of how to write
Clojure web applications.

- James

Nils Wloka

unread,
Dec 10, 2010, 7:01:52 AM12/10/10
to Ring
Hello Brian,

great to see someone doing this. Some topics I'd be interested in
reading about:

- Structure of web-application written in Clojure
This is not strictly about Ring, but many of us come from a Java
background and know common architectural pattern for webapps like MVC.
Something similar for webapps with Clojure would be helpful.

- Deployment scenarios
Standalone, deployment as WAR, deployment within a cloud platform,
starting a swank server within a deployed web application, etc.

- Sessions and cookies

- Routing
Brenton mentioned this and I agree. This is confusing and explaining
some patterns would help.

- Libraries designed for use with Ring
Just a quick overview (compojure, moustache, sandbar, etc.)

Regards,

Nils

Shantanu Kumar

unread,
Dec 10, 2010, 10:34:37 PM12/10/10
to Ring
Another important topic (maybe under the "Advanced" section) would be
how to use Ring with newer HTTP server-backend with asynchronous I/O
support, such as Aleph/Netty and ZeroMQ. Supplementary/comparative
discussion on Node.js for a background may also be useful. Consider
including details with examples/DOs/DON'Ts etc.; not just an
introductory chapter.

Regards,
Shantanu
Reply all
Reply to author
Forward
0 new messages