grunt-asset-render
injects assets into templates
Getting Started
This plugin requires Grunt ~0.4.2
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-asset-render --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt;
The "asset_render" task
Quick Start!
Lets assume you want to link scripts into your HTML.
- start by creating an entry in your Gruntfile.
```js
grunt.initConfig({
asset_render: {
link_my_scripts: {
cwd: '../../path/to/my/website',
src: ['js/*.js', 'js/vendor/*.js'],
dest: '../path/to/my/website/index.html'
}
}
});
```
it's important to set your `cwd` to the path you want your resources to be relative to.
- next we need a template. here's mine
templates/scripts.handlebars
.
```handlebars
{{#files}}
<script src="{{file}}"></script>
{{/files}}
```
- lets update our configuration.
```js
grunt.initConfig({
asset_render: {
link_my_scripts: {
options: {
template: 'templates/scripts.handlebars',
inject: true,
},
cwd: '../../path/to/my/website',
src: ['js/*.js', 'js/vendor/*.js'],
dest: '../path/to/my/website/index.html'
}
}
});
```
- That's it. now you can do this.
```shell
grunt asset_render:link_my_scripts
```
-
Assuming you've included the
<!-- START -->
and<!-- END -->
tags in your html, your html will now look like:<!-- START --><!-- END -->....For more customization options, and mind-blowing features see below!
=====
Options
options.template (required)
Type: String
the path to your handlebars template.
options.inject
Type: Boolean
Default value: false
if this is true, templates will be merged into the destination file rather than overwriting it. Useful for linking assets (i.e, stylesheets, scripts, e.t.c)
options.promotions
Type: Array
Default value: []
useful if certain assets need to be prioritized over others. Read the section on promotions below.
Injection options.
The options below are only used when options.inject
is true
Read the sction on injection below.
options.delimiters
Type: String
Default value: '<!-- -->'
the injection engine uses these to locate opening and closing tags. note they are space separated.
options.start_word
Type: String
Default value: 'START'
the injection engine uses this to validate an opening tag.
options.end_word
Type: String
Default value: 'END'
the injection engine uses this to validate a closing tag.
Usage Examples
Rendering templates
In this example, we use a template to render several files.
Our template
templates/list_assets.handlebars
<ul>{{#files}} <li>{{file}}</li>{{/files}}</ul>
Our Task Configuration
Gruntfile.js
asset_render: render_to_file: options: template: 'templates/list_assets.handlebars' files: 'dest/my_scripts.html': 'js/**/*.js' 'dest/my_images.html': 'img/**/*{jpg,png,jpeg}' 'dest/my_documents.html': 'docs/budget/june2013.xls' 'docs/statements/*.pdf' '!docs/statements/*2012.pdf'
With the above configuration, the task will create several files. Lets look at one of them:
dest/my_images.html
img/me/myface.jpg img/icanhazcheezeburger.png
Injection
Rendering templates is already cool, but usually we want to include our templates into other files.
We can use the injection feature to achieve this. The injection engine examines the destination file for opening and closing
tags, by default '<!-- START -->'
and '<!-- END -->'
. The injection engine will replace the content of these tags with your template.
First we define our destination file.
dest/index.html
my image gallery <!-- START --> <!-- END -->
Then our template.
templates/thumbnails.handlebars
{{#files}} <div class="thumbnail"> <img src="{{file}}"> </div>{{/files}}
And finally remember to activate the inject
option.
Gruntfile.js
asset_render: my_cat_gallery: options: template: 'templates/thumbnails.handlebars' inject: true files: 'dest/index.html': 'gallery/cats/**/*'
The result is that our rendered template will be merged into the destination file, so:
my image gallery <!-- START --> <!-- END -->
Promotions
Sometimes the order that assets are rendered is important. For example if you are using a javascript library (i.e JQuery), you would like it to be added to your page before your script or plugins. Or if one stylesheet should override another. You get the idea.
Here is an example using JQuery.
asset_render: scripts: options: template: 'templates/scripts_include.handlebars' inject: true promotions: '**/jquery.js' '**/jquery.*' files: 'index.html': 'js/**/*.js'
In the above example we have two promotions.
'**/jquery.js'
this promotes JQuery'**/jquery.*'
this promotes JQuery plugins (i.e 'jquery.fittext.js')
This means that Jquery will be promoted to the top, then it's plugins, and finally all other scripts will come after.
Globing
you can use all the syntax you use to define source files. You can even do this:
asset_render: my_target: options: promotions: 'js/vendor/**/*.js' '!js/vendor/indipendent.js' // files
In the above case we want vendor styles to be priorotized but there's one that doesn't need to be prioritized; perhaps it runs on it's own. Just remember to enclose everything in an array []
.
Have fun, and keep it simple!
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt. All your work should be in the development branch.
Release History
v1.0 presenting grunt-asset-render!
v1.0.1 fixes
- fixed versioning
- updated docs
v2.0.0 new features
- now you can inject templates into other files
- support for asset re-ordering
- template context has changed
urls
is nowfiles
url
is nowfile
v2.0.1 better documentation
- fixed several typos
- added badges incicating health of the project
v2.0.2 maintainance
- updated dependencies