grunt-asset-render

v2.0.2

Published

2 years ago

renders templates based on your assets

Downloads

0High
0Medium
0Low

kagia

template inject link publish gruntplugin

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.loadNpmTasks('grunt-asset-render');

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  and  tags in your html, your html will now look like:
```
<html>
 <head>
   
   <script src="js/myscript.js"></script>
   <script src="js/vendor/script.js"></script>
   
 </head>
<body>....</body>
</html>
```
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

<ul>
  <li>img/me/myface.jpg</li>
  <li>img/icanhazcheezeburger.png</li>
</ul>

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 '' and ''. The injection engine will replace the content of these tags with your template.

First we define our destination file.

dest/index.html

<html>
  <head>
    <title>my image gallery</title>
    <style>
    .thumbnail {float:left;}
    </style>
  </head>
  <body>
    <!-- START -->
    <!-- END -->
  </body>
</html>

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:

<html>
  <head>
    <title>my image gallery</title>
    <style>
    .thumbnail {float:left;}
    </style>
  </head>
  <body>
    <!-- START -->
    <div class="thumbnail">
      <img src="gallery/cats/socks_sleeping.jpg">
    </div>
    <div class="thumbnail">
      <img src="gallery/cats/socks_turning_away.jpg">
    </div>
    <!-- END -->
  </body>
</html>

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.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

grunt-asset-render

Getting Started

The "asset_render" task

Quick Start!

Options

options.template (required)

options.inject

options.promotions

Injection options.

options.delimiters

options.start_word

options.end_word

Usage Examples

Rendering templates

Injection

Promotions

Globing

Contributing

Release History

v1.0 presenting grunt-asset-render!

v1.0.1 fixes

v2.0.0 new features

v2.0.1 better documentation

v2.0.2 maintainance