-- 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
--   <a>AngularJS</a> 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.
--   
--   <a>AngularJS</a> 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:
--   
--   <ul>
--   <li>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.
--   <a>embedNgModule</a> uses the static subsite to serve this javascript
--   code, serving a minimized and compressed file during production and
--   serving individual files during development.</li>
--   <li>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.
--   <a>embedNgModule</a> supports templates written in Hamlet, converting
--   the Hamlet to HTML at compile time before embedding the HTML into the
--   generated javascript.</li>
--   <li>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 <a>embedNgModule</a>.</li>
--   <li>Testing. Angular makes testing (both unit and end-to-end) easy.
--   For unit and mid-level testing, the normal Angular test runner
--   <a>karma</a> is the best. <a>hamletTestTemplate</a> assists with
--   integrating Hamlet directive templates into karma. For end2end
--   testing, the <a>Test.WebDriver.Commands.Angular</a> module in the
--   <a>webdriver-angular</a> package works well.</li>
--   </ul>
--   
--   There is an <a>example</a> 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 <tt>.js</tt> file is served separately (with
--   some code to define the <tt>module</tt> variable) and at the location
--   where the combined file would appear during production, a small script
--   which just loads all the <tt>.js</tt> files from the directory is
--   served. This makes debugging much easier.
--   
--   This generator produces one variable definition of type <tt>Route
--   EmbeddedStatic</tt> which is named by passing the location through
--   <a>pathToName</a>.
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
--   <a>embedNgModule</a> 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
--   <tt>.js</tt>.
embedNgModules :: Location -> FilePath -> (ByteString -> IO ByteString) -> Generator

-- | Same as <a>embedNgModule</a> 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 <tt>WidgetT site IO ()</tt> using
--   <a>directiveTemplates</a> 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
--   <a>embedNgModuleWithoutTemplates</a> on it.
embedNgModulesWithoutTemplates :: Location -> FilePath -> (ByteString -> IO ByteString) -> Generator

-- | Create a <tt><a>WidgetT</a> site IO ()</tt> which contains all the
--   directive templates written in Hamlet from the passed in directory.
--   This is only needed if you use <a>embedNgModuleWithoutTemplates</a>
--   because your directive templates use variable/url interpolation. The
--   template will be inside a <tt>&lt;script type="text/ng-template"
--   id="someid"&gt;</tt>, where the ID is found by parsing the javascript
--   code for <tt>templateUrl</tt>. This widget must be inside the tag
--   which has the <tt>ng-app</tt> attribute.
directiveTemplates :: FilePath -> ExpQ

-- | Same as <a>directiveTemplates</a> but allows you to specify the hamlet
--   settings.
directiveTemplatesWithSettings :: HamletSettings -> FilePath -> ExpQ

-- | Wrap a widget in a <tt>&lt;script type="text/ng-template"
--   id="someid"&gt;</tt> 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 <a>embedNgModule</a>). But for the
--   directives to work, the Hamlet templates must still be converted to
--   javascript which inserts the template into the Angular
--   <tt>$templateCache</tt>. This TH splice takes a path to a hamlet file
--   and produces a <a>ByteString</a> which contains this javascript.
--   Before unit testing the javascript code, this TH splice must be run on
--   every directive hamlet template.
--   
--   If you use <a>karma</a>, the <a>karma-ng-hamlet2js-preprocessor</a>
--   does this automatically by using <tt>runghc</tt> to run a small
--   Haskell script which calls <a>hamletTestTemplate</a>. The example
--   application uses this karma preprocessor.
hamletTestTemplate :: FilePath -> ExpQ
