Several things in Angular can be done in more than one way because Angular supports a whole range of
server and framework technologies. For the Angular code to be processed by the static generator
correctly, the Angular code must be written with the following points in mind (and these sometimes
conflict with example Angular code you find around the web). The haddock for
`Yesod.EmbeddedStatic.AngularJavascript` explains the format in detail.
* All controllers/directives/services/filters/etc. are attached to the Angular module by calling the
functions `module.controller` and `module.directive`, where we just rely on the static generator
setting up the `module` variable for us. (Angular supports controllers to just be javascript
functions, e.g. the very first example on the [AngularJS web page](http://angularjs.org), but this
is not allowed by the generator.)
* While not required, each controller/directive/service/filter is in its own file instead of
chaining them in a single file. This eases unit testing. The static generator automatically
combines all the files into a single file at compile time.
* Directive templates should either be written directly into the directive code in the `template`
setting (for short templates) or should be written in Hamlet and stored in a file with the same
name as the directive javascript file but with a `.hamlet` extension instead of `.js`. The
example uses Hamlet templates for both of the directives.
* The Hamlet directive templates do not use any variables/type-safe route interpolation. This
allows the HTML built from Hamlet to be automatically included directly into the generated
javascript file with no more handling required. (The templates are stuck into the Angular
`$templateCache`.)
* While the `Yesod.EmbeddedStatic.AngularJavascript` module has some support for Hamlet
templates with variable interpolation, it requires more complicated handling inside the
Haskell code. In my opinion, configuration, i18n messages, and routes (which would be what you
would probably be using Hamlet variable interpolation for) can just be stuck in a separate
Angular module not managed by the static generators. This separate Angular module can be
created in a widget and use variable/url interpolation, and it should just be a small module
just containing these config settings. The main Angular module (managed by the static
generator) can then depend on the config module and access the settings via dependency
injection.
* For directives with templates in Hamlet, the directive javascript code is in a specific format.
The factory function returns an object literal with keys `templateUrl` and `controller`. This
format allows the static generator to automatically process this directive code. The
`templateUrl` is required and used when processing the Hamlet, so that the template is stuck into
the correct key in the `$templateCache`. The `controller` property has its factory function
annotated for dependency injection.
* Dependency injection of the factory functions is done by naming the parameters to functions, e.g.
using `$scope` as the parameter name. No need to set an `$inject` property on the function or use
inline dependency annotation (an array of strings and the factory function). When compiling for
production, before javascript minification, the static generator will automatically add
annotations for you (so that when the minimizer renames parameter names the dependencies are still
injected).