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