yesod-core-0.9.4.1: Creation of type-safe, RESTful web applications.

Yesod.Core

Contents

- Type classes
  - Breadcrumbs
- Utitlities
- Defaults
- Data types
- Logging
- Misc
- Re-exports

Synopsis

- class RenderRoute (Route a) => Yesod a where
  - approot :: a -> Text
  - encryptKey :: a -> IO (Maybe Key)
  - clientSessionDuration :: a -> Int
  - errorHandler :: ErrorResponse -> GHandler sub a ChooseRep
  - defaultLayout :: GWidget sub a () -> GHandler sub a RepHtml
  - urlRenderOverride :: a -> Route a -> Maybe Builder
  - isAuthorized :: Route a -> Bool -> GHandler s a AuthResult
  - isWriteRequest :: Route a -> GHandler s a Bool
  - authRoute :: a -> Maybe (Route a)
  - cleanPath :: a -> [Text] -> Either [Text] [Text]
  - joinPath :: a -> Text -> [Text] -> [(Text, Text)] -> Builder
  - addStaticContent :: Text -> Text -> ByteString -> GHandler sub a (Maybe (Either Text (Route a, [(Text, Text)])))
  - sessionIpAddress :: a -> Bool
  - cookiePath :: a -> ByteString
  - maximumContentLength :: a -> Maybe (Route a) -> Int
  - messageLogger :: a -> Loc -> LogLevel -> Text -> IO ()
  - gzipCompressFiles :: a -> Bool
  - yepnopeJs :: a -> Maybe (Either Text (Route a))
- class YesodDispatch a master where
  - yesodDispatch :: Yesod master => a -> Maybe Key -> [Text] -> master -> (Route a -> Route master) -> Maybe Application
  - yesodRunner :: Yesod master => a -> master -> (Route a -> Route master) -> Maybe Key -> Maybe (Route a) -> GHandler a master ChooseRep -> Application
- class Eq u => RenderRoute u where
  - renderRoute :: u -> ([Text], [(Text, Text)])
- class YesodBreadcrumbs y where
  - breadcrumb :: Route y -> GHandler sub y (Text, Maybe (Route y))
- breadcrumbs :: YesodBreadcrumbs y => GHandler sub y (Text, [(Route y, Text)])
- maybeAuthorized :: Yesod a => Route a -> Bool -> GHandler s a (Maybe (Route a))
- widgetToPageContent :: (Eq (Route master), Yesod master) => GWidget sub master () -> GHandler sub master (PageContent (Route master))
- defaultErrorHandler :: Yesod y => ErrorResponse -> GHandler sub y ChooseRep
- data AuthResult
  - = Authorized
  - | AuthenticationRequired
  - | Unauthorized Text
- data LogLevel
  - = LevelDebug
  - | LevelInfo
  - | LevelWarn
  - | LevelError
  - | LevelOther Text
- formatLogMessage :: Loc -> LogLevel -> Text -> IO Text
- fileLocationToString :: Loc -> String
- logDebug :: Q Exp
- logInfo :: Q Exp
- logWarn :: Q Exp
- logError :: Q Exp
- logOther :: Text -> Q Exp
- yesodVersion :: String
- yesodRender :: Yesod y => y -> Route y -> [(Text, Text)] -> Text
- module Yesod.Content
- module Yesod.Dispatch
- module Yesod.Handler
- module Yesod.Request
- module Yesod.Widget
- module Yesod.Message
- module Yesod.Config

# Type classes

class RenderRoute (Route a) => Yesod a where

Define settings for a Yesod applications. The only required setting is `approot`; other than that, there are intelligent defaults.

Methods

approot :: a -> Text

An absolute URL to the root of the application. Do not include trailing slash.

If you want to be lazy, you can supply an empty string under the following conditions:

- Your application is served from the root of the domain.
- You do not use any features that require absolute URLs, such as Atom feeds and XML sitemaps.

encryptKey :: a -> IO (Maybe Key)

The encryption key to be used for encrypting client sessions. Returning `Nothing` disables sessions.

clientSessionDuration :: a -> Int

Number of minutes before a client session times out. Defaults to 120 (2 hours).

errorHandler :: ErrorResponse -> GHandler sub a ChooseRep

Output error response pages.

defaultLayout :: GWidget sub a () -> GHandler sub a RepHtml

Applies some form of layout to the contents of a page.

urlRenderOverride :: a -> Route a -> Maybe Builder

Override the rendering function for a particular URL. One use case for this is to offload static hosting to a different domain name to avoid sending cookies.

isAuthorized

Arguments

:: Route a |
-> Bool | is this a write request?
-> GHandler s a AuthResult |

Determine if a request is authorized or not.

Return `Authorized` if the request is authorized, `Unauthorized` a message if unauthorized. If authentication is required, return `AuthenticationRequired`.

isWriteRequest :: Route a -> GHandler s a Bool

Determines whether the current request is a write request. By default, this assumes you are following RESTful principles, and determines this from request method. In particular, all except the following request methods are considered write: GET HEAD OPTIONS TRACE.

