Yesod

Retrieve the value associated with the given key of an Object. The result is empty if the key is not present or the value cannot be converted to the desired type.

This accessor is appropriate if the key and value must be present in an object for it to be valid. If the key and value are optional, use .:? instead.

Create a Value from a list of name/value Pairs. If duplicate keys arise, later keys and their associated values win.

Generates a function that takes a Text and logs a LevelDebug message. Usage:

$(logDebug) "This is a debug log message"

Generates a function that takes a LogSource and Text and logs a LevelDebug message. Usage:

$logDebugS "SomeSource" "This is a debug log message"

See logDebug

See logDebugS

See logDebug

See logDebugS

Generates a function that takes a Text and logs a LevelOther message. Usage:

$(logOther "My new level") "This is a log message"

Generates a function that takes a LogSource, a level name and a Text and logs a LevelOther message. Usage:

$logOtherS "SomeSource" "My new level" "This is a log message"

See logDebug

See logDebugS

Hamlet quasi-quoter. May only be used to generate expressions.

Generated expression have type HtmlUrl url, for some url.

data MyRoute = Home

render :: Render MyRoute
render Home _ = "/home"

>>> putStrLn (renderHtml ([hamlet|<a href=@{Home}>Home|] render))
<a href="/home">Home</a>

"Simple Hamlet" quasi-quoter. May only be used to generate expressions.

Generated expressions have type Html.

>>> putStrLn (Text.Blaze.Html.Renderer.renderHtml [shamlet|<div>Hello, world!|])
<div>Hello, world!</div>

Like hamlet, but produces XHTML.

render with route interpolation. If using this module standalone, apart from type-safe routes, a dummy renderer can be used:

renderJavascriptUrl (\_ _ -> undefined) javascriptUrl

When using Yesod, a renderer is generated for you, which can be accessed within the GHandler monad: getUrlRenderParams.

Default options for mkMessage are: * mmGenType = True * mmConPrefix = "Msg" * mmTypeSuffix = "Message" * mmUseRecordCons = True

generate translations from translation files

This function will:

1. look in the supplied subdirectory for files ending in .msg

2. generate a type based on the constructors found

3. create a RenderMessage instance

create RenderMessage instance for an existing data-type

used by mkMessage, mkMessageFor to generate a RenderMessage and possibly a message data type

create an additional set of translations for a type created by mkMessage

Set the prefix for the constructor names

Whether to generate a new datatype from the constructors found in the .msg files

Set the suffix for the datatype name

Set whether to use record constructors or normal constructors. If you are getting partial-fields warnings you want to remove, set this to False. If you want to use record syntax, set this to True.

Return the same URL if the user is authorized to see it.

Built on top of isAuthorized. This is useful for building page that only contain links to pages the user is allowed to see.

Return an Unauthorized value, with the given i18n message.

Gets the title of the current page and the hierarchy of parent pages, along with their respective titles.

Build a WAI Application that dispatches starting at a nested route fragment a (rather than the whole Route site), given a YesodRunnerEnv for the parent site and the parent route's ParentArgs. Handles cleanPath redirects and a terminal 404 just like toWaiAppYre.

Check if a given request is authorized via isAuthorized and isWriteRequest.

Since 1.2.0

Looks up the CSRF token from the request headers or POST parameters. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

For details, see the "AJAX CSRF protection" section of Yesod.Core.Handler.

Since 1.4.14

Takes a SetCookie and overrides its value with a CSRF token, then sets the cookie. See setCsrfCookieWithCookie.

For details, see the "AJAX CSRF protection" section of Yesod.Core.Handler.

Make sure to set the setCookiePath to the root path of your application, otherwise you'll generate a new CSRF token for every path of your app. If your app is run from from e.g. www.example.com/app1, use app1. The vast majority of sites will just use /.

Since 1.4.14

Customize the cookies used by the session backend. You may use this function on your definition of makeSessionBackend.

For example, you could set the cookie domain so that it would work across many subdomains:

makeSessionBackend site =
    (fmap . fmap) (customizeSessionCookies addDomain) ...
  where
    addDomain cookie = cookie { setCookieDomain = Just ".example.com" }

