Yesod.Handler

Type families

type family Route a

The type-safe URLs associated with a site argument.

Handler monad

data GHandler sub master a

A generic handler monad, which can have a different subsite and master site. This monad is a combination of ReaderT for basic arguments, a WriterT for headers and session, and an MEitherT monad for handling special responses. It is declared as a newtype to make compiler errors more readable.

Instances

Failure ErrorResponse (GHandler sub master)

Monad (GHandler sub master)

Functor (GHandler sub master)

Applicative (GHandler sub master)

MonadCatchIO (GHandler sub master)

MonadIO (GHandler sub master)

RequestReader (GHandler sub master)

Read information from handler

getYesod :: GHandler sub master master

Get the master site appliation argument.

getYesodSub :: GHandler sub master sub

Get the sub application argument.

getUrlRender :: GHandler sub master (Route master -> String)

Get the URL rendering function.

getUrlRenderParams :: GHandler sub master (Route master -> [(String, String)] -> String)

The URL rendering function with query-string parameters.

getCurrentRoute :: GHandler sub master (Maybe (Route sub))

Get the route requested by the user. If this is a 404 response- where the user requested an invalid route- this function will return Nothing.

getRouteToMaster :: GHandler sub master (Route sub -> Route master)

Get the function to promote a route for a subsite to a route for the master site.

Special responses

Redirecting

data RedirectType

Different types of redirects.

Constructors

RedirectPermanent

RedirectTemporary

RedirectSeeOther

Instances

Eq RedirectType

Show RedirectType

redirect :: RedirectType -> Route master -> GHandler sub master a

Redirect to the given route.

redirectParams :: RedirectType -> Route master -> [(String, String)] -> GHandler sub master a

Redirects to the given route with the associated query-string parameters.

redirectString :: RedirectType -> String -> GHandler sub master a

Redirect to the given URL.

Errors

notFound :: Failure ErrorResponse m => m a

Return a 404 not found page. Also denotes no handler available.

badMethod :: (RequestReader m, Failure ErrorResponse m) => m a

Return a 405 method not supported page.

permissionDenied :: Failure ErrorResponse m => String -> m a

Return a 403 permission denied page.

invalidArgs :: Failure ErrorResponse m => [String] -> m a

Return a 400 invalid arguments page.

Short-circuit responses.

sendFile :: ContentType -> FilePath -> GHandler sub master a

Bypass remaining handler code and output the given file.

For some backends, this is more efficient than reading in the file to memory, since they can optimize file sending via a system call to sendfile.

sendResponse :: HasReps c => c -> GHandler sub master a

Bypass remaining handler code and output the given content.

Setting headers

setCookie

Arguments

:: Int

minutes to timeout

-> String

key

-> String

value

-> GHandler sub master ()

Set the cookie on the client.

deleteCookie :: String -> GHandler sub master ()

Unset the cookie on the client.

setHeader :: String -> String -> GHandler sub master ()

Set an arbitrary response header.

setLanguage :: String -> GHandler sub master ()

Set the language in the user session. Will show up in languages.

Content caching and expiration

cacheSeconds :: Int -> GHandler s m ()

Set the Cache-Control header to indicate this response should be cached for the given number of seconds.

neverExpires :: GHandler s m ()

Set the Expires header to some date in 2037. In other words, this content is never (realistically) expired.

alreadyExpired :: GHandler s m ()

Set an Expires header in the past, meaning this content should not be cached.

expiresAt :: UTCTime -> GHandler s m ()

Set an Expires header to the given date.

Session

setSession

Arguments

:: String

key

-> String

value

-> GHandler sub master ()

Set a variable in the user's session.

The session is handled by the clientsession package: it sets an encrypted and hashed cookie on the client. This ensures that all data is secure and not tampered with.

deleteSession :: String -> GHandler sub master ()

Unsets a session variable. See setSession.

Ultimate destination

setUltDest :: Route master -> GHandler sub master ()

Sets the ultimate destination variable to the given route.

An ultimate destination is stored in the user session and can be loaded later by redirectUltDest.

setUltDestString :: String -> GHandler sub master ()

Same as setUltDest, but use the given string.

setUltDest' :: GHandler sub master ()

Same as setUltDest, but uses the current page.

If this is a 404 handler, there is no current page, and then this call does nothing.

redirectUltDest

Arguments

:: RedirectType

-> Route master

default destination if nothing in session

-> GHandler sub master ()

Redirect to the ultimate destination in the user's session. Clear the value from the session.

The ultimate destination is set with setUltDest.

Messages

setMessage :: Html -> GHandler sub master ()

Sets a message in the user's session.

The message set here will not be visible within the current request; instead, it will only appear in the next request.

See getMessage.

getMessage :: GHandler sub master (Maybe Html)

Gets the message in the user's session, if available, and then clears the variable.

See setMessage.

Internal Yesod

runHandler :: HasReps c => GHandler sub master c -> (Route master -> [(String, String)] -> String) -> Maybe (Route sub) -> (Route sub -> Route master) -> master -> (master -> sub) -> YesodApp

Function used internally by Yesod in the process of converting a GHandler into an Application. Should not be needed by users.

newtype YesodApp

An extension of the basic WAI Application datatype to provide extra features needed by Yesod. Users should never need to use this directly, as the GHandler monad and template haskell code should hide it away.

Constructors

YesodApp

Fields

unYesodApp :: (ErrorResponse -> YesodApp) -> Request -> [ContentType] -> IO (Status, [Header], ContentType, Content, [(String, String)])

toMasterHandler :: (Route sub -> Route master) -> (master -> sub) -> Route sub -> GHandler sub master a -> GHandler master master a

Used internally for promoting subsite handler functions to master site handler functions. Should not be needed by users.

localNoCurrent :: GHandler s m a -> GHandler s m a

finallyHandler :: GHandler s m a -> GHandler s m b -> GHandler s m a

A version of finally which works correctly with short-circuiting.