Yesod (web framework)

Yesod uses the model–view–controller (MVC) software design pattern for its user interfaces.

Yesod uses a Web application interface (WAI),{{cite web |url=http://hackage.haskell.org/package/wai |title=The wai package |publisher=Hackage.haskell.org |access-date=2012-10-23}} a type of application programming interface (API), to isolate servlets, aka web apps., from servers, with handlers for the server protocols Common Gateway Interface (CGI),{{cite web |url=http://hackage.haskell.org/package/wai-extra |title=The wai-extra package with CGI WAI handler |publisher=Hackage.haskell.org |access-date=2012-10-23}} FastCGI,{{cite web |url=http://hackage.haskell.org/package/wai-handler-fastcgi |title=The wai-handler-fastcgi package |publisher=Hackage.haskell.org |access-date=2012-10-23}} Simple Common Gateway Interface (SCGI),{{cite web |url=http://hackage.haskell.org/package/wai-handler-scgi |title=The wai-handler-scgi package |publisher=Hackage.haskell.org |access-date=2012-10-23}} Warp,{{cite web |url=http://hackage.haskell.org/package/warp |title=The warp package |publisher=Hackage.haskell.org |access-date=2012-10-23}} Launch (open as local URL to the default browser, closing the server when the window is closed),{{cite web |url=http://hackage.haskell.org/package/wai-handler-launch |title=The wai-handler-launch package |publisher=Hackage.haskell.org |access-date=2012-10-23}}

See ref.{{cite web |url=http://www.yesodweb.com/book/basics |title=book - Basics |publisher=Yesodweb.com |access-date=2012-10-23}} Yesod requires a data type that instantiates the model–view–controller classes. This is called the foundation type. In the example below, it is named "MyApp".

The REST model identifies a web resource with a web path. Here, REST resources are given names with an R suffix (like "HomeR") and are listed in a parseRoutes site map description template. From this list, route names and dispatch handler names are derived.

Yesod makes use of Template Haskell metaprogramming to generate code from templates at compile time, assuring that the names in the templates match and everything typechecks (e.g. web resource names and handler names).

By inserting a mkYesod call, this will call Template Haskell primitives to generate the code[http://hackage.haskell.org/package/yesod-core/docs/src/Yesod-Core-Internal-TH.html#mkYesod The mkYesod code] corresponding to the route type members, and the instances of the dispatch controller classes as to dispatch GET calls to route HomeR to a routine named composing them both as "getHomeR", expecting an existing handler that matches the name.

"Hello, World!" program example based on a Common Gateway Interface (CGI) server interface (the handler types have changed, but the philosophy remains):

{- file wai-cgi-hello.hs -}

{-# LANGUAGE PackageImports, TypeFamilies, QuasiQuotes, MultiParamTypeClasses,

TemplateHaskell, OverloadedStrings #-}

import "wai" Network.Wai

import "wai-extra" Network.Wai.Handler.CGI (run) -- interchangeable WAI handler

import "yesod" Yesod

import "yesod-core" Yesod.Handler (getRequest)

import "text" Data.Text (Text)

import "shakespeare" Text.Cassius (Color(..), colorBlack)

-- the Foundation type

data MyApp = MyApp

-- sitemap template, listing path, resource name and methods accepted

-- `mkYesod` takes the foundation type name as param. for name composition of dispatch functions

mkYesod "MyApp" [parseRoutes|

/ HomeR GET

|]

instance Yesod MyApp

-- indentation structured CSS template

myStyle :: [Text] → CssUrl url

myStyle paramStyle =

[cassius|

.box

border: 1px solid #{boxColor}

|]

where

boxColor = case paramStyle of

["high-contrast"] → colorBlack

_ → Color 0 0 255

-- indentation structured HTML template

myHtml :: [(Text, Text)] → HtmlUrl url

myHtml params = [hamlet|

Hello World! There are #{length params} parameters:

$if null params

Nothing to list

$else

$forall param <- params

• #{fst param}: #{snd param}

  |]

  getHomeR :: Handler RepHtml

  getHomeR = do

  req <- getRequest

  let params = reqGetParams req

  paramStyle <- lookupGetParams "style"

  defaultLayout $ do

  -- adding widgets to the Widget monad (a Writer monad)

  setTitle "Yesod example"

  toWidgetHead $ myStyle paramStyle

  toWidgetBody $ myHtml params

  -- there are run function variants for different WAI handlers

  main = toWaiApp MyApp >>= run

  1. cgi test

  export REMOTE_ADDR=127.0.0.1

  export REQUEST_METHOD=GET

  export PATH_INFO=/

  export QUERY_STRING='p1=abc;p2=def;style=high-contrast'

  ./wai-cgi-hello

See ref.{{cite web |url=http://www.yesodweb.com/book/routing-and-handlers |title=book - Routing and Handlers |publisher=Yesodweb.com |access-date=2012-10-23}}{{cite web |url=http://fpcomplete.com/yesod-tutorial-2-playing-with-routes-and-links/ |title=Playing with Routes and Links |publisher=FPComplete.com |date=2012-10-17 |access-date=2012-10-28}} Yesod follows the representational state transfer model of access to web documents, identifying docs. and directories as resources with a Route constructor, named with an uppercase R suffix (for example, HomeR).

;The routes table: The parseRoutes template should list the resources specifying route pieces, resource name and dispatch methods to be accepted.

URL segment capture as parameter is possible specifying a '#' prefix for single segment capture or '*' for multisegment capture, followed by the parameter type.

-- given a MyApp foundation type

mkYesod "MyApp" [parseRoutes|

/ HomeR -- no http methods stated: all methods accepted

/blog BlogR GET POST

-- the '#' prefix specify the path segment as a route handler parameter

/article/#ArticleId ArticleR GET PUT

-- the '*' prefix specify the parameter as a sequence of path pieces

/branch/*Texts BranchR GET

-- to simplify the grammar, compound types must use an alias, eg. type Texts for [Text]

|]

• Applying the previous template generates the following route constructors:

data Route MyApp =

HomeR -- referenced in templates as: @{HomeR}

| BlogR -- in templates: @{BlogR}

| ArticleR ArticleId -- in templates: @{ArticleR myArticleId}

| BranchR Texts -- in templates: @{BranchR myBranchSegments}

• For every supported HTTP method a handler function must be created to match the dispatch names generated by mkYesod from the parseRoutes template, by prefixing the method name (or the prefix "handler" if no method stated) to the resource, as described (actual versions handler types have changed, but the philosophy remains):

-- for "/ HomeR" -- no http methods stated ⇒ only one handler with prefix handler

handlerHomeR :: HasReps t ⇒ Handler t

-- for "/blog BlogR GET POST"

getBlogR :: HasReps t ⇒ Handler t

postBlogR :: HasReps t ⇒ Handler t

-- for "/article/#ArticleId ArticleR GET PUT"

getArticleR :: HasReps t ⇒ ArticleId → Handler t

putArticleR :: HasReps t ⇒ ArticleId → Handler t

See ref.

See ref.{{cite web |url=http://www.yesodweb.com/book/authentication-and-authorization |title=book - Authentication and Authorization |publisher=Yesodweb.com |access-date=2012-10-23}} Authentication plugins: OpenID, BrowserID, Email, GoogleEmail, HashDB, RpxNow.{{cite web |url=http://hackage.haskell.org/package/yesod-auth |title=The yesod-auth package |publisher=Hackage.haskell.org |access-date=2012-10-26}}

:There is an important setting for automatic redirection after authentication.{{cite web |url=http://www.yesodweb.com/book/sessions |title=book - Sessions - See section "Ultimate Destination"|publisher=Yesodweb.com |access-date=2012-11-17}}

See ref.{{cite web |url=http://www.yesodweb.com/book/sessions |title=Sessions |publisher=Yesodweb.com |access-date=2012-10-23}} Session back-ends: ClientSession{{cite web |url=http://hackage.haskell.org/packages/archive/clientsession/latest/doc/html/Web-ClientSession.html |title=Web.ClientSession |publisher=Hackage.haskell.org |access-date=2012-10-25}} (it stores the session in a cookie), ServerSession{{cite web |url=http://hackage.haskell.org/package/serversession |title=ServerSession: secure modular server-side sessions |publisher=Hackage.haskell.org |access-date=2018-10-29}}{{cite web |url=http://hackage.haskell.org/package/serversession-frontend-yesod |title=Web.ServerSession.Frontend.Yesod |publisher=Hackage.haskell.org |access-date=2018-10-29}} (it stores most of the session data at the server)

:>> To avoid undue bandwidth overhead, production sites can serve their static content from a separate domain name to avoid the overhead of transmitting the session cookie for each request

A success, failure or indicative message can be stored (setMessage) in the Session and will be shown, if it exists, by the default_layout routine through the default_layout.hamlet template, being cleared on consultation.{{cite web |url=https://www.yesodweb.com/book/sessions#sessions_messages |title=Session Messages |publisher=Yesodweb.com |access-date=2018-10-23}}

Common URL prefix subsites for workflows, file serving or site partitioning. See ref.{{cite web |url=http://www.yesodweb.com/book/creating-a-subsite |title=Creating a Subsite |publisher=Yesodweb.com |access-date=2012-10-25}}{{cite web |url=http://monoid.se/haskell/yesod-and-subsites/ |title=Yesod and subsites: a no-brainer |publisher=Monoid.se |date=2012-08-22 |access-date=2012-10-28}}[]

Built-in subsites: Static,{{cite web |url=http://www.yesodweb.com/blog/2010/12/magic-of-yesod-part2 |title=The Magic of Yesod, part 2 - See section "Static Subsite" |publisher=Yesodweb.com |date=2010-12-25 |access-date=2012-10-25}}{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-static/latest/doc/html/Yesod-Static.html |title=The package yesod-static - Static Subsite |publisher=Hackage.haskell.org |access-date=2012-10-25}} Auth{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-auth/latest/doc/html/Yesod-Auth.html |title=The package yesod-auth - Auth Subsite |publisher=Hackage.haskell.org |access-date=2012-10-25}}

See ref.{{cite web |url=http://www.yesodweb.com/book/forms |title=book - Forms |publisher=Yesodweb.com |access-date=2012-10-23}}

The Form type here is an object that is used in the controller to parse and process the form fields user input and produce a (FormResult, Widget) pair were the widget holds the layout of the next rendering of the form with error messages and marks. It can also be used to generate a new form with blanks or default values.

The form type takes the shape of a function of an html snippet to be embedded in the view, that will hold security purpose hidden fields.

A form object is generated from an Applicative – Monadic composition of fields for a combined, sequential parsing of field inputs.

There are three types of forms:

• Applicative (with tabular layout),
• Monadic (with free layout style), both in the Yesod.Form.Functions module,
• Input (for parsing only, no view generated) in the Yesod.Form.Input module.

The field generators, whose names are composed by the form type initial (a|m|i) followed by (req|opt){- required or optional -}, have a fieldParse component and a fieldView one.{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-form/latest/doc/html/Yesod-Form-Fields.html |title=Yesod.Form.Fields |publisher=Hackage.haskell.org |access-date=2012-10-23}}

• the function runForm{Post|Get} runs the field parsers against the form field inputs and generates a (FormResult, Widget) pair from the views offering a new form widget with the received form field values as defaults. The function suffix is the http method used in the form submission.
• while generateForm{Post|Get} ignores inputs from the client and generates a blank or defaults form widget.{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-form/latest/doc/html/Yesod-Form-Functions.html#v:runFormPost |title=Yesod.Form.Functions runFormPost |publisher=Hackage.haskell.org |access-date=2012-10-25}}

The actual function parameters and types have changed through Yesod versions. Check the Yesod book and libraries signatures.

The magic is in the {{mono|FormResult}} data type Applicative instance, where {{mono|(<*>)}} collects the error messages for the case of FormFailure [textErrMsg] result values{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-form/latest/doc/html/Yesod-Form-Types.html#t:FormResult |title=Yesod.Form.Types |publisher=Hackage.haskell.org |access-date=2012-10-23}}

Monadic forms permit free form layout and better treatment of {{mono|hiddenField}} members.

A sample of an Applicative{{cite web |url=http://www.haskell.org/haskellwiki/Applicative_functor |title=HaskellWiki - Applicative functor |publisher=haskell.org |access-date=2012-10-24}} form:

-- a record for our form fields

data Person = Person {personName :: Text, personAge :: Int, personLikings :: Maybe Text}

-- the Form type has an extra parameter for an html snippet to be embedded, containing a CSRF token hidden field for security

type Form sub master x = Html → MForm sub master (FormResult x, Widget)

{-

-- for messages in validation functions:

@param master: yesod instance to use in renderMessage (return from handler's getYesod)

@param languages: page languages to use in renderMessage

-- optional defaults record:

@param mbPersonDefaults: Just defaults_record, or Nothing for blank form

-}

personForm :: MyFoundationType → [Text] → Maybe Person → Form sub master Person

{- aopt (optional field AForm component) for "Maybe" fields,

areq (required fld AForm comp.) will insert the "required" attribute

-}

personForm master languages mbPersonDefaults = renderTable $

Person <$> areq textField fldSettingsName mbNameDefault

<*> areq customPersonAgeField fldSettingsAge mbAgeDefault

<*> aopt textareaField fldSettingsLikings mbLikingsDefault

where

mbNameDefault = fmap personName mbPersonDefaults

mbAgeDefault = fmap personAge mbPersonDefaults

mbLikingsDefault = fmap personLikings mbPersonDefaults

-- "fieldSettingsLabel" returns an initial fieldSettings record

-- recently the "FieldSettings" record can be defined from a String label since it implements IsString

fldSettingsName = (fieldSettingsLabel MsgName) {fsAttrs = [("maxlength","20")]}

fldSettingsAge = fieldSettingsLabel MsgAge

fldSettingsLikings = (fieldSettingsLabel MsgLikings) {fsAttrs = [("cols","40"),("rows","10")]}

customPersonAgeField = check validateAge intField

validateAge y

| y < 18 = Left $ renderMessage master languages MsgUnderAge

| otherwise = Right y

The types shown correspond to an older version, but the philosophy remains.

The Handler monad returns content in one or more of several formats as components of types that implement the {{mono|HasReps}} class{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-core/latest/doc/html/Yesod-Content.html#t:HasReps |title=The class HasReps |publisher=Hackage.haskell.org |access-date=2012-10-23}} {{{mono|RepHtml, RepJson, RepXml, RepPlain}}, the dual {{mono|RepHtmlJson}}, a pair or list of pairs {{code|[(ContentType, Content)]}}, ..}.{{cite web |url=http://www.yesodweb.com/book/restful-content |title=RESTful Content |publisher=Yesodweb.com |access-date=2012-10-23}}{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-core/latest/doc/html/Yesod-Content.html#t:ToContent |title=The class ToContent |publisher=Hackage.haskell.org |access-date=2012-10-23}} Json examples:{{cite web |url=http://www.yesodweb.com/blog/2012/04/yesod-js-todo |title=More Client Side Yesod: todo sample |publisher=Yesodweb.com |date=2012-04-23 |access-date=2012-10-23}}{{cite web |url=http://www.yesodweb.com/book/json-web-service |title=JSON Web Service |publisher=Yesodweb.com |access-date=2012-10-23}}{{cite web |url=http://hackage.haskell.org/package/yesod-json |title=The yesod-json package |publisher=Hackage.haskell.org |access-date=2012-10-23}}

The {{mono|HasReps}} default implementation of {{mono|chooseRep}} chooses the document representation to be returned according to the preferred content-type list of the client {{mono|accept}} header.

• Widgets{{cite web |url=http://www.yesodweb.com/book/widgets |title=book - Widgets |publisher=Yesodweb.com |access-date=2012-10-23}} are HTML DOM code snippets made by specific commands (e.g. setTitle) or from templates of structure (HTML) / behaviour (JavaScript) / style (CSS), whose types instantiate the classes ToWidget, ToWidgetHead or ToWidgetBody.

A Widget monad,{{cite web |url=http://hackage.haskell.org/packages/archive/yesod-core/latest/doc/html/Yesod-Widget.html#t:GWidget |title=The widget monad |publisher=Hackage.haskell.org |access-date=2012-10-23}} based on a Writer{{cite web |url=http://www.haskell.org/haskellwiki/All_About_Monads#The_Writer_monad |title=The Writer monad |publisher=Haskell.org |access-date=2012-10-23}} one and argument to {{mono|defaultLayout}}, facilitate to piece the widgets together.

• the {{mono|hamlet}} quasiquoter (a parser to compile-time Template Haskell code){{cite web |url=http://www.haskell.org/ghc/docs/latest/html/users_guide/template-haskell.html#th-quasiquotation |title=Template Haskell Quasi-quotation |publisher=Haskell.org |access-date=2012-11-02}} specified in the T.H. Oxford brackets syntax [qq| ... |] introduces an indentation based structured html template. (See doc.).{{cite web |url=https://hackage.haskell.org/package/shakespeare/docs/Text-Hamlet.html |title=The hamlet template module |publisher=Hackage.haskell.org |access-date=2012-10-23}}

'$' prefixes lines of logic statements.

Automatic closing tags are generated only for the tag at line start position.

• the {{mono|whamlet}} quasiquoter returns a Widget expression. (saves to Widget before [hamlet|..|]).

toWidget [hamlet|

$doctype 5