[bunch of updates to the crash course
Jeremy Shaw <jeremy@seereason.com>**20100721185247
 Ignore-this: 569aecf07d7ed3b850cccdbc0b7f1e44
] addfile ./HelloBlaze.lhs
hunk ./HelloBlaze.lhs 1
+<!--
hunk ./HelloBlaze.lhs 3
+> {-# LANGUAGE CPP #-}
+
+-->
+
+<h2><a name="helloblaze">Using BlazeHtml</a></h2>
+<p class="warning">The contents of this section are based on the development version of Happstack which includes new functionality</p>
+<p>It is trivial to use <a href="http://jaspervdj.be/blaze/">BlazeHtml</a> with Happstack. Essentially you just use <code>toResponse</code> to convert the blaze <code>Html ()</code> type into a <code>Response</code>. For more detailed information on using BlazeHtml, see the <a href="http://jaspervdj.be/blaze/">BlazeHtml website</a>. The following example should get you started:</p>
+
+<div class="code">
+
+> {-# LANGUAGE OverloadedStrings #-}
+> module Main where
+>
+> import Happstack.Server
+> import           Text.Blaze ((!))
+> import qualified Text.Blaze.Html4.Strict as H
+> import qualified Text.Blaze.Html4.Strict.Attributes as A
+>
+> appTemplate :: String -> [H.Html ()] -> H.Html () -> H.Html ()
+> appTemplate title headers body =
+>     H.html $ do
+>       H.head $ do
+>         H.title (H.string title)
+>         H.meta ! A.http_equiv "Content-Type" ! A.content "text/html;charset=utf-8"
+>         sequence headers
+>       H.body $ do
+>         body
+>
+> helloBlaze :: ServerPart Response
+> helloBlaze = 
+>    ok $ toResponse $ 
+>     appTemplate "Hello, Blaze!" 
+>                 [H.meta ! A.name "keywords" ! A.content "happstack, blaze, html"] 
+>                 (H.p "hello, blaze!")
+>
+> main :: IO ()
+> main = simpleHTTP nullConf $ helloBlaze
+
+</div>
+<p class="source-code">[Source code for the app is <a href="HelloBlaze.hs">here.</a>]</p>
+
+<p>Now if we visit <a href="http://localhost:8000/">http://localhost:8000/</a>, we will get an html page which says:
+
+<pre class="code">
+hello ,blaze!
+</pre>
+
+<p>This example is pretty simple, but there are a few things to
+note:</p>
+
+<ul>
+ <li>The <code>appTemplate</code> function is purely BlazeHtml code and is in no way Happstack specific.</li>
+ <li>The existence of the <code>appTemplate</code> is purely a stylistic choice.</li>
+ <li>I have found it useful to set the content-type meta tag.</li>
+ <li>Happstack will automatically set the HTTP header <kbd>Content-Type: text/html; charset=UTF-8</kbd>. (BlazeHtml only supports UTF-8)</li>
+</ul>
hunk ./HelloWorld.lhs 35
+<p>To build the application run:</p>
+
+<div class="code">
+ $ ghc --make -threaded HelloWorld.hs -o helloworld
+</div>
+
+<p>The executable will be named <kbd>helloworld</kbd>.</p>
+
+<p>Alternatively, you can use <kbd>runhaskell</kbd> and avoid the compilation step.</p>
+
+<div class="code">
+ $ runhaskell HelloWorld.hs
+</div>
+
hunk ./HelloWorld.lhs 55
-<pre>
- happstack-crashcourse $ curl -v http://localhost:8000/
- * About to connect() to localhost port 8000 (#0)
- *   Trying ::1... Connection refused
- *   Trying 127.0.0.1... connected
- * Connected to localhost (127.0.0.1) port 8000 (#0)
- > GET / HTTP/1.1
- > User-Agent: curl/7.19.5 (i486-pc-linux-gnu) libcurl/7.19.5 OpenSSL/0.9.8g zlib/1.2.3.3 libidn/1.10 libssh2/0.18
- > Host: localhost:8000
- > Accept: */*
- > 
- < HTTP/1.1 200 OK
- < Connection: Keep-Alive
- < Content-Length: 13
- < Content-Type: text/plain; charset=UTF-8
- < Date: Fri, 09 Apr 2010 14:47:10 GMT
- < Server: Happstack/0.4.3
- < 
- * Connection #0 to host localhost left intact
- * Closing connection #0
+<div class="code"><pre>
+  $ curl http://localhost:8000/
hunk ./HelloWorld.lhs 58
-</pre>
+</pre></div>
hunk ./Makefile 8
-RQDATA_DEPS := RqDataLimiting.lhs
-RQDATA_DEMOS := HelloRqData.lhs RqDataError.lhs RqDataUpload.lhs 
-DEMOS := $(RQDATA_DEMOS) $(ROUTE_FILTER_DEMOS) $(HELLOWORLD_DEMOS)
+RQDATA_DEPS := RqDataLimiting.lhs RqDataParsing.lhs 
+RQDATA_DEMOS := HelloRqData.lhs RqDataError.lhs RqDataUpload.lhs RqDataRead.lhs RqDataFromData.lhs RqDataCheck.lhs RqDataCheckOther.lhs 
+TEMPLATES_DEPS :=
+TEMPLATES_DEMOS := HelloBlaze.lhs
+DEMOS := $(RQDATA_DEMOS) $(ROUTE_FILTER_DEMOS) $(HELLOWORLD_DEMOS) $(TEMPLATES_DEPS) $(TEMPLATES_DEMOS)
hunk ./Makefile 14
-SRC := $(MAIN) $(DEPS) $(ROUTE_FILTER_DEPS)
+SRC := $(MAIN) $(DEPS) $(ROUTE_FILTER_DEPS) $(DEMOS)
hunk ./Makefile 22
+Templates.html : $(TEMPLATES_DEPS) $(TEMPLATES_DEMOS)
hunk ./RqData.lhs 25
+#include "RqDataParsing.lhs"
hunk ./RqDataError.lhs 37
->              badRequest $ unlines ("The following request parameters are missing:" : e)
+>              badRequest $ unlines e
hunk ./RqDataError.lhs 49
-The following request parameters are missing:
-greeting
-noun
+Parameter not found: greeting
+Parameter not found: noun
hunk ./RqDataLimiting.lhs 7
-<h2><a name="rqdataerror">Limiting lookup to QUERY_STRING or request body</a></h2>
+<h2><a name="rqdatalimiting">Limiting lookup to QUERY_STRING or request body</a></h2>
addfile ./RqDataParsing.lhs
hunk ./RqDataParsing.lhs 1
+<!--
+
+> {-# LANGUAGE CPP #-}
+
+-->
+
+<h2><a name="rqdataparsing">Handling non-String request parameters</a></h2>
+
+<p>The <code>RqData</code> module provides a variety of ways to work with values besides <code>Strings</code>.</p>
+
+#include "RqDataRead.lhs"
+#include "RqDataCheck.lhs"
+#include "RqDataCheckOther.lhs"
hunk ./Templates.lhs 25
+ <dt>BlazeHtml</dt>
+   <dd><p>The BlazeHtml library provides combinators for generating HTML 4 and HTML 5 in Haskell.</p>
+    <p>pros:</p>
+     <ul>
+      <li>Claims to be fast (some benchmarks to back this up)</li>
+      <li>Use of combinators ensures output is always well-formed and free of typos in the names of elements and attributes</li>
+      <li>Automatic escaping of String values</li>
+      <li>Able to use the power of Haskell in your templates</li>
+      <li>Type-checked at compile time to ensure no template values are missing</li>
+      <li>Nice syntax (compared to the old html and xhtml libraries.)</li>
+     </ul>
+    <p>cons:</p>
+     <ul>
+      <li>Requires you to recompile in order to update the template</li>
+      <li>Makes it easy to mix the application logic and view code together, making it hard to update later (therefore you must have self control)</li>
+      <li>Only suitable for generating HTML documents</li>
+      <li>Not ideal for having templates written by a web designer who does not know Haskell</li>
+      <li>No compile-time assurances that generated html/xml is valid (though it will be well-formed).</li>
+      <li>The <code>Html</code> monad is not a real monad, nor is it a monad transformer. This eliminates some advantage usage possibilities.</li>
+     </ul>
+   </dd>
+
hunk ./Templates.lhs 54
+      <li>Automatic escaping of String values</li>
hunk ./Templates.lhs 65
-      <li>Not ideal for having templates written by a non-programming web designer (although the xml syntax helps)</li>
+      <li>Not ideal for having templates written by a web designer who does not know Haskell (although the xml syntax helps)</li>
+      <li>No compile-time assurances that generated html/xml is valid (though it will be well-formed).</li>
hunk ./Templates.lhs 69
-  <dt>BlazeHtml</dt><dd></dd>
hunk ./Templates.lhs 75
+
+#include "HelloBlaze.lhs"
+