ANN: happstack-lite - a friendly introduction to Happstack

Happstack is a powerful Haskell web framework with a rich API that has
evolved over the last 7 years to meet the needs of real world web
development.

Unfortunately a rich and flexible API can also be daunting when all
you need is something simple. What many people don't realize is that
inside Happstack lives a very simple and easy to use web framework.

I am pleased to announce a new member of the Happstack family:

happstack-lite.

happstack-lite is minimal version of Happstack that is designed give
you everything you need to get started with web develop in a much
cleaner, easier package. It is an ideal starting point for novice Haskell programmers or developers who are new to the Happstack family.

We have done that by:

 1. collecting the most essential types and functions into a single, well-documented module

 2. giving all the functions simple type signatures. No crazy monad
 transformers, far fewer type classes, etc.

 3. creating a new, small tutorial (less than 2000 words) that shows
 you how to use all the features of happstack-lite.

But, the best part is that happstack-lite is 100% compatible with regular Happstack. If you find you do need some of the extra features that Happstack offers, you can simply import the extra functions and use them. Migrating from happstack-lite to happstack is trivial -- mostly just changing `import Happstack.Lite` to `import Happstack.Server`. So, you are not locked into staying with happstack-lite if you decide you need more. And you can still use the many addon packages such as happstack-hsp or happstack-jmacro if you want.

happstack-lite is not crippled or underpowered. In fact, it offers features and performance on par with other Haskell frameworks while being as simple as possible. If you have ever looked at Happstack in the past and felt it was too complicated -- I would highly encourage to look again. Especially if the last time you looked was prior to Happstack 6.

Check out the tutorial here: happstack-lite.

We would love to hear your feedback and criticisms. Please see the related discussion at:

http://www.reddit.com/r/haskell.

Happstack + JMacro + HSX

Happstack (a Haskell web framework) has long had support for using HSX so that you can use XML syntax in your Haskell page templates. Happstack now has support for using JMacro to add javascript to your templates.

JMacro was written by Gershom Bazerman, and was first released in July of 2009. Our contribution is the creation of two glue libraries:

hsx-jmacro

a thin wrapper which makes it easy to embed JMacro into HSX (independent of Happstack).

happstack-jmacro

another thin wrapper that makes it easy to generate and serve JMacro .js scripts using Happstack

The use of Happstack+HSX+JMacro has been documented in detail in this section of the Happstack Crash Course.

Here is a little example of what Happstack+HSX+JMacro looks like:

> helloJMacro :: JMacroPart Response
> helloJMacro =
>     toResponse <$> defaultTemplate "Hello JMacro" ()
>       <div>
>        <% [$jmacro| 
>            var helloNode = document.createElement('h1');
>            helloNode.appendChild(document.createTextNode("Hello, JMacro!"));
>            document.body.appendChild(helloNode);
>            |] %>
>       </div>
>

As you can see, the syntax used by JMacro is almost identical to JavaScript. So, you do not have to learn some special DSL to use it. In fact, JMacro can work with most JavaScript you find in the wild. Using JMacro has a number of advantages over just using plain-old javascript:

• syntax checking ensures that your JavaScript is syntactically valid at compile time. That eliminates many common JavaScript errors and reduces development time.
• hygienic names and scoping automatically and transparently ensure that blocks of JavaScript code do not accidentally create variables and functions with conflicting names.
• Antiquotation, marshalling, and shared scope make it easy to splice Haskell values into the JavaScript code. It also makes it easy to programmatically generate JavaScript code.

The last point means that instead of trying to concat strings to call JavaScript functions with Haskell values like this:

hello str = <button onclick=("alert(" ++ str ++ ");")>click me</button>

You can write:

hello str = <button onclick=[$jmacro| alert(`(str)`); |]>click me</button>

The first version has a major bug -- it does not properly escape the str which can lead to javascript injection attacks. The JMacro version, on the other hand, automatically escapes the string.

You are not limited to just splicing strings and other primitive types into the JavaScript code. By creating an instance of ToJExpr you can easily pass any Haskell value to JavaScript.

While JMacro can easily be used for simple templating, it is actually a very powerful tool for generating JavaScript. It is essentially Template Haskell for JavaScript. It parses the JavaScript into an abstract syntax tree, and supports quasiquotation and antiquotation.

To learn more about using JMacro with Happstack and HSX, start reading here.

And a big thanks for Gershom Bazerman for creating JMacro. It's not part of Happstack or HSX, so you should have no problems using it with other web frameworks or templating libraries.