Speed up your AngularJS app by automatically minifying, combining, and automatically caching your HTML templates with
$templateCache
.
Here's an example of the output created by this task from multiple .html
files:
angular.module('app').run(["$templateCache", function($templateCache) {
$templateCache.put("home.html",
// contents for home.html ...
);
...
$templateCache.put("src/app/templates/button.html",
// contents for button.html
);
}]);
Then, when you use ng-include
or templateUrl
with $routeProvider
,
the template is already loaded without an extra AJAX request!
This plugin requires Grunt ~0.4.0
Usemin integration requires grunt-usemin ~2.0.0
Install the plugin:
$ npm install grunt-angular-templates --save-dev
Enable the plugin within your Gruntfile
:
grunt.loadNpmTasks('grunt-angular-templates');
Global namespace for Angular.
If you use angular.noConflict()
, then set this value to whatever you
re-assign angular to. Otherwise, it defaults to angular
.
Callback to modify the bootstraper that registers the templates with
$templateCache
.
By default, the bootstrap script wraps function($templateCache) { ... }
with:
angular.module('app').run(['$templateCache', ... ]);
If you want to create your own wrapper so you register the templates as an
AMD or CommonJS module, set the bootstrap
option to something like:
bootstrap: function(module, script) {
return 'module.exports[module] = ' + script + ';';
}
Name of
concat
target to append the compiled template path to.
This is especially handy if you combine your scripts using grunt-contrib-concat or grunt-usemin.
Object containing htmlmin options that will significantly reduce the filesize of the compiled templates.
Without this, the HTML (whitespace and all) will be faithfully compiled
down into the final .js
file. Minifying that file will only cut down
on the Javascript code, not the HTML within the strings.
Note - this does incur a performance cost. Simply leave out this option to prevent minificaiton.
I recommend using the following settings for production:
htmlmin: {
collapseBooleanAttributes: true,
collapseWhitespace: true,
keepClosingSlash: true, // Only if you are using SVG in HTML
removeAttributeQuotes: true,
removeComments: true, // Only if you don't use comment directives!
removeEmptyAttributes: true,
removeRedundantAttributes: true,
removeScriptTypeAttributes: true,
removeStyleLinkTypeAttributes: true
}
String
of theangular.module
to register templates with.
If not specified, it will automatically be the name of the ngtemplates
subtask (e.g. app
, based on the examples below).
String
to prefix template URLs with. Defaults to''
If you need to use absolute urls:
ngtemplates: {
app: {
options: {
prefix: '/'
}
}
}
If you serve static assets from another directory, you specify that as well.
Callback to modify the template's source code.
If you would like to prepend a comment, strip whitespace, or do
post-processing on the HTML that ngtemplates
doesn't otherwise do,
use this function.
Boolean to indicate the templates should be appended to dest instead of replacing it. Normally grunt-angular-templates creates a new file at
dest
. This option makes it append the compiled templates to thedest
file rather than replace its contents. This is just a useful alternative to creating a temporarydest
file and concatting it to your application.
Boolean indicated if the templates are part of an existing module or a standalone. Defaults to
false
.
false
, the module will look like angular.module('app')
, meaning app
module is retrieved.true
, the module will look like angular.module('app', [])
, meaning app
module is created.Callback to modify the template's
$templateCache
URL.
Normally, this isn't needed as specifying your files with cwd
ensures that URLs load via both AJAX and $templateCache
.
Path to
<!-- build:js [path/to/output.js] -->
usemin target
This should be the output path of the compiled JS indicated in your HTML,
such as path/to/output.js
shown here.
Use single or double quotes to wrap the template strings
Defaults to 'double', other option is 'single'
After configuring your ngtemplates
task, you can either run the
task directly:
$ grunt ngtemplates
Or, bake it into an existing task:
grunt.registerTask('default', [ 'jshint', 'ngtemplates', 'concat' ]);
Finally, you have to load the compiled templates' .js
file into your
application.
<script src="https://github.com/ericclemmons/grunt-angular-templates/raw/master/templates.js"></script>
concat
task:This is my personal preference, since you don't have to worry about what the destination file is actually called.
concat: {
app: {
src: [ '**.js', '<%= ngtemplates.app.dest %>' ],
dest: [ 'app.js' ]
}
}
Using the following HTML as an example:
<!-- build:js dist/vendors.js -->
<script src="https://github.com/ericclemmons/grunt-angular-templates/raw/master/bower_components/angular/angular.js"></script>
<script src="https://github.com/ericclemmons/grunt-angular-templates/raw/master/bower_components/angular-resource/angular-resource.js"></script>
<!-- endbuild -->
Do not use the concat
option, even though grunt-usemin generates a concat.generated
object behind the scenes. Instead, use the usemin
option to indicate the anticipated
output filepath from grunt-usemin.
ngtemplates: {
app: {
src: '**.html',
dest: 'template.js',
options: {
usemin: 'dist/vendors.js' // <~~ This came from the <!-- build:js --> block
}
}
}
Note: Earlier versions of grunt-usemin (correctly, in my opinion) would have generated
a concat['dist/vendors.js']
object for each build section in the HTML. Now,
because there's a single concat.generated
object with all JS/CSS files within it,
I'm back-tracking the proper concat
target for you.
app
Modulengtemplates: {
app: {
src: '**.html',
dest: 'templates.js'
}
}
Normally, your app, templates, & server are in separate folders, which means that the template URL is different from the file path.
ngtemplates: {
app: {
cwd: 'src/app',
src: 'templates/**.html',
dest: 'build/app.templates.js'
}
}
This will store the template URL as templates/home.html
instead of
src/app/templates/home.html
, which would cause a 404.
Simply pass the same options as the htmlmin
task:
ngtemplates: {
app: {
src: '**.html',
dest: 'templates.js',
options: {
htmlmin: { collapseWhitespace: true, collapseBooleanAttributes: true }
}
}
}
Or, if you already have an existing htmlmin
task, you can reference it:
ngtemplates: {
app: {
src: '**.html',
dest: 'templates.js',
options: {
htmlmin: '<%= htmlmin.app %>'
}
}
}
Suppose you only use ngtemplates
when on production, but locally you serve
templates via Node, sans the .html
extension.
You can specify a url
callback to further customize the registered URL:
ngtemplates: {
app: {
src: '**.html',
dest: 'templates.js',
options: {
url: function(url) { return url.replace('.html', ''); }
}
}
}
Some people like AMD & RequireJS and would like wrap the output in AMD or something else (don't ask me why!):
ngtemplates: {
app: {
src: '**.html',
dest: 'templates.js',
options: {
bootstrap: function(module, script) {
return 'define(' + module + ', [], function() { return { init: ' + script + ' }; });';
}
}
}
}
You will be able to custom everything surrounding $templateCache.put(...)
.
merge
option to allow templates to maintain directory structure if set to false
(#114)quotes
options to allow wrapping in single instead of double quotes (#142)cwd
when expand:true
cwd
being part of the $templateCache string when expand:true
(#134), Added verbose logging for minify (#136)html-minifier
to correct whitespace issues. (96)append
option to concat, not overwrite the dest
. (#89)usemin
option still creates file (#84)usemin
matching issue on Windows (#80)usemin
option form v0.4.10grunt-usemin
(#44)usemin
optionprefix
and support for URLs (#57)prefix
option for easier URL prefixes (#53)htmlmin
(#54)options.concat
targets on Windows convert /
to \\
. #48grunt-env
to change environments. Thanks to @FredrikAppelros (#20)htmlmin
a regular dependency. Thanks @rubenv (#37)htmlmin
option that supports both an { ... }
and <%= htmlmin.options %>
for existing tasks.module.define
, thanks to @sidwood (#28)noConflict
option to work with angular.noConflict, thanks to @mbrevoort (#26)concat
task when it's an array, thanks to @codefather (#23)Path
, thanks to @cgross (#19)concat
option for automatically adding compiled template file to existing concat
(or usemin
-created) task, thanks to @cgross (#17)module
option for setting which module the templates will be added to, thanks to @sidwood (#20)prepend
option for modifying final $templateCache
IDs, thanks to @mbarchein. (#16)myapp
) rather than being their own myapp.templates
module to be manually included, thanks to @geddesign. (#10)./bin/grunt-angular-templates
. No need for it!\\
to /
in template IDs (for on win32 systems) (#3)Copyright (c) 2013 Eric Clemmons Licensed under the MIT license.