# Yesod web framework/Printable version

The current, editable version of this book is available in Wikibooks, the open-content textbooks collection, at
https://en.wikibooks.org/wiki/Yesod_web_framework

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

## 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.
* Applying the previous template generates the following route constructors:
* 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):

## 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){- required or optional -}, have a fieldParse component and a fieldView one.
* 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.
The actual function parameters and types have changed through Yesod versions. Check the Yesod book and libraries signatures.
The magic is in the FormResult data type Applicative instance, where (<*>) collects the error messages for the case of FormFailure [textErrMsg] result values
Monadic forms permit free form layout and better treatment of hiddenField members.
A sample of an Applicative form:

## References

* ↑ "The wai package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "The wai-extra package with CGI WAI handler". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "The wai-handler-fastcgi package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "The wai-handler-scgi package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "The warp package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "The wai-handler-launch package". Hackage.haskell.org. Retrieved 2012-10-23.
* 1 2 "book - Basics". Yesodweb.com. Retrieved 2012-10-23.
* ↑ The mkYesod code
* 1 2 "book - Routing and Handlers". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "Playing with Routes and Links". FPComplete.com. 2012-10-17. Retrieved 2012-10-28.
* ↑ "book - Authentication and Authorization". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "The yesod-auth package". Hackage.haskell.org. Retrieved 2012-10-26.
* ↑ "book - Sessions - See section "Ultimate Destination"". Yesodweb.com. Retrieved 2012-11-17.
* ↑ "Sessions". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "Web.ClientSession". Hackage.haskell.org. Retrieved 2012-10-25.
* ↑ "ServerSession: secure modular server-side sessions". Hackage.haskell.org. Retrieved 2018-10-29.
* ↑ "Web.ServerSession.Frontend.Yesod". Hackage.haskell.org. Retrieved 2018-10-29.
* ↑ "Session Messages". Yesodweb.com. Retrieved 2018-10-23.
* ↑ "Creating a Subsite". Yesodweb.com. Retrieved 2012-10-25.
* ↑ "Yesod and subsites: a no-brainer". Monoid.se. 2012-08-22. Retrieved 2012-10-28.
* ↑ "The Magic of Yesod, part 2 - See section "Static Subsite"". Yesodweb.com. 2010-12-25. Retrieved 2012-10-25.
* ↑ "The package yesod-static - Static Subsite". Hackage.haskell.org. Retrieved 2012-10-25.
* ↑ "The package yesod-auth - Auth Subsite". Hackage.haskell.org. Retrieved 2012-10-25.
* 1 2 "book - Forms". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "Yesod.Form.Fields". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Yesod.Form.Functions runFormPost". Hackage.haskell.org. Retrieved 2012-10-25.
* ↑ "Yesod.Form.Types". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "HaskellWiki - Applicative functor". haskell.org. Retrieved 2012-10-24.

# View
### View

The Handler monad returns content in one or more of several formats as components of types that implement the HasReps class {RepHtml, RepJson, RepXml, RepPlain, the dual RepHtmlJson, a pair or list of pairs [(ContentType, Content)], ..}. Json examples:
The HasReps default implementation of chooseRep chooses the document representation to be returned according to the preferred content-type list of the client accept 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 defaultLayout, facilitate to piece the widgets together.

#### Template interpolation - Shakespearean templates

See ref. 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 ^{...}

    other templates of the same type 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
** in case of css templates, the expression type must be an instance of Text.Cassius.ToCss
** in case of javascript templates, the expression type must be an instance of Text.Julius.ToJavascript
** in case of i18n message definitions (in "isoLang.msg" files) with parameter interpolations, the expression type must be an instance of Text.Shakespeare.I18N.ToMessage
** in case of plain text templates, the expression type must be an instance of Text.Shakespeare.Text.ToText
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).
* reload mode for external files: See doc.

##### Localizable (i18n) messages

See ref. For every supported language ISO name there should be a file in the messages subfolder as <iso-language>.msg with entries like
For each entry in en.msg a message constructor is generated, prefixing the message name by "Msg", so the example msg. can be referred as
Actual i18n support is missing from the stack app template. You have to add the mkMessage "MyApp" directory isoLangDefault to the "Foundation.hs" file to get the messages instantiated.

