karma-ng-hamlet2js-preprocessor/README.md

A karma plugin to compile Hamlet HTML templates to JavaScript on the fly.

# Karma Hamlet Angular Preprocessor

This package provides a [Karma](http://karma-runner.github.io) preprocessor for
[Hamlet](http://www.yesodweb.com/book/shakespearean-templates) that converts the Hamlet templates
into javascript.  The javascript inserts the generated HTML into the
[AngularJs](http://angularjs.org) template cache.  It provides similar functionality as
[karma-ng-html2js-preprocessor](https://github.com/karma-runner/karma-ng-html2js-preprocessor).

The yesod-static-generators package has an [example
application](https://bitbucket.org/wuzzeb/yesod-static-generators/src/tip/examples/angular/?at=default)
using this preprocessor.

## Usage

First, configure Karma to use the preprocessor similar to the html2js preprocessor, i.e. inside
karma.js.conf

```
#!javascript
module.exports = function(config) {
    config.set({
        ...

        files: [
            ...
            "somedir/*.hamlet",
            ...
        ],

        plugins: [
            "karma-*",
        ],

        preprocessors: {
            ...
            "**/*.hamlet" : ["ng-hamlet2js"],
        },
    });
};
```

The preprocessor works by executing `runghc` with a short script which calls `hamletTestTemplate`
from the `Yesod.EmbeddedStatic.AngularJavascript` module from the
[yesod-static-angular](http://hackage.haskell.org/package/yesod-static-angular) package. This
package must either be installed globally, installed inside a cabal sandbox which is located in some
ancestor of the current directory, or runghc must be configured explicitly below.

# Configuration

Configuration options can be specified inside `karma.conf.js` inside a `ngHamlet2JsPreprocessor`
key, i.e.

```
#!javascript
module.exports = function(config) {
    config.set({
        ...
        ngHamlet2JsPreprocessor: {
            runghc: "/path/to/custom/runghc",
            ...
        },
    });
};
```

The following configuration options are supported:

* `runghc` *(string)* path to custom runghc executable.  Defaults to searching for runghc on the path.
* `packageDb` *(string)* path to a Haskell package database (which should contain the yesod-static-generators
  package).  If this option is not given, the current directory and then successive parent
  directories are searched for a `cabal.sandbox.config` file.  If a sandbox config file is found, it
  is parsed for the package database.  If no sandbox config file is found, no package database is
  used.
* `extraGhcArgs` *(array of strings)* list of extra arguments to pass to runghc.  These arguments
  are used in addition to the package database options.
* `hsProg` *(string)* the Haskell program to be given to runghc with `%s` in place of the Hamlet
  filename.  The program should read the hamlet from the given file and print the output onto
  standard output.  The primary intent of overriding this is if the Hamlet template uses
  variable/type safe route interpolation so that you need to define custom variables
  or setup before calling hamletTestTemplate.  The default program is the following:

```
#!haskell
import qualified Data.ByteString.Lazy as BL
import Yesod.EmbeddedStatic.AngularJavascript (hamletTestTemplate)
main = BL.putStr $(hamletTestTemplate "%s")
```