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

Safe HaskellNone

Yesod.Core

Contents

Synopsis

Type classes

class RenderRoute a => Yesod a whereSource

Define settings for a Yesod applications. All methods have intelligent defaults, and therefore no implementation is required.

Methods

approot :: Approot aSource

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

Default value: ApprootRelative. This is valid 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.

If this is not true, you should override with a different implementation.

errorHandler :: ErrorResponse -> GHandler sub a ChooseRepSource

Output error response pages.

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

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

urlRenderOverride :: a -> Route a -> Maybe BuilderSource

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.

isAuthorizedSource

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 BoolSource

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

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]Source

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.

joinPathSource

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.

addStaticContentSource

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.

cookiePath :: a -> ByteStringSource

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

cookieDomain :: a -> Maybe ByteStringSource

The domain value to set for cookies. By default, the domain is not set, meaning cookies will be sent only to the current domain.

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

Maximum allowed length of the request body, in bytes.

Default: 2 megabytes.

getLogger :: a -> IO LoggerSource

Returns a Logger to use for log messages.

Default: Sends to stdout and automatically flushes on each write.

messageLoggerSource

Arguments

:: a 
-> Logger 
-> Loc

position in source code

-> LogLevel 
-> LogStr

message

-> IO () 

Send a message to the Logger provided by getLogger.

Note: This method is no longer used. Instead, you should override messageLoggerSource.

messageLoggerSourceSource

Arguments

:: a 
-> Logger 
-> Loc

position in source code

-> LogSource 
-> LogLevel 
-> LogStr

message

-> IO () 

Send a message to the Logger provided by getLogger.

logLevel :: a -> LogLevelSource

The logging level in place for this application. Any messages below this level will simply be ignored.

gzipSettings :: a -> GzipSettingsSource

GZIP settings.

jsLoader :: a -> ScriptLoadPosition aSource

Where to Load sripts from. We recommend the default value, BottomOfBody. Alternatively use the built in async yepnope loader:

 BottomOfHeadAsync $ loadJsYepnope $ Right $ StaticR js_modernizr_js

Or write your own async js loader: see loadJsYepnope

makeSessionBackend :: a -> IO (Maybe (SessionBackend a))Source

Create a session backend. Returning Nothing disables sessions.

Default: Uses clientsession with a 2 hour timeout.

fileUploadSource

Arguments

:: a 
-> Word64

request body size

-> FileUpload 

How to store uploaded files.

Default: Whe nthe request body is greater than 50kb, store in a temp file. Otherwise, store in memory.

shouldLog :: a -> LogSource -> LogLevel -> BoolSource

Should we log the given log source/level combination.

Default: Logs everything at or above logLevel

yesodMiddleware :: GHandler sub a res -> GHandler sub a resSource

A Yesod middleware, which will wrap every handler function. This allows you to run code before and after a normal handler.

Default: Adds the response header "Vary: Accept, Accept-Language".

Since: 1.1.6

class YesodDispatch sub master whereSource

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

Methods

yesodDispatchSource

Arguments

:: Yesod master 
=> Logger 
-> master 
-> sub 
-> (Route sub -> Route master) 
-> (Maybe (SessionBackend master) -> Application)

404 handler

-> (Route sub -> Maybe (SessionBackend master) -> Application)

405 handler

-> Text

request method

-> [Text]

pieces

-> Maybe (SessionBackend master) 
-> Application 

yesodRunner :: Yesod master => Logger -> GHandler sub master ChooseRep -> master -> sub -> Maybe (Route sub) -> (Route sub -> Route master) -> Maybe (SessionBackend master) -> ApplicationSource

Instances

class Eq (Route a) => RenderRoute a where

Associated Types

data Route a1

The type-safe URLs associated with a site argument.

Methods

renderRoute :: Route a -> ([Text], [(Text, Text)])

Breadcrumbs

class YesodBreadcrumbs y whereSource

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

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)])Source

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

Types

data Approot master Source

How to determine the root of the application for constructing URLs.

Note that future versions of Yesod may add new constructors without bumping the major version number. As a result, you should not pattern match on Approot values.

Constructors

ApprootRelative

No application root.

ApprootStatic Text 
ApprootMaster (master -> Text) 
ApprootRequest (master -> Request -> Text) 

Utitlities

maybeAuthorizedSource

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

Convert a widget to a PageContent.

Defaults

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

The default error handler for errorHandler.

Data types

unauthorizedI :: RenderMessage master msg => msg -> GHandler sub master AuthResultSource

Return an Unauthorized value, with the given i18n message.

Logging

logDebug :: Q Exp

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

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

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"

logDebugS :: Q Exp

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

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

logOtherS :: Q Exp

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

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

Sessions

newtype SessionBackend master Source

Constructors

SessionBackend 

Fields

sbLoadSession :: master -> Request -> UTCTime -> IO (BackendSession, SaveSession)

Return the session data and a function to save the session

clientSessionBackendSource

Arguments

:: Yesod master 
=> Key

The encryption key

-> Int

Inactive session valitity in minutes

-> SessionBackend master 

clientSessionBackend2Source

Arguments

:: Yesod master 
=> Key

The encryption key

-> IO ClientSessionDateCache

See clientSessionDateCacher

-> SessionBackend master 

clientSessionDateCacherSource

Arguments

:: NominalDiffTime

Inactive session valitity.

-> IO (IO ClientSessionDateCache, IO ()) 

loadClientSessionSource

Arguments

:: Yesod master 
=> Key 
-> Int

timeout

-> ByteString

session name

-> master 
-> Request 
-> UTCTime 
-> IO (BackendSession, SaveSession) 

data Header Source

Headers to be added to a Result.

Instances

JS loaders

loadJsYepnope :: Yesod master => Either Text (Route master) -> [Text] -> Maybe (HtmlUrl (Route master)) -> HtmlUrl (Route master)Source

For use with setting jsLoader to BottomOfHeadAsync

type BottomOfHeadAsync masterSource

Arguments

 = [Text]

urls to load asynchronously

-> Maybe (HtmlUrl (Route master))

widget of js to run on async completion

-> HtmlUrl (Route master)

widget to insert at the bottom of head

Misc

yesodRenderSource

Arguments

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

url query string

-> Text 

runFakeHandler :: (Yesod master, MonadIO m) => SessionMap -> (master -> Logger) -> master -> GHandler master master a -> m (Either ErrorResponse a)Source

Run a GHandler completely outside of Yesod. This function comes with many caveats and you shouldn't use it unless you fully understand what it's doing and how it works.

As of now, there's only one reason to use this function at all: in order to run unit tests of functions inside GHandler but that aren't easily testable with a full HTTP request. Even so, it's better to use wai-test or yesod-test instead of using this function.

This function will create a fake HTTP request (both wai's Request and yesod's Request) and feed it to the GHandler. The only useful information the GHandler may get from the request is the session map, which you must supply as argument to runFakeHandler. All other fields contain fake information, which means that they can be accessed but won't have any useful information. The response of the GHandler is completely ignored, including changes to the session, cookies or headers. We only return you the GHandler's return value.

Re-exports