Web/Literature/Practical web programming in Haskell
This tutorial is under construction. Feel free to help out.
This tutorial aims to get you started with writing web applications in Haskell. We describe a relatively light-weight approach to Haskell web programming which uses a CGI library and an XHTML combinator library.
We think that while the approach we describe here is not as sophisticated or innovative as some other approaches, it is simple, portable and easy to understand if you are already familiar with web programming in other languages.
The tutorial starts with preliminaries such as how to install the necessary software and how to compile and run your web applications. We then show a number of working small example programs which introduce the basic features of the CGI and XHtml libraries. We then move on to how to use monad transformers to add application specific functionality such as sessions to the CGI monad, and how to create database-driven web applications. We also present FastCGI, and an approach to using dynamically loaded Haskell code.
1.1 Other Approaches
[Web Authoring System Haskell (WASH) . Domain-specific embedded language. Type-safe forms handling. Threads continuation through client. This gives good back-button and session splitting properties.
Haskell Application Server (HAppS) . Complete system including web server in one program. Uses XSLT for output.
Haskell Server Pages (HSP) . Uses preprocessor to make XML tags into Haskell expressions. Dynamic compilation.
1.2 Assumed Knowledge
This tutorial is not meant as an introduction to Haskell or web programming. We will assume that you have some familiarity with the following concepts:
This tutorial is not meant as a first introduction to Haskell. If you want to learn about Haskell in general, have a look at the list of books and tutorials. You may want to start with Haskell in 5 steps.
HTML (HyperText Markup Language) is the "the lingua franca for publishing hypertext on the World Wide Web. The XHtml library which we use in this tutorial produces XHTML 1.0, which is HTML 4.0 formulated as XML.
The combinators in the XHtml library do not make much sense unless you understand at least some parts of HTML.
2 Required software
2.1 Haskell compiler
GHC, the Glasgow Haskell Compiler, is the Haskell implementation that we will use in this tutorial. However, any Haskell implementation that supports Haskell98 and multi-parameter type classes should work.
2.2 Libraries: xhtml and cgi
If your Haskell implementation does not come with the xhtml and cgi packages, download them from HackageDB.
2.3 Web server
You need to have access to a web server on which you can run CGI programs. The most convenient way to do this when learning and developing is to run a web server on your development machine. If you run the programs on some other machine you need to make sure that you compile your programs so that they can run on that machine. This normally means that the machines must to have the same architecture and run the same operating system. Linking your applications statically by giving the flags -static -optl-static to GHC will avoid problems with missing libraries on the web server.
You could also use the Haskell Web Server.
3 Compiling and running web applications
Use GHC to produce a binary executable called prog.cgi from the Haskell source code file prog.hs:
ghc --make -package cgi -package xhtml -o prog.cgi prog.hs
Put the compiled program in the cgi-bin directory, or give it the extension .cgi, depending on the configuration of the web server.
Linking your applications statically by giving the flags -static -optl-static to GHC will avoid problems with missing libraries on the web server.
To run the compiled program, visit the URL of the CGI program with your web browser.
4 Simple Examples
4.1 Hello World
Here is a very simple example which just outputs some static HTML. The type signatures in this code are optional. We show them here for clarity, but omit them in some later examples.
import Network.CGI import Text.XHtml page :: Html page = body << h1 << "Hello World!" cgiMain :: CGI CGIResult cgiMain = output $ renderHtml page main :: IO () main = runCGI $ handleErrors cgiMain
page function constructs an HTML document which consists
of a body containing a single header element which contains the text
``Hello World. The CGI-action |cgiMain| renders the HTML document
as a string, and produces that string as output. The |main| function
runs |cgiMain|, using the normal CGI protocol for input and output.
It also uses |handleErrors| to output an error page in case |cgiMain|
throws an exception.
Fans of one-liners may like this version better (|handleErrors| has been omitted since this simple program will not throw any exceptions):
import Text.XHtml import Network.CGI main = runCGI $ output $ renderHtml $ body << h1 << "Hello World!"
Html is the type of HTML fragments. It comes from the
These are some of the important functions used in this example:
-- creates a string containing the HTML document. renderHtml :: Html -> String -- outputs a string as the body of the HTTP response. output :: String -> CGI CGIResult -- Catches any exception thrown by the given CGI action, returns an -- error page with a 500 Internal Server Error, showing the exception -- information, and logs the error. handleErrors :: CGI CGIResult -> CGI CGIResult -- Runs a CGI action which produces a CGIResult, using the CGI protocol -- to get the inputs and send the outputs. runCGI :: CGI CGIResult -> IO ()
4.2 HTML combinators
See also .
There are functions for all XHTML 1.0 elements. Some examples:
- header, body
- h1, h2, ...
<< operator is used for nesting HTML.
Attributes are added to tags using the
The function renderHtml (explain variants) produces a string containing the document.
4.3 Getting user input
This program shows a form which asks the user for her name. When the form is submitted, the program greets the user by name.
import Network.CGI import Text.XHtml inputForm = form << [paragraph << ("My name is " +++ textfield "name"), submit "" "Submit"] greet n = paragraph << ("Hello " ++ n ++ "!") page t b = header << thetitle << t +++ body << b cgiMain = do mn <- getInput "name" let x = maybe inputForm greet mn output $ renderHtml $ page "Input example" x main = runCGI $ handleErrors cgiMain
-- Get the value of an input variable, for example from a form. -- If the variable has multiple values, the first one is returned. getInput :: String -> CGI (Maybe String)
import Network.CGI import Text.XHtml import Control.Monad (liftM) import Data.Maybe (fromMaybe) hello :: Int -> Html hello 0 = h1 << "Welcome!" +++ p << "This is the first time I see you." hello c = h1 << "Welcome back!" +++ p << ("I have seen you " ++ show c ++ " times before.") page :: String -> Html -> Html page t b = header << thetitle << t +++ body << b cgiMain :: CGI CGIResult cgiMain = do c <- liftM (fromMaybe 0) $ readCookie "mycookie" setCookie (newCookie "mycookie" (show (c+1))) output $ renderHtml $ page "Cookie example" $ hello c main :: IO () main = runCGI $ handleErrors cgiMain
Here we use newCookie, setCookie and readCookie to store and retrieve a counter cookie in the browser. If you want to get the string value of a cookie, use getCookie instead of readCookie.
4.5 File uploads
FIXME: use a safer example
-- Accepts file uploads and saves the files in the given directory. -- WARNING: this script is a SECURITY RISK and only for -- demo purposes. Do not put it on a public web server. import Network.CGI import Text.XHtml import qualified Data.ByteString.Lazy as BS import Control.Monad (liftM) import Data.Maybe (fromJust) uploadDir = "../upload" fileForm = form ! [method "post", enctype "multipart/form-data"] << [afile "file", submit "" "Upload"] saveFile n = do cont <- liftM fromJust $ getInputFPS "file" let f = uploadDir ++ "/" ++ basename n liftIO $ BS.writeFile f cont return $ paragraph << ("Saved as " +++ anchor ! [href f] << f +++ ".") page t b = header << thetitle << t +++ body << b basename = reverse . takeWhile (`notElem` "/\\") . reverse cgiMain = do mn <- getInputFilename "file" h <- maybe (return fileForm) saveFile mn output $ renderHtml $ page "Upload example" h main = runCGI $ handleErrors cgiMain
We first output a file upload form, which should use the HTTP POST method, and the multipart/form-data content type. Here we seen an example of the use of HTML attributes, added with the ! operator.
For efficiency reasons, we use Data.ByteString.Lazy to represent the file contents. getInputFPS gets the value of an input variable as a lazy ByteString.
4.6 Error handling
handleErrors catches all exceptions and outputs a default error page with some information about the exception. You can write you own exception handler if you want to do something else when an exception is thrown. It can be useful to set the response code, e.g. 404.
4.7 Returning non-HTML
Of course we do not have to output HTML. Use setHeader to set the value of the Content-type header, and you can output whatever string you like.
4.8 Setting response headers
You can use the setHeader function to set arbitrary HTTP response headers. You can also set the response code, as seen above.
Example: output raw file data (with last-modified)
5 Going Further
This section explores some of possibilities beyond the basic web application programming.
5.1 Extending the CGI monad with monad transformers
CGI is not the only monad in which you can use the functions from the cgi package. MonadCGI is a class of CGI monads, and there is a CGIT monad transformer. You can use these together with your own monads for things like holding database handles, keeping track of session information etc.
FastCGI is a standard for CGI-like programs that are not restarted for every request. This reduces the overhead involved in handling each request, and reduces the servers response time for each request. The overhead involved in starting a new process for each request can also include the need to set up new DB connections every time. With FastCGI, DB connections can be reused.
Install FastCGI. Get a web server which can run FastCGI programs. Import Network.FastCGI. Use runFastCGI.
5.3 URL rewriting
5.4 Dynamic loading
6 Database-driven web-applications
6.1 Persistent DB connections with FastCGI
6.2 Web services
7 Existing Applications