This function is used to determine if a request is authorized; see `isAuthorized`.

authRoute :: a -> Maybe (Route a)

The default route for authentication.

Used in particular by `isAuthorized`, but library users can do whatever they want with it.

cleanPath :: a -> [Text] -> Either [Text] [Text]

A function used to clean up path segments. It returns `Right` with a clean path or `Left` with a new set of pieces the user should be redirected to. The default implementation enforces:

- No double slashes
- There is no trailing slash.

Note that versions of Yesod prior to 0.7 used a different set of rules involing trailing slashes.

joinPath

Arguments

:: a |
-> Text | application root
-> [Text] | path pieces
-> [(Text, Text)] | query string
-> Builder |

Builds an absolute URL by concatenating the application root with the pieces of a path and a query string, if any. Note that the pieces of the path have been previously cleaned up by `cleanPath`.

addStaticContent

Arguments

:: Text | filename extension
-> Text | mime-type
-> ByteString | content
-> GHandler sub a (Maybe (Either Text (Route a, [(Text, Text)]))) |

This function is used to store some static content to be served as an external file. The most common case of this is stashing CSS and JavaScript content in an external file; the Yesod.Widget module uses this feature.

The return value is `Nothing` if no storing was performed; this is the default implementation. A `Just` `Left` gives the absolute URL of the file, whereas a `Just` `Right` gives the type-safe URL. The former is necessary when you are serving the content outside the context of a Yesod application, such as via memcached.

sessionIpAddress :: a -> Bool

Whether or not to tie a session to a specific IP address. Defaults to `True`.

cookiePath :: a -> ByteString

The path value to set for cookies. By default, uses "/", meaning cookies will be sent to every page on the current domain.

maximumContentLength :: a -> Maybe (Route a) -> Int

Maximum allowed length of the request body, in bytes.

messageLogger

Arguments

:: a |
-> Loc | position in source code
-> LogLevel |
-> Text | message
-> IO () |

Send a message to the log. By default, prints to stdout.

gzipCompressFiles :: a -> Bool

Apply gzip compression to files. Default is false.

yepnopeJs :: a -> Maybe (Either Text (Route a))

Location of yepnope.js, if any. If one is provided, then all Javascript files will be loaded asynchronously.

class YesodDispatch a master where

This class is automatically instantiated when you use the template haskell mkYesod function. You should never need to deal with it directly.

Methods

yesodDispatch :: Yesod master => a -> Maybe Key -> [Text] -> master -> (Route a -> Route master) -> Maybe Application

yesodRunner :: Yesod master => a -> master -> (Route a -> Route master) -> Maybe Key -> Maybe (Route a) -> GHandler a master ChooseRep -> Application

class Eq u => RenderRoute u where

Methods

renderRoute :: u -> ([Text], [(Text, Text)])

## Breadcrumbs

class YesodBreadcrumbs y where

A type-safe, concise method of creating breadcrumbs for pages. For each resource, you declare the title of the page and the parent resource (if present).

Methods

breadcrumb :: Route y -> GHandler sub y (Text, Maybe (Route y))

Returns the title and the parent resource, if available. If you return a `Nothing`, then this is considered a top-level page.

breadcrumbs :: YesodBreadcrumbs y => GHandler sub y (Text, [(Route y, Text)])

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

# Utitlities

maybeAuthorized

Arguments

:: Yesod a |
=> Route a |
-> Bool | is this a write request?
-> GHandler s a (Maybe (Route a)) |

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.

widgetToPageContent :: (Eq (Route master), Yesod master) => GWidget sub master () -> GHandler sub master (PageContent (Route master))

Convert a widget to a `PageContent`.

# Defaults

defaultErrorHandler :: Yesod y => ErrorResponse -> GHandler sub y ChooseRep

The default error handler for `errorHandler`.

# Data types

data AuthResult

Constructors

Authorized |
AuthenticationRequired |
Unauthorized Text |

Instances

Eq AuthResult |
Read AuthResult |
Show AuthResult |

# Logging

data LogLevel

Constructors

LevelDebug |
LevelInfo |
LevelWarn |
LevelError |
LevelOther Text |

Instances

Eq LogLevel |
Ord LogLevel |
Read LogLevel |
Show LogLevel |
Lift LogLevel |

formatLogMessage

Arguments

:: Loc |
-> LogLevel |
-> Text | message
-> IO Text |

fileLocationToString :: Loc -> String

logDebug :: Q Exp

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

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

logInfo :: Q Exp

See `logDebug`

logWarn :: Q Exp

See `logDebug`

logError :: Q Exp

See `logDebug`

logOther :: Text -> Q Exp

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

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

# Misc

yesodVersion :: String

yesodRender :: Yesod y => y -> Route y -> [(Text, Text)] -> Text

# Re-exports

module Yesod.Content

module Yesod.Dispatch

module Yesod.Handler

module Yesod.Request

module Yesod.Widget

module Yesod.Message

module Yesod.Config