Default: Do not customize anything (id).

Calls csrfCheckMiddleware with isWriteRequest, defaultCsrfHeaderName, and defaultCsrfParamName as parameters.

Since 1.4.14

Calls defaultCsrfSetCookieMiddleware and defaultCsrfCheckMiddleware.

For details, see the "AJAX CSRF protection" section of Yesod.Core.Handler.

You can chain this middleware together with other middleware like so:

yesodMiddleware = defaultYesodMiddleware . defaultCsrfMiddleware

or:

yesodMiddleware app = defaultYesodMiddleware $ defaultCsrfMiddleware $ app

Since 1.4.14

Calls csrfSetCookieMiddleware with the defaultCsrfCookieName.

The cookie's path is set to /, making it valid for your whole website.

Since 1.4.14

The default error handler for errorHandler.

Default implementation of makeLogger. Sends to stdout and automatically flushes on each write.

Since 1.4.10

Default implementation of messageLoggerSource. Checks if the message should be logged using the provided function, and if so, formats using formatLogMessage. You can use defaultShouldLogIO as the provided function.

Since 1.4.10

Default implementation of shouldLog. Logs everything at or above LevelInfo.

Since 1.4.10

Default implementation of yesodMiddleware. Adds the response header "Vary: Accept, Accept-Language", "X-XSS-Protection: 1; mode=block", and performs authorization checks.

Since 1.2.0

Create a SessionBackend which reads the session key from the named environment variable.

This can be useful if:

1. You can't rely on a persistent file system (e.g. Heroku)