##### HTML-like templates

* the hamlet quasiquoter (a parser to compile-time Template Haskell code) specified in the T.H. Oxford brackets syntax [qq| ... |] introduces an indentation based structured html template with '$' prefixed lines of logic statements (See doc.). Automatic closing tags are generated only for the tag at line start position.
* the whamlet quasiquoter returns a Widget expression. (saves toWidget before [hamlet|..|]).

##### JavaScript templates

* the julius quasiquoter: introduces a javascript template. Javascript variants CoffeeScript and Roy-language have also specific quasiquoters.

##### CSS-like templates

* the cassius quasiquoter: introduces a css template with indentation based structuring.
* the lucius quasiquoter: introduces a css template with standard syntax plus shakespeare-template style substitutions.

##### Plain text templates

* for e-mail or text/plain http content type.
* templates: lt: lazy text, st: strict text
* templates for text with a left margin delimiter '|': lbt (lazy), sbt (strict)

#### Specific views

* Search engines XML Sitemaps, 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.
* Navigation Breadcrumbs. You have to provide a YesodBreadcrumbs instance for the site where the generator function breadcrumb should return a title and parent route for each one. Then, the query function breadcrumbs will return the present route title and ancestors' (route, title) pairs.
* Web feed views (RSS / Atom). 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.

## References

* 1 2 "The class HasReps". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "RESTful Content". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "The class ToContent". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "More Client Side Yesod: todo sample". Yesodweb.com. 2012-04-23. Retrieved 2012-10-23.
* ↑ "JSON Web Service". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "The yesod-json package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "book - Widgets". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "The widget monad". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "The Writer monad". Haskell.org. Retrieved 2012-10-23.
* 1 2 3 "book - Shakesperean templates". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "Class Text.Blaze.ToMarkup". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Class Text.Cassius.ToCss". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Class Text.Julius.ToJavascript". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Class Text.Shakespeare.I18N.ToMessage". Hackage.haskell.org. Retrieved 2012-10-24.
* ↑ "Class Text.Shakespeare.Text.ToText". Hackage.haskell.org. Retrieved 2012-10-24.
* ↑ "Template Haskell". haskell.org. Retrieved 2012-11-03.
* ↑ "book - Internationalization". Yesodweb.com. Retrieved 2012-10-23.
* ↑ mkMessage
* 1 2 "HaskellWiki - QuasiQuotation". Haskell.org. 2012-05-26. Retrieved 2012-10-23.
* ↑ "Template Haskell Quasi-quotation". Haskell.org. Retrieved 2012-11-02.
* ↑ "The hamlet template module". Hackage.haskell.org. Retrieved 2012-10-23.
* 1 2 "The Julius template module". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Roy language". Roy.brianmckenna.org. Retrieved 2012-10-23.
* ↑ "The Cassius template module". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "The Lucius template module". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Shakespeare plain text templates module". Hackage.haskell.org. Retrieved 2012-10-24.
* ↑ "The yesod-sitemap package". Hackage.haskell.org. Retrieved 2012-10-26.
* ↑ "The YesodBreadcrumbs class". Hackage.haskell.org. Retrieved 2012-11-05.
* ↑ "The yesod-newsfeed package for RSS / Atom views". Hackage.haskell.org. Retrieved 2012-10-26.

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

E.g. a visitor count. See ref.

#### 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.
There is first class support for PostgreSQL, SQLite, MongoDB, CouchDB and MySQL, with experimental support for Redis.
The Database layout is described in a template listing the entities, fields and constraints.
* For every entity listed, an integer key column "id" is generated with autoincrement and primary index attributes, with a type alias appending Id to the entity name
* For every entity listed, a record type named as the entity is generated were record fields names are composed prefixing the entity name to the field name like "personName". An EntityField type "PersonName" is also generated for foreign key referencing from other entities.
* There is an automatic database schema migration mechanism for DB schema updates, which, to succeed, requires, when adding columns to existent tables, to specify Default-column-value constraints with sql level notation.
* "At most one" cardinality has a special mechanism around the type Checkmark.
* Weak entities (childs in life constrained owner-child relationships) have no special support for cascade delete triggers, but there are functions to deleteCascade manually in the Database.Persist.Class module.

