Yesod 0.2 Mini Tutorial

Well, I'll be flying home in a few days after a long trip to see family. As such, this will probably be my last time to do some Yesod work for a week, so I wanted to give a little status update.

There are two major changes coming with Yesod 0.2: Hamlet and web-routes-quasi. The former is going to be the preferred templating system for Yesod, replacing both HStringTemplate and the Data.Object.Html module. It has already been released and is fairly well documented.

The latter is a reworking of the former routing system for Yesod, split out and designed to work with web-routes. It features a simpler syntax, support for subsites, and (most importantly) delivers the ability to create type-safe URLs. It is not yet released, though there is a web-routes-quasi documentation page; that page may be a little out of date.

I'm very interested in hearing community feedback on Yesod at this point. I know most people will wait to try things out seriously when the documentation is written, but for now I thought I'd write a mini-tutorial on how things fit together.

Hello World

1 {-# LANGUAGE TypeFamilies, QuasiQuotes, TemplateHaskell #-}
2 import Yesod
3 data HelloWorld = HelloWorld
4 mkYesod "HelloWorld" [$parseRoutes|/ Home GET|]
5 instance Yesod HelloWorld where approot _ = ""
6 getHome = return $ RepPlain $ cs "Hello World!"
7 main = toWaiApp HelloWorld >>= basicHandler 3000

Line 1 shows you what language extensions Yesod requires, and line 2 imports the framework. Line 3 declares the HelloWorld datatype; every Yesod application has such a datatype which is the core of the application. In our simple HelloWorld, we don't need any information in it, but usually you store settings loaded from config files, database connections and the like in it.

Line 4 is magic: the end of the line is a piece of quasiquotes which creates a list of Resources. This is a feature provided by web-routes-quasi; see its documentation for syntax information. mkYesod is template haskell that does a number of things for us:

• Creates a datatype for the URLs in our application. For our example, this is equivalent to data HelloWorldRoutes = Home
• Creates an instance of YesodSite; this provided URL parse and render functions as well as a dispatch function. The dispatch function references the getHome function, which is why we define it on line 6.

Line 5 is a minimalistic instance of the Yesod typeclass; all applications must instantiate it. You can set various settings in it, but the only one necessary is approot. Line 6 defines the handler for the GET method of the application root. cs converts the string "Hello World!" into Content; RepPlain specifies that the content type is "text/plain".

And finally, line 7 creates a WAI Application and uses the basicHandler to serve the application via either simple server or CGI, based on environment variables.

Beyond Hello World

I'll just point out a few of the possibly surprising things in Yesod; everything will be covered more thoroughly in the upcoming documentation.

• You can provide multiple representations of a response, and allow Yesod to choose the right one based on the HTTP "Accept" request header. This allows you to easily create applications with either an AJAX or static interface.
• clientsession is used for handling session data.
• There is built in support for OpenID and RPXnow authentication, but not internal site authentication. Hopefully, that will be added soon.
• The current development version depends on a few packages not yet released, but which are all available in my github account. Obviously those will all be uploaded before release.

I might update this post with a few more points later, but I'm out of time for now! See you all in a week.

Update (April 25, 2010)

I've gotten all of the dependencies for Yesod uploaded onto Hackage, so all it should take to try it out is:

• cabal update
• git clone git://github.com/snoyberg/yesod.git
• cd yesod
• git checkout origin/ver0.2
• cabal install