[More documentation on RqData
Jeremy Shaw <jeremy@seereason.com>**20100712232701
 Ignore-this: 4d38fef506c38c0cf15f5673ebbb14a7
] hunk ./HelloRqData.lhs 38
-<p>First we define a policy which limits the amount of data a client is allowed to send. We will cover policy creation in more detail later. But for now we will just use the default policy which takes four arguments:</p>
+<p>In the code, we first define a policy which limits the amount of data a client is allowed to send. We will cover policy creation in more detail later. But for now we will just use the default policy which takes four arguments:</p>
hunk ./HelloRqData.lhs 116
-<p><code>getDataFn</code> returns either a list of errors, or the succesfully extracted value. It is covered in more detail in the RqData error handling section.</p>
+<p><code>getDataFn</code> returns either a list of errors, or the successfully extracted value. It is covered in more detail in the RqData error handling section.</p>
hunk ./Makefile 8
-RQDATA_DEPS := 
-RQDATA_DEMOS := HelloRqData.lhs
+RQDATA_DEPS := RqDataLimiting.lhs
+RQDATA_DEMOS := HelloRqData.lhs RqDataError.lhs 
hunk ./RqData.lhs 22
+#include "RqDataError.lhs"
+#include "RqDataLimiting.lhs"
+
+<script type="text/javascript">var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
+              document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
+            </script><script type="text/javascript"
+    >var pageTracker = _gat._getTracker("UA-7111625-1");
+              pageTracker._initData();
+              pageTracker._trackPageview();
+            </script>
+ </body>
+</html>
addfile ./RqDataError.lhs
hunk ./RqDataError.lhs 1
+<!--
+
+> {-# LANGUAGE CPP #-}
+
+-->
+
+<h2><a name="rqdataerror">RqData Error</a></h2>
+
+<p>If we want to have better error reporting, we can make two changes to our <i>hello, rqdata,</i> app:</p>
+<ol>
+ <li>build the query using an applicative functor instead of a monad</li>
+ <li>use <code>getDataFn</code> instead of <code>withDataFn</code></li>
+</ol>
+
+<p>The following code has those two changes made:</p>
+
+<div class="code">
+
+> module Main where
+>
+> import Control.Applicative ((<$>), (<*>))
+> import Happstack.Server (ServerPart, badRequest, nullConf, ok, simpleHTTP)
+> import Happstack.Server.RqData (BodyPolicy, RqData, defaultBodyPolicy, look, getDataFn)
+>
+> myPolicy :: BodyPolicy
+> myPolicy = defaultBodyPolicy "/tmp" 0 1024 4096
+>
+> helloRq :: RqData (String, String)
+> helloRq =
+>     (,) <$> look "greeting" <*> look "noun"
+>
+> helloPart :: ServerPart String
+> helloPart =
+>     do r <- getDataFn myPolicy helloRq
+>        case r of
+>          (Left e) -> 
+>              badRequest $ unlines ("The following request parameters are missing:" : e)
+>          (Right (greet, noun)) ->
+>              ok $ greet ++ ", " ++ noun
+>
+> main :: IO ()
+> main = simpleHTTP nullConf $ helloPart
+
+</div>
+<p class="source-code">[Source code for the app is <a href="RqDataError.hs">here.</a>]</p>
+<p>Now if we visit <a href="http://localhost:8000/">http://localhost:8000/</a>, we will get the error:
+
+<pre class="code">
+The following request parameters are missing:
+greeting
+noun
+</pre>
+
+<p>If we had used the monad functions to build the RqData instead of the applicative functor functions, then we would have only seen that the <code>greeting</code> was missing. Then when we added a <code>greeting</code> we would have gotten a new error message saying that <code>noun</code> was missing.</p>
+
+<p>In general, improved error messages are not going to help people visiting your website. If the parameters are missing it is because a form or link they followed is invalid. There are two places where there error messages are useful:</p>
+<ol>
+ <li>When you are developing and debugging your site</li>
+ <li>Reporting errors to users of your web service API</li>
+</ol>
+
+<p>If you are providing a REST API for developers to use, they are going to be a lot happier if they get a detailed error messages instead of a plain old 404.</p>
addfile ./RqDataLimiting.lhs
hunk ./RqDataLimiting.lhs 1
+<!--
+
+> {-# LANGUAGE CPP #-}
+
+-->
+
+<h2><a name="rqdataerror">Limiting lookup to QUERY_STRING or request body</a></h2>
+
+<p>By default, <code>look</code> and friends will search both the
+QUERY_STRING the request body (aka, POST/PUT data) for a key. But
+sometimes we want to specify that only the QUERY_STRING or request
+body should be searched. This can be done by using the <code>body</code> and <code>queryString</code> filters:</p>
+
+<div class="code">
+#ifdef HsColour
+> body        :: RqData a -> RqData a
+> queryString :: RqData a -> RqData a
+#endif
+</div>
+
+<p>If we want to only look in the request body we could modified <code>helloRq</code> to be:</p>
+
+<div class="code">
+#ifdef HsColour
+> helloRq :: RqData (String, String)
+> helloRq =
+>     body ((,) <$> look "greeting" <*> look "noun")
+#endif
+</div>
+
+<p>We could also mix and match. In this varation we look in the QUERY_STRING for the <i>greeting</i> and the request body for the <i>noun</i></p>
+
+<div class="code">
+#ifdef HsColour
+> helloRq :: RqData (String, String)
+> helloRq =
+>     (,) <$> (queryString $ look "greeting") <*> (body $ look "noun")
+#endif
+</div>
+
+<p><code>queryString</code> and <code>body</code> act as filters on the data that is being searched. If you were to write:</p>
+
+<div class="code">
+#ifdef HsColour
+> helloRq :: RqData (String, String)
+> helloRq =
+>     body (queryString $ look "greeting")
+#endif
+</div>
+
+<p>This <code>RqData</code> would never match because the <code>body</code> filter would hide all the QUERY_STRING values, and the <code>queryString</code> filter would hide all the request body values, and hence, there would be nothing left to search.</p>
hunk ./Templates.lhs 52
-
+<p><a href="RqData.html">Next: Request parameters and data</a></p>