##### 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. to look for migration aware DBMS.
* Esqueleto: is a haskell combinators layer to generate correct relational queries to persistent.
Example for persistent rawSQL and Esqueleto queries.

### E-mail

The following packages are part of the yesod-platform:
* email-validate: Validating an email address.
* mime-mail: Compose and send MIME email messages.

### Facebook

* Useful glue functions between the fb library and Yesod.

## Development cycle

New Yesod apps are generated from the HaskellStack tool templates, replacing previous command "yesod init"
Stack based app. template names are prefixed by yesod as "yesod-{minimal | postgres | sqlite | mysql | mongo | ...}"
* Since HaskellStack uses the stackage repo by default, extra packages from the hackage repo should be referred in the "stack.yaml" extra-deps section.
* You may customize packages to a local subfolder. They must be referred in the "stack.yaml" packages section.

### The "Yesod helper" tool

* The yesod helper tool
** yesod devel run from the project site, recompiles and restarts the project at every file tree modification.
** yesod add-handler adds a new handler and module to the project, adding an import clause for the handler in the "Application" module.

### Deploying with Keter: A web app server monitor and reverse proxy server

See refs.
Keter is a process as a service that handles deployment and restart of Yesod web app servers, and, per web app, database creation for PostgreSQL.
The console command yesod keter packs the web app. as a keter bundle for uploading to a keter folder named "incoming".
Keter monitors the "incoming" folder and unpacks the app. to a temporary one, then assigns the web app a port to listen to, and starts it.
Initially it worked with Nginx as reverse proxy (keter version 0.1*), adding virtual server entries to its configuration and making Nginx reload it, but now Keter itself provides its own reverse proxy functionality, removing Nginx dependency and acting as the main web server.
Old documentation (Nginx based).

## Integration with JavaScript generated from functional languages

See ref.

## References

* ↑ "Book - Initializing data in the foundation datatype". Yesodweb.com. Retrieved 2014-05-26.
* 1 2 3 "book - Persistent". Yesodweb.com. Retrieved 2012-10-23.
* ↑ "Yesod-persistent package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Yesod-persistent docs". github.com. Retrieved 2018-10-16.
* ↑ "Yesod-persistent entity syntax". github.com. Retrieved 2018-10-16.
* ↑ "Redundant migrations for fields' default values". GitHub.com. Retrieved 2012-12-04.
* ↑ ""At most one" cardinality enforcement in persistent with type Checkmark". Hackage.haskell.org. Retrieved 2018-10-16.
* ↑ "How can I create a foreign key constraint using Yesod/Persistent?". stackoverflow.com. Retrieved 2018-10-16.
* ↑ "esqueleto package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Query example at". Stackoverflow.com. 2012-09-19. Retrieved 2012-10-23.
* ↑ "The yesod package". Hackage.haskell.org. Retrieved 2019-06-26.
* ↑ "The email-validate package". Hackage.haskell.org. Retrieved 2012-10-26.
* ↑ "The mime-mail package". Hackage.haskell.org. Retrieved 2012-10-26.
* ↑ "The yesod-fb package". Hackage.haskell.org. Retrieved 2012-10-26.
* ↑ Haskell Stack - How to install
* ↑ The yesod-bin pkg with the helper tool (with instructions for use with the stack tool)
* ↑ "book - Deploying your Webapp". Yesodweb.com. Retrieved 2012-10-23.
* ↑ Readme.Md. "Yesod keter readme". GitHub. Retrieved 2012-10-23.
* ↑ "The keter package". Hackage.haskell.org. Retrieved 2012-10-23.
* ↑ "Keter updates". Yesodweb.com. 2012-10-25. Retrieved 2012-10-25.
* ↑ "Keter: Web App Deployment". Yesodweb.com. 2012-05-11. Retrieved 2012-10-23.
* ↑ "Keter: It's Alive!". Yesodweb.com. 2012-05-17. Retrieved 2012-10-23.
* ↑ "Javascript Options". github.com. Retrieved 2014-03-12.
* ↑ "Yesod, AngularJS and Fay". yesodweb.com. 2012-10-30. Retrieved 2014-03-12.
* ↑ "HaskellWiki - The JavaScript Problem". haskell.org. Retrieved 2014-04-12.