Jump to content

Yesod web framework/View

100% developed
From Wikibooks, open books for an open world

The Handler monad returns content in one or more of several formats as components of types that implement the HasReps class[1] {RepHtml, RepJson, RepXml, RepPlain, the dual RepHtmlJson, a pair or list of pairs [(ContentType, Content)], ..}.[2][3] Json examples:[4][5][6]

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.[1]

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

Template interpolation - Shakespearean templates

[edit | edit source]

See ref.[10] 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[11]
    • in case of css templates, the expression type must be an instance of Text.Cassius.ToCss[12]
    • in case of javascript templates, the expression type must be an instance of Text.Julius.ToJavascript [13]
    • 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 [14]
    • in case of plain text templates, the expression type must be an instance of Text.Shakespeare.Text.ToText [15]

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).[16]
  • reload mode for external files: See doc.[10]
Localizable (i18n) messages
[edit | edit source]

See ref.[17] 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

-- in code
myMsg = MsgArticleUnexistant myArticleId 
     
-- in templates
  _{MsgArticleUnexistant myArticleId}

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.[18]

HTML-like templates
[edit | edit source]
  • the hamlet quasiquoter (a parser to compile-time Template Haskell code)[19][20] specified in the T.H. Oxford brackets syntax [qq| ... |] introduces an indentation based structured html template with '$' prefixed lines of logic statements (See doc.[10]).[21] Automatic closing tags are generated only for the tag at line start position.
  • the whamlet quasiquoter returns a Widget expression. (saves toWidget before [hamlet|..|]).
toWidget [hamlet|
$doctype 5
<html>
    <head>
        <title>#{pageTitle} - My Site
        <link rel=stylesheet href=@{Stylesheet_route}>
    <body>
        <div>
           ^{headerTemplate}
        <div>
          <p><span style="font-weight:bold;">_{MsgArticleListTitle}</span>
          $if null articles
            <p>_{MsgSorryNoArticles}
          $else
            <ul>
                $forall art <- articles
                    <li>#{articleNumber art} .- #{articleTitle art}
        <div>
          ^{footerHamletTemplate}
|]
JavaScript templates
[edit | edit source]
  • the julius quasiquoter: introduces a javascript template.[22] Javascript variants CoffeeScript and Roy-language[23] have also specific quasiquoters.[19][22]
toWidgetHead [julius|

var myfunc = function(){document.location = "@{SomeRouteR}";}

^{extraJuliusTemplate}
|]
CSS-like templates
[edit | edit source]
  • the cassius quasiquoter: introduces a css template with indentation based structuring.[24]
toWidget [cassius|
.box
    border: 1px solid #{myColor}
    background-image: url(@{MyImageR})

^{extraCassiusTemplate}
|]
  • the lucius quasiquoter: introduces a css template with standard syntax plus shakespeare-template style substitutions.[25]
toWidgetHead [lucius|
.box { border: 1px solid #{myColor} ;
       background-image: url(@{MyImageR}) ;
     }

^{extraLuciusTemplate}
|]
Plain text templates
[edit | edit source]
  • for e-mail or text/plain http content type.[26]
  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

[edit | edit source]
  • Search engines XML Sitemaps,[27] 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.[28] 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).[29] 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

[edit | edit source]
  1. a b "The class HasReps". Hackage.haskell.org. Retrieved 2012-10-23.
  2. "RESTful Content". Yesodweb.com. Retrieved 2012-10-23.
  3. "The class ToContent". Hackage.haskell.org. Retrieved 2012-10-23.
  4. "More Client Side Yesod: todo sample". Yesodweb.com. 2012-04-23. Retrieved 2012-10-23.
  5. "JSON Web Service". Yesodweb.com. Retrieved 2012-10-23.
  6. "The yesod-json package". Hackage.haskell.org. Retrieved 2012-10-23.
  7. "book - Widgets". Yesodweb.com. Retrieved 2012-10-23.
  8. "The widget monad". Hackage.haskell.org. Retrieved 2012-10-23.
  9. "The Writer monad". Haskell.org. Retrieved 2012-10-23.
  10. a b c "book - Shakesperean templates". Yesodweb.com. Retrieved 2012-10-23.
  11. "Class Text.Blaze.ToMarkup". Hackage.haskell.org. Retrieved 2012-10-23.
  12. "Class Text.Cassius.ToCss". Hackage.haskell.org. Retrieved 2012-10-23.
  13. "Class Text.Julius.ToJavascript". Hackage.haskell.org. Retrieved 2012-10-23.
  14. "Class Text.Shakespeare.I18N.ToMessage". Hackage.haskell.org. Retrieved 2012-10-24.
  15. "Class Text.Shakespeare.Text.ToText". Hackage.haskell.org. Retrieved 2012-10-24.
  16. "Template Haskell". haskell.org. Retrieved 2012-11-03.
  17. "book - Internationalization". Yesodweb.com. Retrieved 2012-10-23.
  18. mkMessage
  19. a b "HaskellWiki - QuasiQuotation". Haskell.org. 2012-05-26. Retrieved 2012-10-23.
  20. "Template Haskell Quasi-quotation". Haskell.org. Retrieved 2012-11-02.
  21. "The hamlet template module". Hackage.haskell.org. Retrieved 2012-10-23.
  22. a b "The Julius template module". Hackage.haskell.org. Retrieved 2012-10-23.
  23. "Roy language". Roy.brianmckenna.org. Retrieved 2012-10-23.
  24. "The Cassius template module". Hackage.haskell.org. Retrieved 2012-10-23.
  25. "The Lucius template module". Hackage.haskell.org. Retrieved 2012-10-23.
  26. "Shakespeare plain text templates module". Hackage.haskell.org. Retrieved 2012-10-24.
  27. "The yesod-sitemap package". Hackage.haskell.org. Retrieved 2012-10-26.
  28. "The YesodBreadcrumbs class". Hackage.haskell.org. Retrieved 2012-11-05.
  29. "The yesod-newsfeed package for RSS / Atom views". Hackage.haskell.org. Retrieved 2012-10-26.