Yesod.Handler

Type families

class YesodSubRoute s y where

Methods

fromSubRoute :: s -> y -> Route s -> Route y

Handler monad

data GHandler sub master a

A generic handler monad, which can have a different subsite and master site. We define a newtype for better error message.

Instances

MonadBase IO (GHandler sub master)

MonadBaseControl IO (GHandler sub master)

MonadLift (ResourceT IO) (GHandler sub master)

Monad (GHandler sub master)

Functor (GHandler sub master)

Applicative (GHandler sub master)

MonadUnsafeIO (GHandler sub master)

MonadThrow (GHandler sub master)

MonadResource (GHandler sub master)

MonadIO (GHandler sub master)

MonadLift (GHandler sub master) (GWidget sub master)

~ * master master' => SubsiteGetter (master -> sub) (GHandler anySub master') sub

(~ * anySub anySub', ~ * master master') => SubsiteGetter (GHandler anySub master sub) (GHandler anySub' master') sub

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 -> Text)

Get the URL rendering function.

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

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.

getRequest :: GHandler s m Request

waiRequest :: GHandler sub master Request

Get the request's Request value.

runRequestBody :: GHandler s m RequestBodyContents

Special responses

Redirecting

class RedirectUrl master a where

Some value which can be turned into a URL for redirects.

Methods

toTextUrl :: a -> GHandler sub master Text

Converts the value to the URL and a list of query-string parameters.

Instances

RedirectUrl master String

RedirectUrl master Text

RedirectUrl master (Route master)

(~ * key Text, ~ * val Text) => RedirectUrl master (Route master, [(key, val)])

redirect :: RedirectUrl master url => url -> GHandler sub master a

Redirect to the given route. HTTP status code 303 for HTTP 1.1 clients and 302 for HTTP 1.0 This is the appropriate choice for a get-following-post technique, which should be the usual use case.

If you want direct control of the final status code, or need a different status code, please use redirectWith.

redirectWith :: RedirectUrl master url => Status -> url -> GHandler sub master a

Redirect to the given URL with the specified status code.

redirectToPost :: RedirectUrl master url => url -> GHandler sub master a

Redirect to a POST resource.

This is not technically a redirect; instead, it returns an HTML page with a POST form, and some Javascript to automatically submit the form. This can be useful when you need to post a plain link somewhere that needs to cause changes on the server.

Errors

notFound :: GHandler sub master a

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

badMethod :: GHandler sub master a

Return a 405 method not supported page.

permissionDenied :: Text -> GHandler sub master a

Return a 403 permission denied page.

permissionDeniedI :: RenderMessage master msg => msg -> GHandler sub master a

Return a 403 permission denied page.

invalidArgs :: [Text] -> GHandler sub master a

Return a 400 invalid arguments page.

invalidArgsI :: RenderMessage y msg => [msg] -> GHandler s y 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.

sendFilePart

Arguments

:: ContentType

-> FilePath

-> Integer

offset

-> Integer

count

-> GHandler sub master a

Same as sendFile, but only sends part of a file.

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

Bypass remaining handler code and output the given content with a 200 status code.

sendResponseStatus :: HasReps c => Status -> c -> GHandler s m a

Bypass remaining handler code and output the given content with the given status code.

sendResponseCreated :: Route m -> GHandler s m a

Send a 201 Created response with the given route as the Location response header.

sendWaiResponse :: Response -> GHandler s m b

Send a Response. Please note: this function is rarely necessary, and will disregard any changes to response headers and session that you have already specified. This function short-circuits. It should be considered only for very specific needs. If you are not sure if you need it, you don't.

Setting headers

setCookie :: SetCookie -> GHandler sub master ()

Set the cookie on the client.

getExpires

Arguments

:: Int

minutes

-> IO UTCTime

Helper function for setCookieExpires value

deleteCookie

Arguments

:: Text

key

-> Text

path

-> GHandler sub master ()

Unset the cookie on the client.

Note: although the value used for key and path is Text, you should only use ASCII values to be HTTP compliant.

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

Set an arbitrary response header.

Note that, while the data type used here is Text, you must provide only ASCII value to be HTTP compliant.

setLanguage :: Text -> GHandler sub master ()

Set the language in the user session. Will show up in languages on the next request.

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

type SessionMap = Map Text ByteString

lookupSession :: Text -> GHandler s m (Maybe Text)

Lookup for session data.

