grunt-ngindex

v0.1.4

Published

2 years ago

Generates index.html from template, linking js/css files and interpolating arbitrary vars.

Downloads

0High
0Medium
0Low

andrezero

grunt gruntplugin angularjs template

grunt-ngindex

Compiles index.html files from templates.

Getting Started

This plugin requires Grunt ~0.4.0.

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.

Install the plugin with this command:

npm install grunt-ngindex --save-dev

Add this line to your project's Gruntfile.js gruntfile:

grunt.loadNpmTasks('grunt-ngindex');

The "ngindex" task

Run this task with the grunt distjs command.

Task targets, files and options may be specified according to the grunt Configuring tasks guide.

Overview

This is a grunt multi-task that generates html files from templates, linking any number of js/css files and interpolating arbitrary vars.

It was built with AngularJS in mind and inspired by ngbp but it can probably be used in many other scenarios.

On top of that, an effort was made to streamline the process of generating multiple html files, to cater for apps that are segmented in independent modules and/or have specific needs for different environments or platforms.

Templating

Create one index.html file (or more). Following ng-boilerplate practices, the best place to store your template(s) is src/ but you may choose any directory as long as you configure the task accordingly.

You can find a good starting point in example/index.html inside this plugin directory.

The template syntax is the underlying Grunt Template Process, which uses Lo dash templates.

<!DOCTYPE html>
<html data-ng-app="exampleApp" data-ng-controller="appCtrl">
<head>
    <title><%= pkg.name %></title>
    <% if ('undefined' !== typeof cssFiles) { cssFiles.forEach( function ( file ) { %>
    <link rel="stylesheet" type="text/css" href="/<%= file %>" /><% }); } %>

</head>
<body>
    <header>
        <h1><%= pkg.name %></h1>
        <h2><%= foo.bar.baz %></h2>
    </header>

    <div class="view-container">
        <section data-ng-view="main" id="content"></section>
    </div>

    <% if ('undefined' !== typeof jsFiles) { jsFiles.forEach( function ( file ) { %>
    <script type="text/javascript" charset="utf-8" src="/<%= file %>"></script><% }); } %>

</body>
</html>

Configuration

Inside your Gruntfile.js file add a section called ngindex.

This section defines the default options, and the different files you want to generate.

Each target generates a single 'index.html' from a specific template, linking to a set of js and css files.

grunt.initConfig({

  ngindex: {

    options: {
      src: [
          'build/src/vendor/**/*.js',
          'build/src/lib/**/*.js'
      ],
      dest: 'build/',
      template: 'src/template.html',
      stripDir: 'build',
      vars: {
        pkg: grunt.file.readJSON('package.json')
      }
    },

    front: {
      src: [
          'src/front/**/*.js',
          'src/**/*.css'
      ],
      options {
        vars: {
          'foo': 'bar'
        }
      }
    },
    admin: {
      src: [
        'src/admin/**/*.js',
        'src/admin/**/*.*css'
      ]
    }
  }
}

Disclaimer

This being my first Grunt task, my feature wishlist was not framed within the Grunt configuration paradigm. Meaning that I built this thinking outside the box, a.k.a., as a total grunt noob.

You will see below that some of the target options EXTEND the the task options instead of OVERRIDING them.
Also, you can set a default dest in the task options which does not seem to be a common practice.

Once I figured these are not standard approaches, this is not how Grunt makes config available to a task when it's executed in a target context, I still checked a million Grunt plugins for similar use cases and couldn't actually find anything.

Yet, I find it very useful to be able to define a set of common src files and vars for all your index files and then extend that with target specific values so I'm keeping this for now. Feel free to comment on this project's issues.

Gotchas

The dest property must be a string. If it is an array, Grunt will fail when attempting to write the index file.

Options

_Note: the options declared per target will either OVERRIDE (template, dest and stripDir) or EXTEND (src and vars) the ones defined in the options property. See below for more details on each option.

options.template

Type: String

Default: 'src/index.html'

The path to the template file, relative to the project directory.

options.dest

Type: String

Default: 'build/index.html'

The path to the destination file, relative to the project directory.

options.src

Type: Array

Default: null

List of css and js files to link to. You can use the powerful grunt files here, including glob patterns and template substitution.

config = {

  ngindex: {

    index: {
      src: [
        '<%= files.vendor_js %>',
        'src/**/*.js',
        'src/*/*.*css'
      ]
    }
  }
};

The src option defined per target will merge with the value of src specified in the task options. This allows you to define a common set of files for all targets and then expand it per target.

NOTE: order matters and the base set of files will always preceed the target ones.

NOTE: duplicate files will always be removed.

NOTE: foreach entry in src that uses wildcards, only files that actually exist (relative to the project root) at the moment the task is executed will make it into the template. If no wildcards are used the files are not checked so you may be including files that don't exist. Open the generated file(s) in a browser and check for 404s.

options.vars

Type: Object

Default: '{}'

Any data you want to pass to the template. Ex:

config = {

  ngindex: {

    options: {
      vars: {
        foo: { bar: 'baz' }
      }
    }
  }
};

You can then use it in your template like this:

<span><%= foo.bar.baz %>/span>

The available data is always the result of deep extending any vars defined in the options property with any vars defined per target.

options.stripDir

Type: String|Array

Default: 'build/'

Strips the given prefix from the beginning of the paths of any matched files.

If your file list contains files inside the actual build folder, this will generate invalid links, since the app is served from within the acual build/ directory. Ex:

files: ['build/vendor/**/*.js']

In this case, you will want to use options.stripDir to strip build/ from every css and js file linked.

config = {

  ngindex: {

    options: {
      stripDir: 'build/'
    }
  }
};

You can also specify more than one path to strip. Ex: ['build/', 'dist/'].

Roadmap

Embedding css, javascript or arbitrary content in the template.

This will require another configuration option, a map that targets named regions in the template and defines the source of the content, this being a file or an ordered list of files.

Here's an example use case, where we are embeding:

css contents generated by a less task;
the raw contents of another html file;
the result of a grunt-template task that generates a costumized Google Analytics script.

config = {

  ngindex: {

    main: {
      src: [ ... ],
      options: {
        embed: {
          style: '<%= less.embed_css.dest %>',
          footer: '<%= files.html.production_footer %>',
          ga: '<%= ga_template.dest %>'
        }
      }
    }
  }
};

These vars would then be used in the templates like this:

<head>
<% if ('undefined' !== typeof embed.embed) { %><style><%= embed.style %></style><% } %>
...

</head>
<body>
<% if ('undefined' !== typeof embed.footer) { %><%= embed.footer %><% } %>

...

<% if ('undefined' !== typeof embed.ga) { %>
    <script type="text/javascript" charset="utf-8">
    <%= embed.ga %>
    </script>
<% } %>

</body>

Roadmap

test coverage for all configuration options

Credits and Acknowlegdments

All credits go to the ngbp project for seeding an index task in the boilerplate.

MIT License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

grunt-ngindex

Getting Started

The "ngindex" task

Overview

Templating

Configuration

Disclaimer

Gotchas

Options

options.template

options.dest

options.src

options.vars

options.stripDir

Roadmap

Embedding css, javascript or arbitrary content in the template.

Roadmap

Credits and Acknowlegdments

MIT License