❤
npm
Sign UpSign In

grunt-asset-render

2.0.2 • Public • Published

grunt-asset-render

injects assets into templates

Build Status

NPM

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.

  1. 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.
  1. next we need a template. here's mine templates/scripts.handlebars.
```handlebars
{{#files}}
<script src="{{file}}"></script>
{{/files}}
```
  1. 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'
    }
  }
});
```
  1. That's it. now you can do this.
```shell
grunt asset_render:link_my_scripts
```

  1. Assuming you've included the <!-- START --> and <!-- END --> tags in your html, your html will now look like:

    <html>
     <head>
       <!-- START -->
       <script src="js/myscript.js"></script> 
       <script src="js/vendor/script.js"></script> 
       <!-- END -->
     </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 '<!-- 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

<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.

  1. '**/jquery.js' this promotes JQuery
  2. '**/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 now files
    • url is now file

v2.0.1 better documentation

  • fixed several typos
  • added badges incicating health of the project

v2.0.2 maintainance

  • updated dependencies

Readme

Keywords

Package Sidebar

Install

npm i grunt-asset-render

Repository

github.com/kagia/grunt-asset-render

Homepage

github.com/kagia/grunt-asset-render

Weekly Downloads

2

Version

2.0.2

License

none

Last publish

Collaborators

  • kagia
Try on RunKit
Report malware