A Haskell newbie's guide to the Snap framework

NOTE: the updated tutorial for Snap version 0.8 can be found here .

I've spent a bit of time working up a simple application in the Snap web framework.  This proved to be a bit of a challenge: the documentation for Snap is definitely a work in progress, and doesn't cater well to a Haskell newbie such as myself.  This account is intended to help others in my position get up to speed on Snap, by filling in some of the information that the tutorial's authors may have taken for granted.  It is not intended as a standalone introduction to Snap. If you want to use this document to help you learn Snap, I would suggest the following steps:

• Read the three Snap documents in the TUTORIAL section
• Read through this document
• Build an example application

Snap was absolutely easy to install and get running.  The API introduction walks you through creating a hello-snap app from scratch.  The app has a built-in HTTP server that serves a few simple web pages.  My goal was to create a web page that integrated data from a PostgreSQL database.  

Overview
A standard Snap application will consist of a few source files in /src and some HTML-related files in /resources and some other overhead files.  The only one of the overhead files I had to touch was the cabal file, and GHC told me when I needed to tweak that.  The HTML-related files that go in subdirectories of  /resources might consist both of straight HTML or CSS files, or Heist templates which Snap will build into HTML.  This all should be pretty obvious if you read the Snap intro.

Heist is a pretty slick templating system.  It lets you define your own tags which it expands when it renders a template.  A tag's definition can be either static text or a simple substitution, or you can call Haskell code via a Splice to get the text for a tag. 

I followed the instructions in the Heist tutorial for building some static templates, and all was fine.  When I tried to build a simple Splice, though, I had difficulty figuring out how to bind the splice tag into the template's list of tags.  The method used in the example application wasn't covered anywhere in the Heist tutorial, and the tutorial showed you how to set up a Heist state object containing the Splice but not how to use it.  I spent a lot of time trying the tutorial's method, when just a little more effort on the example's method got me success. Even there, I had one significant obstacle -- I got mentally stuck on the fact that the tutorial's way of binding the Splice returned a templateState value, while the method in the example code wants a function that takes a templateState and returns a template.  Here is more information about bindSplice.

A Splice that uses tag attributes

My first Splice was grabSQLwhereAttr, which used tag attributes to pass information from the Heist template to the Splice. The Splice then uses those attribute values in building an SQL query.  The result of that query is then used to build the Splice's return value, which Heist uses in rendering the template. 

The code to bind the Splice is

  my_template :: Application ()
    my_template= heistLocal templateSt $ render "cheese_template"
      where
        templateSt ts = bindSplices sqlSplices ts
        sqlSplices = [ ("get_sql_where_attr", grabSQLwhereAttr) ]

The new template gets routed properly by adding the italicized code below

  site  = route [ ("/",  index)
                , ("/cheese_template", my_template)
                ]
          <|> serveDirectory "resources/static"


And the Splice itself is defined via

  import qualified Data.Text as DT
  import qualified Text.XmlHtml as X

  grabSQLwhereAttr :: Splice Application
  grabSQLwhereAttr = do
    contents <- getParamNode 
    let column = getAttr contents "column" 
        key    = getAttr contents "key" 
        value  = getAttr contents "value" 
        table  = getAttr contents "table" 
    qval <- liftIO $ runQuery 
            $ bldQueryWhere column table key value 
    return $ [X.TextNode $ DT.pack $ qval] 

  getAttr :: X.Node -> DT.Text -> String
  getAttr x y = DT.unpack $ maybe (DT.pack "") id 
                                  (X.getAttribute y x)


getParamNode grabs the data from your Heist element; it is returned as  a Node object from Text.XmlHtml*. XmlHtml gives you a lot of ability to work with HTML; the docs have the details.  Here, we are grabbing the attributes from the get_sql_where_attr key.  The runQuery and bldQueryWhere code can be seen at Site.hs on github (the project is here). 

The Heist template that uses this Splice looks like

  <html>
  <head><title>Cheeses</title></head>
  <body>
  <get_sql_where_attr column="price" key="name" 
                      value="'dubliner'" table="cheese">
  </get_sql_where_attr>


The Splice code pulls out the attributes from the <get_sql_where_attr> tag, builds a query with them, runs the query, and takes the result text and substitutes it into the template in place of the tag.

A Splice that uses contents of child elements

The code above works fine, but the case-insensitive nature of HTML attributes limits it.  Let's refactor to use the contents of child elements instead (and allow any where clause in our SQL query):

  grabSQLwhere :: Splice Application
  grabSQLwhere = do
    contents <- getParamNode 
    let column = getChildText contents "column" 
        clause = getChildText contents "where_clause" 
        table  = getChildText contents "table" 
    qval <- liftIO $ runQuery 
            $ bldQueryWhereNew column table clause 
    return $ [X.TextNode $ DT.pack $ qval]
 
  getChildText :: X.Node -> DT.Text -> String
  getChildText x y = DT.unpack $ maybe (DT.pack "") id 
                                       (liftM X.nodeText tag)
      where tag = X.childElementTag y x


The template then becomes

  <html>
  <head><title>Cheeses</title></head>
  <body>
  <get_sql_where>
    <column>price</column>
    <key>name</key>
    <where_clause>name = 'dubliner'</where_clause>
   </get_sql_where>




Click here for Part 2 of this guide

*This took me some work to find out, as getAttribute comes up empty in Hoogle and the tutorial doesn't mention the return type.  A more experienced Haskeller would have dug this up quickly; for me it was good experience in navigating the Haskell information web.