Integrate an AngularJS application written in Javascript into the static subsite.

AngularJS is a javascript web framework for enhancing HTML to provide dynamic web applications. This module integrates an AngularJS application written in pure javascript into a Yesod application. (As of January 2014, there is some experiemental development work on Fay bindings to AngularJS, but unfortunately it is not currently usable.)

An AngularJS application consists of several pieces:

• Javascript code consisting of controllers, directives, and services attached to Angular modules. The goal of this javascript is to produce a domain specific language extending HTML. embedNgModule uses the static subsite to serve this javascript code, serving a minimized and compressed file during production and serving individual files during development.
• Directive Templates. In Angular, directives should be the only components which manipulate the DOM. This can happen in the directive javascript code or through a directive HTML template. embedNgModule supports templates written in Hamlet, converting the Hamlet to HTML at compile time before embedding the HTML into the generated javascript.
• The View. In Angular, the view is written in the DSL extending HTML. Normal Yesod Handlers and Widgets work great for the view (so nothing needed from this module). Note that your Yesod Widgets will not have any julius or attached javascript code, the javascript is entirely managed by embedNgModule.
• Testing. Angular makes testing (both unit and end-to-end) easy. For unit and mid-level testing, the normal Angular test runner karma is the best. hamletTestTemplate assists with integrating Hamlet directive templates into karma. For end2end testing, the Test.WebDriver.Commands.Angular module in the webdriver-angular package works well.

There is an example in the source code which shows an application, unit testing with karma, and end2end testing with webdriver.

This Haskell module assists with the management of Angular modules. Each Angular module cooresponds to a directory where each controller/directive/service/factory/etc. is located in separate files within this directory. For example, you might have files angular/myctrl.js, angular/somedirective.js, angular/myservice.js, and so on. Also, for each directive that does not use an inline template, you should have the corresponding directive template in a file with the same name as the javascript file but with a hamlet extension (e.g. angular/somedirective.hamlet). For larger applications, you can organize the Angular code into multiple Angular modules by using one directory per module.

All files with a .js extension in the given directory will be loaded. Each javascript file should be written to assume that a variable named module is already defined and holds the angular module. For example,

module.controller("MyController", function($scope) {
    $scope.hello = "Hello, World!";
});

When compiling for production, these .js files will be concatenated, combined with the code defining the module variable, DI annotated, minified, compressed, and then embedded into the executable to be served from the given location. That is, the following javascript will be automatically created:

(function(module) {

module.controller("MyController", ["$scope", function($scope) {
    $scope.hello = "Hello, world!";
}]);

<contents of all the other .js files>
<optionally contents of the directive templates (see below)>

})(angular.module("module-name", <contents of module-deps.json>));

Note the module-deps.json file: if this file exists within the directory, it will be parsed and used as the module dependencies (so therefore the contents should be a list of strings). If this file does not exist, an empty list of dependencies is used.

Note also the inline dependency injection annotation of the $scope parameter. When compiling for production, before running the minimizer, the javascript is parsed and DI parameters are annotated. The arguments to the top-level call to module.somefunction will be annotated. Also, if the call is module.directive, the body of the factory function will be scanned for a return of an object literal (must be an object literal, not a variable). The object literal is scanned for a controller property, and if found that controller property is also DI annotated (the example program shows this in action).

If a directive uses an external hamlet template, the directive hamlet and directive javascript should be in two files with the same name but .js and .hamlet extensions. To embed the directive template so that the javascript is able to find it, the template ID must be loaded. To do so, the javascript is parsed to find the value of templateUrl. The .js file must have a top-level call to module.directive. Some statement directly inside the factory function must be a return of an object literal. This object literal must have a templateUrl property with a single string literal as the value. This string literal is used as the ID when embedding the template. For example, if my-dialog.js contains

module.directive("my-dialog", function() {
    return {
        restrict: "E",
        transclude: true,
        templateUrl: "mydialog-template",
    };
});

then something like the following will be automatically created and then inserted into the generated file:

module.run(["$templateCache", function($templateCache) {
    $templateCache.put("mydialog-template", <rendered my-dialog.hamlet>);
}]);