This page is under construction. Feel free to help out. If you make substantial edits, please add your name to the authors list at the bottom of this page, so that you can be credited if this is ever published in another medium.

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.

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: We assume knowledge of the following:

Haskell: 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 lists of books and tutorials. You may want to start with Haskell in 5 steps.

(X)HTML: 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.

CGI: CGI (Common Gateway Interface) programs are programs which run on the web server. They are given input which comes from the user's browser, and their output is given to the browser. To really understand how the CGI library works, you probably need to know a thing or two about CGI. (Tutorial.)

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.

cgi: This is a Haskell library for writing CGI programs. Download here.

A 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.

Use GHC to produce a binary executable called prog.cgi from the Haskell
source code file prog.hs:

ghc --make -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
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.

The 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):

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.

At this point, you should be able to create many useful CGI scripts. As your scripts get more ambitious, however, you may find yourself needing to pass "global" parameters to your CGI actions (e.g. database connections, session information.) Rather than explicitly passing these values around, you can extend the CGI monad to do this work for you.

The

Network.CGI.Monad

module defines a CGI monad transformer, allowing us to build a new monad that does everything the CGI monad does -- and more!
For example, let's define a new CGI monad that provides a database connection (in this example, we use the

Database.HSQL.PostgreSQL

module for our database.) Since it will be used by the CGI application, I'll call the new monad "App".

So now we have an App monad that gives us all the functionality of CGI, but also carries around a database connection. The last step is to define the function that creates the monad so we can run actions inside it.

There are times when you absolutely do not want to embed (X)HTML in Haskell. You can separate the code and the presentation (the Holy Grail of erm, web development). The code will be, well, Haskell, and the presentation will be buried inside templates. This might not be the case: fortunately, there is a very nice templating engine available: HStringTemplate; also very useful is hakyll, a simple static site generator library, mainly aimed at creating blogs and brochure sites.

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.

See Takusen and HDBC. If you would like to write queries in Haskell (and not SQL), see also HaskellDB, which integrates with HDBC.

FastCGI aren't restarted for each request, only the runFastCGI part is re-run. Everything (handles, datastructures etc.) you do outside of that loop will be persistent. However you need to handle errors yourself, because you're operating outside of handleErrors.