Web Routes Demo

Let's start by looking at a simple example of using web-routes. In this example we will use blaze for the html templates.

In order to run this demo you will need to install web-routes, web-routes-th and web-routes-happstack from hackage.

First we need to define the type to represent our routes. In this site we will have a homepage and articles which can be retrieved by their id.

Next we use template-haskell to derive an instance of PathInfo for the Sitemap type.

The PathInfo class looks like this:

It is basically a class that describes how to turn a type into a url and back. This class is semi-optional. Some conversion methods such as web-routes-th and web-routes-regular use it, but others do not.

Since ArticleId is just a newtype we were able to just do deriving PathInfo instead of having to call derivePathInfo.

Next we need a function that maps a route to the handlers:

As you can see, mapping a url to a handler is just a straight-forward case statement. We do not need to do anything fancy here to extract the article id from the url, becuse that has already been done when the url was converted to a Sitemap value.

You may be tempted to write the route function like this instead of using the case statement:

But, I don't recommend it. In a real application, the route function will likely take a number of extra arguments such as database handles. Sometimes those extra arguments are only used by some of the handlers. But every time you add a parameter, you have to update every pattern match to account for the extra argument. Using a case statement instead makes the code easier to maintain and more readable in my opinion.

The other thing you will notice is the RouteT monad transformer in the type signature. The RouteT monad transformer is another semi-optional feature of web-routes. RouteT is basically a Reader monad that holds the function which converts the url type into a string. At first, this seems unnecessary -- why not just call toPathInfo directly and skip RouteT entirely? But it turns out there are few advantages that RouteT brings:

1. RouteT is parametrized by the url type -- in this case Sitemap. That will prevent us from accidentally trying to convert an ArticleId into a url. An ArticleId is a valid component of some urls, but it is not a valid URL by itself.
2. The url showing function inside RouteT can also contain additional information needed to form a valid url, such as the hostname name, port, and path prefix
3. RouteT is also used when we want to embed a library/sub-site into a larger site.

We will see examples of these benefits as we continue with the tutorial.

Next, we have the handler functions:

Even though we have the RouteT in the type signature -- these functions look normal ServerPartT functions -- we do not have to use lift or anything else. That is because RouteT is a instance of all the Happstack classes such as ServerMonad, FilterMonad, etc. Though you do need to make sure you have imported Web.Routes.Happstack to get those instances.

The only new thing here is the showURL function, which has the type:

showURL converts a url type, such as Sitemap into a url String that we can use an href, src, etc attribute.

URL m is a type-function that calculates the url type based on the monad we are currently in. For RouteT url m a, URL m is going to be whatever url is. In this example, url is Sitemap. If you are not familiar with type families and type functions, see this section.

Now we have:

1. A url type, Sitemap
2. functions to convert the type to a string and back via PathInfo
3. a function to route the url to a handler, route

We need to tie these three pieces together. That is what the Site type does for us:

Looking at the type for Site, we notice that it is very general -- it does not have any references to Happstack, PathInfo, URLParser, RouteT, etc. That is because those are all addons to the core of web-routes. We can convert our route to a Site using some simple helper functions like this:

runRouteT removes the RouteT wrapper from our routing function:

So if we have our routing function like:

runRouteT will convert it to a function that takes a url showing function:

Since we created a PathInfo instance for Sitemap we can use mkSitePI to convert the new function to a Site. mkSitePI has the type:

so applying it to runRouteT route gives us:

setDefault allows you to map / to any route you want. In this example we map / to Home.

Next we use implSite to embed the Site into a normal Happstack route:

The type for implSite is straight-forward:

The first argument is the domain/port/etc that you want to add to the beginning of any URLs you show. The first argument is not used during the decoding/routing process -- it is merely prepended to any generated url strings.

The second argument is the path to this handler. This path is automatically used when routing the incoming request and when showing the URL. This path can be used to ensure that all routes generated by web-routes are unique because they will be in a separate sub-directory (aka, a separate namespace). If you do not want to put the routes in a separate sub-directory you can set this field to "".

The third argument is the Site that does the routing.

If the URL decoding fails, then implSite will call mzero.

Sometimes you will want to know the exact parse error that caused the router to fail. You can get the error by using implSite_ instead. Here is an alternative main that prints the route error to stdout.

[Source code for the app is here.]

Web Routes + Type Families

showURL has the type:

If you are not familiar with type families and type functions, the URL m in that type signature might look a bit funny. But it is really very simple.

The showURL function leverages the ShowURL class:

And here is the RouteT instance for ShowURL:

Here URL is a type function that is applied to a type and gives us another type. For example, writing URL (RouteT Sitemap (ServerPartT IO)) gives us the type Sitemap. We can use the type function any place we would normally use a type.

In our example we had:

So there, showURL is going to have the type:

which can be simplified to:

So, we see that the url type we pass to showURL is dictated by the monad we are currently in. This ensures that we only call showURL on values of the right type.

While ShowURL is generally used with the RouteT type -- it is not actually a requirement. You can implement ShowURL for any monad of your choosing.