Yesod (web framework)

Yesod (; he, יְסוֺד, "Foundation") is a free and open-source web framework based on Haskell for productive development of type-safe, REST model based (where URLs identify resources, and HTTP methods identify transitions), high performance web applications, developed by Michael Snoyman et al.

Yesod is based on templates, to generate instances for listed entities, and dynamic content process functions, through Template Haskell constructs to host eDSL content templates called QuasiQuotes, where the content is translated into code expressions by metaprogramming instructions.

There are also web-like language snippet templates that admit code expression interpolations, making them fully type-checked at compile-time.

Yesod divides its functionality in separate libraries, so you may choose your functionality library of your choice.

MVC architecture

Controller

Server interface

Yesod uses a ''Web application interface'' API, abbreviated ''WAI'', to isolate servlets, aka web apps., from servers, with handlers for the server protocols CGI, FastCGI, SCGI, Warp, ''Launch'' (open as local ''URL'' to the default browser, closing the server when the window is closed),

The ''foundation'' type

See ref. Yesod requires a data type that instantiates the 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 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

"Hello world" example based on a CGI server interface (The actual handler types have changed, but the philosophy remains):

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"
/ HomeR GET
,
instance Yesod MyApp

-- indentation structured CSS template
myStyle :: ext→ CssUrl url
myStyle paramStyle =

.box
border: 1px solid #
, 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 # parameters:
$if null params

Nothing to list
$else

$forall param <- params

• #: #
  , ]

  
  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
  

  
  # 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
  
  

  
  

  Resources, routes and HTTP method handlers

  See ref.
  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: @
  , BlogR -- in templates: @
  , ArticleR ArticleId -- in templates: @
  , BranchR Texts -- in templates: @
  

  * 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
  
  

  
  

  Request data, Parameters, Cookies, Languages and other Header info

  See ref.
  

  
  

  Authentication and authorization

  
  See ref. Authentication plugins: OpenId, BrowserId, Email, GoogleEmail, HashDB, RpxNow.
  :There is an important setting for automatic redirection after authentication.
  

  
  

  Sessions

  
  See ref. Session back-ends: ClientSession (it stores the session in a cookie), ServerSession (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
  

  
  

  = Session messages

  =

  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.
  

  
  

  Subsites

  Common URL prefix subsites for workflows, file serving or site partitioning. See ref.

  Built-in subsites: Static, Auth
  

  
  

  Form processing and layout generation

  See ref.

  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), have a fieldParse component and a fieldView one.
  *the function runForm 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 ignores inputs from the client and generates a blank or defaults form widget.

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

  The magic is in the data type Applicative instance, where collects the error messages for the case of FormFailure extErrMsg/code> result values

  Monadic forms permit free form layout and better treatment of members.

  A sample of an ''Applicative'' form:

-- a record for our form fields
data Person = Person

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

  personForm :: MyFoundationType → ext→ Maybe Person → Form sub master Person

  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)
fldSettingsAge = fieldSettingsLabel MsgAge
fldSettingsLikings = (fieldSettingsLabel MsgLikings)

  customPersonAgeField = check validateAge intField

  validateAge y
, y < 18 = Left $ renderMessage master languages MsgUnderAge
, otherwise = Right y



  
  

  View

  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 class . Json examples:

  The default implementation of chooses the document representation to be returned according to the preferred content-type list of the client header.

  * Widgets 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, based on a Writer one and argument to , facilitate to piece the widgets together.


  
  

  Indentation based templates for tree structured markup

  * the quasiquoter (a parser to compile-time Template Haskell code) specified in the T.H. Oxford brackets syntax ... , /code> introduces an indentation based structured html template. (See doc.).

  '$' prefixes lines of logic statements.

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

  * the quasiquoter returns a Widget expression. (saves to Widget before .., .

  
toWidget [hamlet,
$doctype 5