-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/
-- | Yesod generators for embedding AngularJs code into yesod-static at compile time
--
-- yesod-static supports generators which run at compile time which
-- create static resources to embed directly into the executable. This
-- package leverages this to provide automatic management of
-- AngularJS code. During development individual files served and
-- reloaded on every request. When compiling for production, the files
-- are minimized, compressed, and then embedded into the executable.
@package yesod-static-angular
@version 0.1.8
-- | 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.
module Yesod.EmbeddedStatic.AngularJavascript
-- | Embed the javascript and directive templates from a single directory
-- into the static subsite as a single Angular module file. For this to
-- work, the directive templates cannot use any hamlet variable
-- interpolation.
--
-- During development, each .js file is served separately (with
-- some code to define the module variable) and at the location
-- where the combined file would appear during production, a small script
-- which just loads all the .js files from the directory is
-- served. This makes debugging much easier.
--
-- This generator produces one variable definition of type Route
-- EmbeddedStatic which is named by passing the location through
-- pathToName.
embedNgModule :: String -> Location -> FilePath -> (ByteString -> IO ByteString) -> Generator
-- | Embed multiple angular modules into the static subsite.
--
-- All subdirectories within the given directory are assumed to be
-- angular modules, and each subdirectory is embedded by calling
-- embedNgModule on it. The subdirectory name is used for the
-- module name. The location for the module will be the location given to
-- this generator combined with the subdirectory name and then
-- .js.
embedNgModules :: Location -> FilePath -> (ByteString -> IO ByteString) -> Generator
-- | Same as embedNgModule but the directive templates are not
-- included. Use this if your directive templates require variable/type
-- safe route interpolation. Your directive templates should then instead
-- be inserted into a WidgetT site IO () using
-- directiveTemplates and then embedded into the final page.
embedNgModuleWithoutTemplates :: String -> Location -> FilePath -> (ByteString -> IO ByteString) -> Generator
-- | Embed multiple angular modules without templates into the static
-- subsite. All subdirectories within the given directory are assumed to
-- be angular modules, and each subdirectory is embedded by calling
-- embedNgModuleWithoutTemplates on it.
embedNgModulesWithoutTemplates :: Location -> FilePath -> (ByteString -> IO ByteString) -> Generator
-- | Create a WidgetT site IO () which contains all the
-- directive templates written in Hamlet from the passed in directory.
-- This is only needed if you use embedNgModuleWithoutTemplates
-- because your directive templates use variable/url interpolation. The
-- template will be inside a <script type="text/ng-template"
-- id="someid">, where the ID is found by parsing the javascript
-- code for templateUrl. This widget must be inside the tag
-- which has the ng-app attribute.
directiveTemplates :: FilePath -> ExpQ
-- | Same as directiveTemplates but allows you to specify the hamlet
-- settings.
directiveTemplatesWithSettings :: HamletSettings -> FilePath -> ExpQ
-- | Wrap a widget in a <script type="text/ng-template"
-- id="someid"> block.
directiveWidget :: Text -> WidgetT site IO () -> WidgetT site IO ()
-- | Convert a hamlet file to javascript for unit testing.
--
-- When unit testing the Angular code, the javascript is executed
-- directly (without any processing by embedNgModule). But for the
-- directives to work, the Hamlet templates must still be converted to
-- javascript which inserts the template into the Angular
-- $templateCache. This TH splice takes a path to a hamlet file
-- and produces a ByteString which contains this javascript.
-- Before unit testing the javascript code, this TH splice must be run on
-- every directive hamlet template.
--
-- If you use karma, the karma-ng-hamlet2js-preprocessor
-- does this automatically by using runghc to run a small
-- Haskell script which calls hamletTestTemplate. The example
-- application uses this karma preprocessor.
hamletTestTemplate :: FilePath -> ExpQ