lookupSessionBS :: Text -> GHandler s m (Maybe ByteString)

Lookup for session data in binary format.

getSession :: GHandler sub master SessionMap

Get all session variables.

setSession

Arguments

:: Text

key

-> Text

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.

setSessionBS :: Text -> ByteString -> GHandler sub master ()

Same as setSession, but uses binary data for the value.

deleteSession :: Text -> GHandler sub master ()

Unsets a session variable. See setSession.

Ultimate destination

setUltDest :: RedirectUrl master url => url -> 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.

setUltDestCurrent :: 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.

setUltDestReferer :: GHandler sub master ()

Sets the ultimate destination to the referer request header, if present.

This function will not overwrite an existing ultdest.

redirectUltDest

Arguments

:: RedirectUrl master url

=> url

default destination if nothing in session

-> GHandler sub master a

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

The ultimate destination is set with setUltDest.

This function uses redirect, and thus will perform a temporary redirect to a GET request.

clearUltDest :: GHandler sub master ()

Remove a previously set ultimate destination. See setUltDest.

Messages

setMessage :: Html -> GHandler sub master ()

Sets a message in the user's session.

See getMessage.

setMessageI :: RenderMessage y msg => msg -> GHandler sub y ()

Sets a message in the user's session.

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.

Helpers for specific content

Hamlet

hamletToContent :: HtmlUrl (Route master) -> GHandler sub master Content

Converts the given Hamlet template into Content, which can be used in a Yesod Response.

hamletToRepHtml :: HtmlUrl (Route master) -> GHandler sub master RepHtml

Wraps the Content generated by hamletToContent in a RepHtml.

Misc

newIdent :: GHandler sub master Text

Get a unique identifier.

Lifting

class MonadLift base m | m -> base where

The standard MonadTrans class only allows lifting for monad transformers. While GHandler and GWidget should allow lifting, their types do not express that they actually are transformers. This replacement class accounts for this.

Methods

lift :: base a -> m a

Instances

(Monad m, MonadTrans t) => MonadLift m (t m)

MonadLift (ResourceT IO) (GHandler sub master)

MonadLift (GHandler sub master) (GWidget sub master)

i18n

getMessageRender :: RenderMessage master message => GHandler s master (message -> Text)

Per-request caching

data CacheKey a

mkCacheKey :: Q Exp

Generate a new CacheKey. Be sure to give a full type signature.

cacheLookup :: CacheKey a -> GHandler sub master (Maybe a)

cacheInsert :: CacheKey a -> a -> GHandler sub master ()

cacheDelete :: CacheKey a -> GHandler sub master ()

Internal Yesod

runHandler :: HasReps c => GHandler sub master c -> (Route master -> [(Text, Text)] -> Text) -> Maybe (Route sub) -> (Route sub -> Route 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] -> SessionMap -> ResourceT IO YesodAppResult

runSubsiteGetter :: SubsiteGetter g m s => g -> m s

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

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

toMasterHandlerDyn :: (Route sub -> Route master) -> GHandler sub' master sub -> Route sub -> GHandler sub master a -> GHandler sub' master a

FIXME do we need this?

toMasterHandlerMaybe :: (Route sub -> Route master) -> (master -> sub) -> Maybe (Route sub) -> GHandler sub master a -> GHandler sub' master a

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

data HandlerData sub master

data ErrorResponse

Responses to indicate some form of an error occurred. These are different from SpecialResponse in that they allow for custom error pages.

Constructors

NotFound

InternalError Text

InvalidArgs [Text]

PermissionDenied Text

BadMethod Method

Instances

Eq ErrorResponse

Show ErrorResponse

Typeable ErrorResponse

Exception ErrorResponse

data YesodAppResult

Constructors

YARWai Response

YARPlain Status [Header] ContentType Content SessionMap

handlerToYAR

Arguments

:: (HasReps a, HasReps b)

=> master

master site foundation

-> sub

sub site foundation

-> (Route sub -> Route master)

-> (Route master -> [(Text, Text)] -> Text)

-> (ErrorResponse -> GHandler sub master a)

-> Request

-> Maybe (Route sub)

-> SessionMap

-> GHandler sub master b

-> ResourceT IO YesodAppResult

yarToResponse :: YesodAppResult -> [(CI Ascii, Ascii)] -> Response

headerToPair :: Header -> (CI Ascii, Ascii)

Convert Header to a key/value pair.