Yesod (web framework)

src: post-engineering.com

Yesod (IPA: [je'sod]; Hebrew: ???????, "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 classes, entities, and dynamic content process functions, making use of Haskell compiled templates called QuasiQuotes, that admit code expression interpolations in web-like language snippets, making it fully type-checked at compile-time.

Video Yesod (web framework)

MVC architecture

Controller

Server interface

Yesod uses a Web application interface API, abbrev. 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 T.H. 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.

Skeleton app. extracted from next section, "Hello world" example (changes with newer yesod versions: the actual handler types have changed, but the philosophy remains):

WAI CGI Hello World

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.

Applying the previous template generates the following route constructors:

Handlers

For every 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.

Redirection after authentication.

Sessions

See ref. Session back-ends: ClientSession.

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

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

Built-in subsites: Static, Auth

Subsite Static

For every file in the "static" folder, a symbol with type (Route Static) is generated for reference, by means of a compile time splice call in the scaffold module StaticFiles.hs, that replaces non-identifier characters "/-." with underscores:

After adding static files, regenerate (::Route Static) symbols at the next recompilation, just updating the StaticFiles.hs date:

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

ArticleUnexistant param@Int64: unexistant article #{param}  

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" messagesFolder 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.

1. templates: lt: lazy text, st: strict text
2. templates for text with a left margin delimiter '|': lbt (lazy), sbt (strict)

  [lt| Mr./Mrs. #{fullName} ...   |]  

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.

Model

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

E.g. a visitor count. See ref.

Persistent

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

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.

• Default column values for added columns in automatic migrations.

Forms

See ref.

A form is a sequential (Applicative/Monadic) composition of fields for a sequential parsing of field inputs giving a pair as result: (FormResult: the parsing result, and xml: the view widget to use in the next rendering of the page including error msgs and marks for missing required fields).

The types of forms are Applicative (with tabular layout), Monadic (with free layout style) in the Yesod.Form.Functions module and Input (for parsing only) in the Yesod.Form.Input module.

Field definitions, which can be (a|m|i){- the form type -}(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 sent form field values as defaults. The method suffix is the form submission method used.
• while generateForm{Post|Get} ignores the web inputs and generates a blank 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:

See renderMessage signature.

Maps Yesod (web framework)

Other protocols

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.

src: i.ytimg.com

Development cycle

Getting started

Install haskellStack.

Scaffolding

• Packages not in the stackage repo, but in std. hackage should be referred in the "stack.yaml" extra-deps section.

• Customized packages, should be in a local subfolder and referred in the "stack.yaml" packages section.

Developing

Adding static files requires to unix touch the Settings/StaticFiles.hs module to generate the correspondent route symbols as explained.

• 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 it manually requires to add an import clause for the handler in Application.hs)

Logging for debug

See ref. The yesod scaffold uses "wai-extra" Network.Wai.Middleware.RequestLogger for request logging, although there are alternatives.

The package "monad-logger" brings T.H. generated logging functions with automatic inclusion of line location, which can be used in the monads Handler, Widget, PersistQuery, PersistStore, .. which are instances of MonadLogger.

The following "monad-logger" calls are also available from "yesod-core":

You can set per case log default by overriding the shouldLog method of the Yesod class instance for the site.

Deploying

See ref.

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

src: i.vimeocdn.com

Integration with JavaScript generated from functional languages

See ref.

from true GHC Haskell with hacked compilers having JavaScript backends

Haste and GhcJs offer alternatives that generate Javascript from the STG output phase of GHC admitting haskell code compilable with GHC. While GhcJs is more feature complete (concurrency, etc.), it requires and generates much more code than Haste.

Haste sample. Other examples at the ref.

Compiling:

Yesod widgets code:

Elm - reactive composition of web user interfaces

Elm is a novel functional reactive programming language (no callbacks) with Haskell like syntax (type annotations included) that compiles to Javascript, but with strict evaluation (top down evaluation, no where clauses), with simplified syntax (single pattern definitions, no guards), propagating events and changes from event sources through the dependency graph.

Elm role is not for adding JavaScript behaviour to existing elements, but to build up a variable html structure that recomposes itself in reaction to event streams.

Although it looks nice, JavaScript UIs are not search-engine friendly because the content not present in the first layout will probably not be indexed.

The Elm language has changed a lot. You can find a more recent description here.

src: i.ytimg.com

See also

• Happstack
• Snap (web framework)

src: i.ytimg.com

References

src: i.ytimg.com

External links

• Official website
• Presentations: InfoQ, Haskell eXchange 2012
• Slides: A.C.M. at Johns Hopkins Univ. - ReST-ful Websites with Yesod
• ScreenCast: Yesod 1.0 at Vimeo
• O'Reilly ebook - Developing Web Applications with Haskell and Yesod - Safety-Driven Web Development
• Q&A: StackOverflow.com - Yesod tagged Q&A

Blog tutorials

• FPComplete.com - My First Web Site, Playing with Routes and Links
• Yesod for newbies
• hamberg.no - handlerToIO: use forkIO in Yesod handlers

Comparisons

• HaskellWiki - Haskell web frameworks
• A Hopefully Fair and Useful Comparison of Haskell Web Frameworks
• Univ. of Kent - Comparing Dynamic and Static Language Approaches to Web Frameworks - Yesod vs Ruby on Rails

Other languages

• Haskell Biblio. - Yesod (in Spanish) Univ. of Cadiz

At GNU/Linux distributions

• Yesod at Debian
• Yesod at Ubuntu 12.04 "precise"

Source of the article : Wikipedia