Yesod (web framework)

Server interface

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

The foundation type

See ref.^[11] 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^[12] 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):

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

data MyApp = MyApp

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|

<!-- only the tag at the beginning of the line will be automatically closed -->
<!-- '.' prefix in tags introduces a class attribute -->
<!-- '#' prefix in tags introduces an id attribute -->
<!-- interpolation of haskell expressions follow the "shakespeare templates" #{expr} syntax -->

<p>Hello World! There are <span .box>#{length params} parameters</span>:
$if (not . null) params
    <ul>
         $forall param <- params
             <li>#{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

# 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

^[11]

Resources, routes and HTTP method handlers

See ref.^[13][14] 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

-- compound types must use an alias, eg. type Texts = [Text]
|]

• Applying the previous template generates the following route constructors:

-- interpolation of routes in templates follow the @{route_expr} syntax

data Route MyApp = 
    HomeR                    -- referenced in templates as: @{HomeR}
    | BlogR                  -- in templates: @{BlogR}
    | ArticleR ArticleId     -- in templates: @{ArticleR myArticleId}
    | BranchR Texts

• 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.^[13]

Authentication and authorization

See ref.^[15] Authentication plugins: OpenId, BrowserId, Email, GoogleEmail, HashDB, RpxNow.^[16]

Redirection after authentication.^[17]

Sessions

See ref.^[18] Session back-ends: ClientSession.^[19]

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

Subsites

See ref.^[20][21]

>> A subsite is a collection of routes and their handlers that can be easily inserted into a master site.^[20] It can host a workflow with a common url prefix.

Built-in subsites: Static,^[22][23] Auth^[24]

Template interpolation - Shakespearean templates

See ref.^[34] These are content view templates that follow a common substitution pattern of code expressions within curly brackets with different character prefix to refer to

template expressions with ^{...}

refers to other templates of the same type, with given parameters as ^{template params},

route expressions with @{...}

safe (typed) urls as @{HomeR},

message expressions with _{...}

i18n message rendering as _{MsgMessage params}

other Haskell expressions with #{...}

haskell expression rendering as #{haskell_expression} which type must be convertible

• • in case of hamlet html templates, the expression type must be an instance of Text.Blaze.ToMarkup^[35]
  • in case of css templates, the expression type must be an instance of Text.Cassius.ToCss^[36]
  • in case of javascript templates, the expression type must be an instance of Text.Julius.ToJavascript ^[37]
  • in case of i18n message definitions (in "<isoLanguage>.msg" files) with parameter interpolations, the expression type must be an instance of Text.Shakespeare.I18N.ToMessage ^[38]
  • in case of text/plain templates (for use in emails), the expression type must be an instance of Text.Shakespeare.Text.ToText ^[39]

Using non-English text in expressions requires use of the Unicode-aware type Text, since GHC's show for the type String renders non-ASCII characters as escaped numerical codes.

• external file templates: Template content can be loaded from external files using compile time splice calls as $(expr).^[40]
• reload mode for external files: See doc.^[34]

-- identifier, {' ', parameter, '@', type}, ":", text with interpolations
ArticleUnexistant param@Int64 : unexistant article #{param}

-- in code
myMsg :: MyAppMessage  -- datatype suffixing "Message" to the foundation type
myMsg = MsgArticleUnexistant myArticleId 
     
-- in templates
  _{MsgArticleUnexistant myArticleId}

toWidget [hamlet|
$doctype 5
<html>
    <!-- only the tag at the beginning of the line will be automatically closed -->
    <!-- '.' prefix in tags introduces a class attribute -->
    <!-- '#' prefix in tags introduces an id attribute -->
    <!-- interpolation of haskell expressions follow the "shakespeare templates" #{expr} syntax -->

    <head>
        <title>#{pageTitle} - My Site
        <link rel=stylesheet href=@{Stylesheet_route}>
    <body>
        <header>
           ^{headerTemplate}
        <section>
          <p><span style="font-weight:bold;">_{MsgArticleListTitle}</span>
          $if null articles
            <p>_{MsgSorryNoArticles}
          $else
            <ul>
                $forall art <- articles
                    <li>#{articleNumber art} .- #{articleTitle art}
        <footer>
          ^{footerTemplate}
|]

Navigation Breadcrumbs

• Navigation Breadcrumbs.^[51] You have to provide a YesodBreadcrumbs instance for the site where the generator function breadcrumb should return for each route a title and parent one. Then, the query function breadcrumbs will return the present route title and the ancestors' (route, title) pairs.

Search engine Sitemap

• Search engines XML Sitemaps,^[52] where sitemap returns an XML Sitemap as http response, with the routes we want the search engines to crawl, and attributes to instruct the crawler, from a provided list of SitemapUrl records.

Web feed views

• Web feed views (RSS / Atom).^[53] You have handlers that return RepRss, RepAtom, or dual RepAtomRss content (to be selected on accept headers' preferred content-type list) from a given Feed structure.

Using in-memory mutable data (in the foundation datatype)

E.g. a visitor count. See ref.^[54]

The Database layer

• persistent is the name of the database access layer with templates for generating types for entities and keys as well as schema initialization.^[55][56]

There is first class support for PostgreSQL, SQLite, MongoDB, CouchDB and MySQL, with experimental support for Redis.^[55]

The Database layout is described in a template listing the entities, fields and constraints.

• For every entity listed a record is generated were the record fields names are composed prefixing the field name to the entity name.

• For every entity listed an integer key column "id" is generated with autoincrement and primary index attributes, with a type alias suffixing Id to the entity name

• Added columns to existant tables must be given Default-column-value constraints for the migration procedure to succeed, with sql level notation.^[57]

automatic table creation, schema update and table migration

Modifications of the entities template produces an schema update with automatic table creation, and migration for the DBMS's that support "ALTER TABLE" SQL commands in a migrateAll procedure, generated from the template content. See "Migrations" in ref.^[55] to look for migration aware DBMS.

share [mkPersist sqlSettings, 
       mkMigrate "migrateAll"   -- generates the migration procedure with the specified name 
       ] [persist|

User                            -- table name and entity record type
                -- implicit autoincrement column "id" as primary key, typed UserId
    ident Text             -- refers to db. table column "ident"; 
                     -- generates a record field prefixing the table name as  "userIdent"
    password Text Maybe         -- Maybe indicates Nullable field
    UniqueUser ident            -- unique constraint with space sep. field sequence

Email
                -- implicit autoincrement column "id" as primary key, typed EmailId
    email Text
    user UserId                 -- foreign key
    verkey Text Maybe

    newlyAddedColumn Text "default='sometext'::character varying"  -- sql level Default constraint

    UniqueEmail email     -- unique constraint
|]

• Esqueleto: is a haskell combinators layer to generate correct relational queries to persistent.^[58]

Example for persistent rawSQL and Esqueleto queries.^[59]