2. Your application is open source (e.g. you can't commit the key)

By keeping a consistent value in the environment variable, your users will have consistent sessions without relying on the file system.

Note: A suitable value should only be obtained in one of two ways:

1. Run this code without the variable set, a value will be generated and printed on devstdout/

2. Use clientsession-generate

Since 1.4.5

Default formatting for log messages. When you use the template haskell logging functions for to log with information about the source location, that information will be appended to the end of the log. When you use the non-TH logging functions, like logDebugN, this function does not include source information. This currently works by checking to see if the package name is the string "<unknown>". This is a hack, but it removes some of the visual clutter from non-TH logs.

Since 1.4.10

Get the textual application root from an Approot value.

Since 1.4.17

Guess the approot based on request headers. For more information, see Network.Wai.Middleware.Approot

In the case of headers being unavailable, it falls back to ApprootRelative

Since 1.4.16

Guess the approot based on request headers, with fall back to the specified AppRoot.

Since 1.4.16

Helps defend against CSRF attacks by setting the SameSite attribute on session cookies to Lax. With the Lax setting, the cookie will be sent with same-site requests, and with cross-site top-level navigations.

This option is liable to change in future versions of Yesod as the spec evolves. View more information here.

Apply a Strict-Transport-Security header with the specified timeout to all responses so that browsers will rewrite all http links to https until the timeout expires. For security, the max-age of the STS header should always equal or exceed the client sessions timeout. This defends against SSL-stripping man-in-the-middle attacks. It is only effective if a secure connection has already been made; Strict-Transport-Security headers are ignored over HTTP.

Since 1.4.7

Defends against session hijacking by setting the secure bit on session cookies so that browsers will not transmit them over http. With this setting on, it follows that the server will regard requests made over http as sessionless, because the session cookie will not be included in the request. Use this as part of a total security measure which also includes disabling HTTP traffic to the site or issuing redirects from HTTP urls, and composing sslOnlyMiddleware with the site's yesodMiddleware.

Since 1.4.7

Helps defend against CSRF attacks by setting the SameSite attribute on session cookies to Strict. With the Strict setting, the cookie will only be sent with same-site requests.

This option is liable to change in future versions of Yesod as the spec evolves. View more information here.

Convert a widget to a PageContent.

Give just the media types as a pair.

For example, "text/html; charset=utf-8" returns ("text", "html")

Zero-length enumerator.

Removes "extra" information at the end of a content type string. In particular, removes everything after the semicolon, if present.

For example, "text/html; charset=utf-8" is commonly used to specify the character encoding for HTML data. This function would return "text/html".

Generate a random number uniformly distributed in the full range of Int.

Note: Before 1.6.20, this generates pseudo-random number in an unspecified range. The range size may not be a power of 2. Since 1.6.20, this uses a secure entropy source and generates in the full range of Int.

All of the default middlewares, excluding logging.

Since 1.2.12

Default constructor for yreGetMaxExpires field. Low level function for simple manual construction of YesodRunnerEnv.

A default set of middlewares.

Since 1.2.0

Construct a YesodRunnerEnv for a site, initializing its logger, session backend, and other runtime state. This is the environment threaded through dispatch; toWaiAppPlain and friends build one for you, but it is exposed so callers can construct and reuse a runner environment directly.

Same as toWaiAppPlain, but provides a default set of middlewares. This set may change with future releases, but currently covers:

• Logging

• GZIP compression

• Automatic HEAD method handling

• Request method override with the _method query string parameter

• Accept header override with the _accept query string parameter

Convert the given argument into a WAI application, executable with any WAI handler. This function will provide no middlewares; if you want commonly used middlewares, please use toWaiApp.

Convert the given argument into a WAI application, executable with any WAI handler. This function will provide no middlewares; if you want commonly used middlewares, please use toWaiApp.

This function allows you to create an Application that only responds to a subset of the site routes. This is really only useful for writing tests, but it does allow you to write tests that only depend on a subset of the handlers instead of all handlers.

Pure low level function to construct WAI application. Usefull when you need not standard way to run your app, or want to embed it inside another app.

A convenience method to run an application using the Warp webserver on the specified port. Automatically calls toWaiApp. Provides a default set of middlewares. This set may change at any point without a breaking version number. Currently, it includes:

• Logging

• GZIP compression

• Automatic HEAD method handling

• Request method override with the _method query string parameter

• Accept header override with the _accept query string parameter

If you need more fine-grained control of middlewares, please use toWaiApp directly.

Since 1.2.0

Deprecated synonym for warp.

Runs your application using default middlewares (i.e., via toWaiApp). It reads port information from the PORT environment variable, as used by tools such as Keter and the FP Complete School of Haskell.

Note that the exact behavior of this function may be modified slightly over time to work correctly with external tools, without a change to the type signature.

Set attachment file name.

Allows Unicode characters by encoding to UTF-8. Some modurn browser parse UTF-8 characters with out encoding setting. But, for example IE9 can't parse UTF-8 characters. This function use RFC 6266(RFC 5987)

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.

Adds a status and message in the user's session.

See getMessages.

Adds a message in the user's session but uses RenderMessage to allow for i18n

See getMessages.

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

Return a 405 method not supported page.

Retrieves a value from the cache used by cachedBy.

Sets a value in the cache used by cachedBy.

Retrieves a value from the cache used by cached.

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

Sets a value in the cache used by cached.

Use a per-request cache to avoid performing the same action multiple times. Values are stored by their type, the result of typeOf from Typeable. Therefore, you should use different newtype wrappers at each cache site.

For example, yesod-auth uses an un-exported newtype, CachedMaybeAuth and exports functions that utilize it such as maybeAuth. This means that another module can create its own newtype wrapper to cache the same type from a different action without any cache conflicts.

See the original announcement: http://www.yesodweb.com/blog/2013/03/yesod-1-2-cleaner-internals

a per-request cache. just like cached. cached can only cache a single value per type. cachedBy stores multiple values per type by usage of a ByteString key

cached is ideal to cache an action that has only one value of a type, such as the session's current user cachedBy is required if the action has parameters and can return multiple values per type. You can turn those parameters into a ByteString cache key. For example, caching a lookup of a Link by a token where multiple token lookups might be performed.

Takes a header name to lookup a CSRF token. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

Checks that a valid CSRF token is present in either the request headers or POST parameters. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

Takes a POST parameter name to lookup a CSRF token. If the value doesn't match the token stored in the session, this function throws a PermissionDenied error.

Clear all session variables.

@since: 1.0.1

Remove a previously set ultimate destination. See setUltDest.

The default cookie name for the CSRF token ("XSRF-TOKEN").

The default header name for the CSRF token ("X-XSRF-TOKEN").

The default parameter name for the CSRF token ("_token")

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.

Unsets a session variable. See setSession.

Set an Expires header to the given date.

Stream the data from the file. Since Yesod 1.2, this has been generalized to work in any MonadResource.

Extract a strict ByteString body from a FileInfo.

This function will block while reading the file.

do
    fileByteString <- fileSourceByteString fileInfo

forkIO for a Handler (run an action in the background)

Uses handlerToIO, liftResourceT, and resourceForkIO for correctness and efficiency

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.

Helper function for setCookieExpires value

Gets just the last message in the user's session, discards the rest and the status

Gets all messages in the user's session, and then clears the variable.

See addMessage.

Get all the post parameters passed to the handler. To also get the submitted files (if any), you have to use runRequestBody instead of this function.

Get all session variables.

Get the URL rendering function.

The URL rendering function with query-string parameters.

Get the master site application argument.

Get a specific component of the master site application argument. Analogous to the gets function for operating on StateT.

Deprecated synonym for withUrlRenderer.

Wraps the Content generated by hamletToContent in a RepHtml.

Returns a function that runs HandlerFor actions inside IO.

Sometimes you want to run an inner HandlerFor action outside the control flow of an HTTP request (on the outer HandlerFor action). For example, you may want to spawn a new thread:

getFooR :: Handler RepHtml
getFooR = do
  runInnerHandler <- handlerToIO
  liftIO $ forkIO $ runInnerHandler $ do
    Code here runs inside HandlerFor but on a new thread.
    This is the inner HandlerFor.
    ...
  Code here runs inside the request's control flow.
  This is the outer HandlerFor.
  ...

Another use case for this function is creating a stream of server-sent events using HandlerFor actions (see yesod-eventsource).

Most of the environment from the outer HandlerFor is preserved on the inner HandlerFor, however:

• The request body is cleared (otherwise it would be very difficult to prevent huge memory leaks).

• The cache is cleared (see cached).

Changes to the response made inside the inner HandlerFor are ignored (e.g., session variables, cookies, response headers). This allows the inner HandlerFor to outlive the outer HandlerFor (e.g., on the forkIO example above, a response may be sent to the client without killing the new thread).

Takes a header name to lookup a CSRF token, and returns whether the value matches the token stored in the session.

Takes a POST parameter name to lookup a CSRF token, and returns whether the value matches the token stored in the session.

Return a 400 invalid arguments page.

Return a 400 invalid arguments page.

Get the list of supported languages supplied by the user.

Languages are determined based on the following (in descending order of preference):

• The _LANG get parameter.

• The _LANG user session variable.

• The _LANG cookie.

• Accept-Language HTTP header.

Yesod will seek the first language from the returned list matched with languages supporting by your application. This language will be used to render i18n templates. If a matching language is not found the default language will be used.

This is handled by parseWaiRequest (not exposed).

NOTE: Before version 1.6.19.0, this function prioritized the session variable above all other sources.

Lookup basic authentication data from Authorization header of request. Returns user name and password

Lookup bearer authentication datafrom Authorization header of request. Returns bearer token value

Lookup for cookie data.

Lookup for cookie data.

Lookup for POSTed files.

Lookup for POSTed files.

Lookup for GET parameters.

Lookup for GET parameters.

Lookup a request header.

Lookup a request header.

Lookup for POST parameters.

Lookup for session data.

Lookup for session data in binary format.

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

Get a unique identifier.

Return a 401 status code

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

Send a 304 not modified response immediately. This is a short-circuiting action.

Return a 403 permission denied page.

Return a 403 permission denied page.

Provide a single representation to be used, based on the request of the client. Should be used together with selectRep.

Same as provideRep, but instead of determining the content type from the type of the value itself, you provide the content type separately. This can be a convenience instead of creating newtype wrappers for uncommonly used content types.

provideRepType "application/x-special-format" "This is the content"

Stream in the raw request body without any parsing.

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.

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.

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.

Redirect to the given URL with the specified status code.

Replace an existing header with a new value or add a new header if not present.

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

Provide a pure value for the response body.

respond ct = return . TypedContent ct . toContent

Use a Source for the response body.

Note that, for ease of use, the underlying monad is a HandlerFor. This implies that you can run any HandlerFor action. However, since a streaming response occurs after the response headers have already been sent, some actions make no sense here. For example: short-circuit responses, setting headers, changing status codes, etc.

Select a representation to send to the client based on the representations provided inside this do-block. Should be used together with provideRep.

In a streaming response, send a single chunk of data. This function works on most datatypes, such as ByteString and Html.

Type-specialized version of sendChunk for strict ByteStrings.

Type-specialized version of sendChunk for Htmls.

Type-specialized version of sendChunk for lazy ByteStrings.

Type-specialized version of sendChunk for lazy Texts.

Type-specialized version of sendChunk for strict Texts.

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.

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

In a streaming response, send a flush command, causing all buffered data to be immediately sent to the client.

Send a raw response. This is used for cases such as WebSockets. Requires WAI 2.1 or later, and a web server which supports raw responses (e.g., Warp).

Send a raw response without conduit. This is used for cases such as WebSockets. Requires WAI 3.0 or later, and a web server which supports raw responses (e.g., Warp).

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

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

Bypass remaining handler code and output no content with a 204 status code.

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

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

Switch over to handling the current request with a WAI Application.

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.

Set the cookie on the client.

Sets a cookie with a CSRF token, using defaultCsrfCookieName for the cookie name.

The cookie's path is set to /, making it valid for your whole website.

Takes a SetCookie and overrides its value with a CSRF token, then sets the cookie.

Make sure to set the setCookiePath to the root path of your application, otherwise you'll generate a new CSRF token for every path of your app. If your app is run from from e.g. www.example.com/app1, use app1. The vast majority of sites will just use /.

Check the if-none-match header and, if it matches the given value, return a 304 not modified response. Otherwise, set the etag header to the given value.

Note that it is the responsibility of the caller to ensure that the provided value is a valid etag value, no sanity checking is performed by this function.

Deprecated synonym for addHeader.

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

Calls addMessage with an empty status

Calls addMessageI with an empty status

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.

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

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.

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.

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

This function will not overwrite an existing ultdest.

Check the if-none-match header and, if it matches the given value, return a 304 not modified response. Otherwise, set the etag header to the given value.

A weak etag is only expected to be semantically identical to the prior content, but doesn't have to be byte-for-byte identical. Therefore it can be useful for dynamically generated content that may be difficult to perform bytewise hashing upon.

Note that it is the responsibility of the caller to ensure that the provided value is a valid etag value, no sanity checking is performed by this function.

Get the request's Request value.

Provide a URL rendering function to the given function and return the result. Useful for processing Shakespearean templates.

Generate a YesodSubDispatchNested instance for a nested route within a subsite, for hand-written split-route modules (see the subsite-splitting recipe in docs/split-route-compilation.md).

Takes the resources as [ResourceTree String] — exactly the form the parseRoutes quasi-quoter produces — and parses them to Type internally via parseResourceTypes, so the caller never touches the partial parseType/dropBracket. A malformed type fails the splice with an attributed error instead.

Generates URL datatype and site function for the given Resources. This is used for creating sites, not subsites. See mkYesodSubData and mkYesodSubDispatch for the latter. Use parseRoutes to create the Resources.

Contexts and type variables in the name of the datatype are parsed. For example, a datatype App a with typeclass constraint MyClass a can be written as "(MyClass a) => App a".

Sometimes, you will want to declare your routes in one file and define your handlers elsewhere. For example, this is the only way to break up a monolithic file into smaller parts. Use this function, paired with mkYesodDispatch, to do just that.

mkYesodData but with custom options.

See mkYesodData.

See mkYesodDataOpts

mkYesod but with custom options.

Generate both YesodSubDispatch and YesodSubDispatchNested instances for a parameterized subsite. This is the subsite equivalent of using mkYesod for top-level sites.

Usage:

mkYesodSubDispatchInstance "(MyClass a) => MySub a" resourcesMySub

This generates:

1. A YesodSubDispatch instance using mkYesodSubDispatch

2. YesodSubDispatchNested instances for any nested route fragments

The generated instances quantify over the master site and constrain it only through the subsite's own class. For a parameterized subsite this normally means the subsite's class carries a subsite -> master functional dependency (so master is determined) and the using module enables UndecidableInstances (the instance contexts mention type-family applications and non-variable arguments), along with FlexibleContexts, FlexibleInstances, MultiParamTypeClasses and TypeFamilies. The nested route datatype must also declare exactly as many type parameters as the subsite has type arguments (see the arity note below).

Like mkYesodSubDispatchInstance, but takes a RouteOpts so a subsite can control nested-route generation — most usefully setNestedRouteFallthrough (which mkYesodSubDispatchInstance leaves at its default of False). The flag is threaded into both the yesodSubDispatch body (so the subsite's own top-level parent clauses fall through to later siblings on an inner miss) and the generated YesodSubDispatchNested fragment instances.

Similar to mkYesod, except contexts and type variables are not parsed. Instead, they are explicitly provided. You can write (MyClass a) => App a with mkYesodWith [["MyClass","a"]] "App" ["a"] ....

Format as per RFC 1123.

Format as per RFC 822.

Format a UTCTime in W3 format.

Returns True if the client prefers application/json as indicated by the Accept HTTP header.

Convert a list of values to an Array.

Given the Content-Type header, returns if it is JSON.

This function is currently a simple check for application/json, but in the future may check for alternative representations such as xxx/yyy+json.

Provide both an HTML and JSON representation for a piece of data, using the default layout for the HTML output (defaultLayout).

jsonEncodingOrRedirect simplifies the scenario where a POST handler sends a different response based on Accept headers:

1. 200 with JSON data if the client prefers application/json (e.g. AJAX, see acceptsJSON).

2. 3xx otherwise, following the PRG pattern. @since 1.4.21

jsonOrRedirect simplifies the scenario where a POST handler sends a different response based on Accept headers:

1. 200 with JSON data if the client prefers application/json (e.g. AJAX, see acceptsJSON).

2. 3xx otherwise, following the PRG pattern.

Wraps a data type in a RepJson. The data type must support conversion to JSON via ToJSON.

Parse the request body to a data type as a JSON value. The data type must support conversion from JSON via FromJSON. If you want the raw JSON value, just ask for a Result Value.

The MIME type must indicate JSON content. Requiring a JSON content-type helps secure your site against CSRF attacks (browsers will perform POST requests for form and text/plain content-types without doing a CORS check, and those content-types can easily contain valid JSON).

Note that this function will consume the request body. As such, calling it twice will result in a parse error on the second call, since the request body will no longer be available.

Same as parseCheckJsonBody, but does not check that the mime type indicates JSON content.

Note: This function is vulnerable to CSRF attacks.

Same as parseInsecureJsonBody

Same as parseInsecureJsonBody, but return an invalid args response on a parse error.

Provide a JSON representation for usage with selectReps, using aeson's toJSON (aeson >= 0.11: toEncoding) function to perform the conversion.

Same as parseCheckJsonBody, but return an invalid args response on a parse error.

Same as parseInsecureJsonBody, but return an invalid args response on a parse error.

Same as parseInsecureJsonBody, but return an invalid args response on a parse error.

Convert a value to a JSON representation via aeson's toJSON function.

Convert a value to a JSON representation via aeson's toEncoding function.

Represents TypedContent as a String, rendering at most a specified number of bytes of the content, and annotating it with the remaining length. Returns Nothing if the content type indicates the content is binary data.

Link to the specified local script.

Link to the specified local script.

Link to the specified remote script.

Link to the specified remote script.

Link to the specified local stylesheet.

Link to the specified local stylesheet.

Link to the specified remote stylesheet.

Link to the specified remote stylesheet.

Wraps the Content generated by hamletToContent in a RepHtml.

Since 1.2.1

Wraps the Content generated by hamletToContent in a RepHtml.

Add description meta tag to the head of the page

Google does not use the description tag as a ranking signal, but the contents of this tag will likely affect your click-through rate since it shows up in search results.

The average length of the description shown in Google's search results is about 160 characters on desktop, and about 130 characters on mobile, at time of writing.

Source: https://www.advancedwebranking.com/blog/meta-tags-important-in-seo/

Add translated description meta tag to the head of the page

n.b. See comments for setDescription.

Add description meta tag to the head of the page

Google does not use the description tag as a ranking signal, but the contents of this tag will likely affect your click-through rate since it shows up in search results.

The average length of the description shown in Google's search results is about 160 characters on desktop, and about 130 characters on mobile, at time of writing.

Unlike setDescription, this version is *idempotent* - calling it multiple times will result in only a single description meta tag in the head.

Source: https://www.advancedwebranking.com/blog/meta-tags-important-in-seo/

Add translated description meta tag to the head of the page

n.b. See comments for setDescriptionIdemp.

Unlike setDescriptionI, this version is *idempotent* - calling it multiple times will result in only a single description meta tag in the head.

Add OpenGraph image meta tag to the head of the page

Best practices:

• Use custom images for shareable pages, e.g., homepage, articles, etc.

• Use your logo or any other branded image for the rest of your pages.

• Use images with a 1.91:1 ratio and minimum recommended dimensions of 1200x630 for optimal clarity across all devices.

Source: https://ahrefs.com/blog/open-graph-meta-tags/

Add OpenGraph type meta tag to the head of the page

See all available OG types here: https://ogp.me/#types

Set the page title.

Calling setTitle or setTitleI multiple times overrides previously set values.

SEO Notes:

• Title tags are the second most important on-page factor for SEO, after content

• Every page should have a unique title tag

• Start your title tag with your main targeted keyword

• Don't stuff your keywords

• Google typically shows 55-64 characters, so aim to keep your title length under 60 characters

Set the localised page title.

n.b. See comments for setTitle

A quasi-quoter to parse a string into a list of Resources. Checks for overlapping routes, failing if present; use parseRoutesNoCheck to skip the checking. See documentation site for details on syntax.

Same as parseRoutes, but uses an external file instead of quasiquotation.

The recommended file extension is .yesodroutes.

Same as parseRoutesNoCheck, but uses an external file instead of quasiquotation.

The recommended file extension is .yesodroutes.

Same as parseRoutes, but performs no overlap checking.

Default options for generating routes.

The defaults are:

• setEqDerived, setShowDerived, setReadDerived: True — derive Eq, Show and Read for the route datatype.

• setCreateResources: True — emit the resourcesSite :: [ResourceTree String] term.

• setParameterizedSubroute: False — subroutes are unparameterized.

• setFocusOnNestedRoute: unset — generate the whole route tree rather than focusing on a single nested route.

• setNestedRouteFallthrough: False — a nested route that fails to match throws notFound instead of falling through.

Use the set* functions to override individual fields.

Determine whether or not to generate the resourcesApp value.

Disabling this can be useful if you are creating the routes :: [ResourceTree String] elsewhere in your module, and referring to it here. The resourcesApp can become very large in large applications, and duplicating it can result in signifiacntly higher compile times.

Default: True.

When True, derive an Eq instance for the route datatype.

Default: True.

If you set this with routeName, then the code generation will generate code for the routeName to be imported in the main dispatch class. This allows you to generate code in separate modules.

Example:

First, you would put your route definitions into their own file.

module App.Routes.Resources where

import Yesod.Core

appResources :: [ResourceTree String]
appResources = [parseRoutes|
    /  HomeR GET

    /nest NestR:
        /     NestIndexR GET POST
        /#Int NestShowR  GET POST

|]

We have defined a nested route called NestR here. A nested route is created with the : after the route name.

Then, in a module for the route specifically, we can generate the route datatype and instances for later hooking in to the main instance.

module App.Routes.NestR where

import App.Routes.Resources
import Yesod.Core

mkYesodOpts (setFocusOnNestedRoute NestR defaultOpts) App appResources

If you only want to generate the datatypes, you can separate things further using mkYesodDataOpts and mkYesodDispatchOpts.

Finally, import that type into your main yesod macro code.

module App where

import App.Routes.Resources (appResources)
import App.Routes.NestR (NestR(..))

mkYesod App appResources

The call to mkYesod will delegate to the generated code for NestR rather than regenerating it.

By default, defaultOpts starts unfocused (the whole route tree is generated). Use unsetFocusOnNestedRoute to clear a previously-set focus.

For a full walkthrough — including subsites, linking to nested routes, and why split sites should enable setNestedRouteFallthrough — see the guide at https://github.com/yesodweb/yesod/blob/master/yesod-core/docs/split-route-compilation.md.

When True, a nested route that fails to match falls through to the enclosing dispatch rather than throwing notFound. When False, a non-matching nested route throws notFound.

Default: False.

If True, generate nested-discovery code (separate subroute datatypes and RenderRouteNested dispatch instances) for a parameterized/ site instead of the backwards-compatible inline output. The subroute datatypes then carry the parent site's type variables so that the ParentSite / ParentArgs associated types stay well-scoped.

Because the generated nested instances are parameterized over the site's type variables, the splice emits instance heads with non-variable arguments; a module using this typically needs FlexibleContexts, FlexibleInstances, MultiParamTypeClasses, TypeFamilies and, for a parameterized subsite whose master is determined by the subsite (a subsite -> master functional dependency on the user's class), UndecidableInstances.

Monomorphic sites always use nested discovery regardless of this flag; see discoveryMode.

Default: False.

When True, derive a Read instance for the route datatype.

Default: True.

When True, derive a Show instance for the route datatype.

Default: True.

Clear any nested-route focus set by setFocusOnNestedRoute, so that the whole route tree is generated.

defaultOpts already starts unfocused, so this is only needed to undo a previous setFocusOnNestedRoute.

A type that can be converted from JSON, with the possibility of failure.

In many cases, you can get the compiler to generate parsing code for you (see below). To begin, let's cover writing an instance by hand.

There are various reasons a conversion could fail. For example, an Object could be missing a required key, an Array could be of the wrong size, or a value could be of an incompatible type.

The basic ways to signal a failed conversion are as follows:

• fail yields a custom error message: it is the recommended way of reporting a failure;

• empty (or mzero) is uninformative: use it when the error is meant to be caught by some (<|>);

• typeMismatch can be used to report a failure when the encountered value is not of the expected JSON type; unexpected is an appropriate alternative when more than one type may be expected, or to keep the expected type implicit.

prependFailure (or modifyFailure) add more information to a parser's error messages.

An example type and instance using typeMismatch and prependFailure:

-- Allow ourselves to write Text literals.
{-# LANGUAGE OverloadedStrings #-}

data Coord = Coord { x :: Double, y :: Double }

instance FromJSON Coord where
    parseJSON (Object v) = Coord
        <$> v .: "x"
        <*> v .: "y"

    -- We do not expect a non-Object value here.
    -- We could use empty to fail, but typeMismatch
    -- gives a much more informative error message.
    parseJSON invalid    =
        prependFailure "parsing Coord failed, "
            (typeMismatch "Object" invalid)

For this common case of only being concerned with a single type of JSON value, the functions withObject, withScientific, etc. are provided. Their use is to be preferred when possible, since they are more terse. Using withObject, we can rewrite the above instance (assuming the same language extension and data type) as:

instance FromJSON Coord where
    parseJSON = withObject "Coord" $ \v -> Coord
        <$> v .: "x"
        <*> v .: "y"

Instead of manually writing your FromJSON instance, there are two options to do it automatically:

• Data.Aeson.TH provides Template Haskell functions which will derive an instance at compile time. The generated instance is optimized for your type so it will probably be more efficient than the following option.

• The compiler can provide a default generic implementation for parseJSON.

To use the second, simply add a deriving Generic clause to your datatype and declare a FromJSON instance for your datatype without giving a definition for parseJSON.

For example, the previous example can be simplified to just:

{-# LANGUAGE DeriveGeneric #-}

import GHC.Generics

data Coord = Coord { x :: Double, y :: Double } deriving Generic

instance FromJSON Coord

or using the DerivingVia extension

deriving via Generically Coord instance FromJSON Coord

The default implementation will be equivalent to parseJSON = genericParseJSON defaultOptions; if you need different options, you can customize the generic decoding by defining:

customOptions = defaultOptions
                { fieldLabelModifier = map toUpper
                }

instance FromJSON Coord where
    parseJSON = genericParseJSON customOptions