Handler, Widget and YesodDB (for Persistent). As with most monads, each one provides some specific functionality: Handler gives access to the request and allows you to send responses, a Widget contains HTML, CSS, and Javascript, and YesodDB let's you make database queries. In Model-View-Controller (MVC) terms, we could consider YesodDB to be the model, Widget to be the view, and Handler to be the controller.
So far, we've presented some very straight-forward ways to use these monads: your main handler will run in Handler, using runDB to execute a YesodDB query, and defaultLayout to return a Widget, which in turn was created by calls to toWidget.
However, if we have a deeper understanding of these types, we can achieve some fancier results.
## Monad Transformers
Monads are like onions. Monads are *not* like cakes._Shrek, more or less_Before we get into the heart of Yesod's monads, we need to understand a bit about monad transformers. (If you already know all about monad transformers, you can likely skip this section.) Different monads provide different functionality:
Reader allows read-only access to some piece of data throughout a computation, Error allows you to short-circuit computations, and so on.
Often times, however, you would like to be able to combine a few of these features together. After all, why not have a computation with read-only access to some settings variable, that could error out at any time? One approach to this would be to write a new monad like ReaderError, but this has the obvious downside of exponential complexity: you'll need to write a new monad for every single possible combination.
Instead, we have monad transformers. In addition to Reader, we have ReaderT, which adds reader functionality to any other monad. So we could represent our ReaderError as (conceptually):
```haskell
type ReaderError = ReaderT Error
```
In order to access our settings variable, we can use the ask function. But what about short-circuiting a computation? We'd like to use throwError, but that won't exactly work. Instead, we need to lift our call into the next monad up. In other words:
```haskell
throwError :: errValue -> Error
lift . throwError :: errValue -> ReaderT Error
```
There are a few things you should pick up here:
* A transformer can be used to add functionality to an existing monad.
* A transformer must always wrap around an existing monad.
* The functionality available in a wrapped monad will be dependent not only on the monad transformer, but also on the inner monad that is being wrapped.
A great example of that last point is the IO monad. No matter how many layers of transformers you have around an IO, there's still an IO at the core, meaning you can perform I/O in any of these __monad transformer stacks__. You'll often see code that looks like liftIO
$ putStrLn "Hello There!".
## The Three Transformers
We've already discussed two of our transformers previously: Handler and Widget. Just to recap, there are two special things about these transformers:
1. In order to simplify error messages, they are not actual transformers. Instead, they are newtypes that hard-code their inner monads. This is why Yesod provides a specialized lift function, which works for Handler and Widget.
1. In reality they have extra type parameters for the sub and master site. As a result, the Yesod libraries provide GHandler sub master a and GWidget sub master
a, and each site gets a pair of type synonyms type Handler = GHandler MyApp
MyApp and type Widget = GWidget MyApp My App ().
In [persistent](http://hackage.haskell.org/package/persistent), we have a typeclass called PersistStore. This typeclass defines all of the primitive operations you can perform on a database, like get. This typeclass essentially looks like class (Monad (b m)) => PersistStore b m. b is the backend itself, and is in fact a monad transformer, while m is the inner monad that b wraps around. Both SQL and MongoDB have their own instances; in the case of SQL, it looks like:
```haskell
instance MonadBaseControl IO m => PersistBackend SqlPersist m
```
This means that you can run a SQL database with any underlying monad, so long as that underlying monad supports MonadBaseControl IO, which allows you to properly deal with exceptions in a monad stack. That basically means any transformer stack built around IO (besides exceptional cases like ContT). Fortunately for us, that includes both Handler and Widget. The takeaway here is that we can layer our Persistent transformer on top of Handler or Widget.
This wasn't always the case. Before Yesod 0.10, Yesod was built on top of enumerators, which do not support MonadBaseControl. In Yesod 0.10, we moved over to [conduit](http://hackage.haskell.org/package/conduit), which greatly simplified everything we're discussing here.
In order to make it simpler to refer to the relevant Persistent transformer, the [yesod-persistent](http://hackage.haskell.org/package/yesod-persistent) package defines the YesodPersistBackend associated type. For example, if I have a site called MyApp and it uses SQL, I would define something like type instance YesodPersistBackend MyApp =
SqlPersist.
When we want to run our database actions, we'll have a SqlPersist wrapped around a Handler or Widget. We can then use the standard Persistent unwrap functions (like runSqlPool) to run the action and get back a normal Handler/Widget. To automate this, we provide the runDB function. Putting it all together, we can now run database actions inside our handlers and widgets.
Most of the time in Yesod code, and especially thus far in this book, widgets have been treated as actionless containers that simply combine together HTML, CSS and Javascript. But if you look at that last paragraph again, you'll realize that's not the way things have to be. Since a widget is a transformer on top of a handler, anything you do in a handler can be done in a widget, including database actions. All you have to do is lift.
## Example: Database-driven navbar
Let's put some of this new knowledge into action. We want to create a Widget that generates its output based on the contents of the database. Previously, our approach would have been to load up the data in a Handler, and then pass that data into a Widget. Now, we'll do the loading of data in the Widget itself. This is a boon for modularity, as this Widget can be used in any Handler we want, without any need to pass in the database contents.
```haskell active web
{-# LANGUAGE OverloadedStrings, TypeFamilies, TemplateHaskell, FlexibleContexts,
QuasiQuotes, MultiParamTypeClasses, GADTs #-}
import Yesod
import Database.Persist.Sqlite
import Data.Text (Text)
import Data.Time
import Control.Monad.Logger (runStderrLoggingT)
share [mkPersist sqlSettings, mkMigrate "migrateAll"] [persist|
Link
title Text
url Text
added UTCTime
|]
data LinksExample = LinksExample ConnectionPool
mkYesod "LinksExample" [parseRoutes|
/ RootR GET
/add-link AddLinkR POST
|]
instance Yesod LinksExample
instance RenderMessage LinksExample FormMessage where
renderMessage _ _ = defaultFormMessage
instance YesodPersist LinksExample where
type YesodPersistBackend LinksExample = SqlPersist
runDB db = do
LinksExample pool <- getYesod
runSqlPool db pool
getRootR :: Handler RepHtml
getRootR = defaultLayout [whamlet|