mgcrea / grunt-nginclude

Grunt task for embedding AngularJS static ngInclude elements.

grunt-nginclude

Grunt task for embedding AngularJS static ng-include elements.

Getting Started

This plugin requires Grunt ~0.4.5

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-nginclude --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

grunt.loadNpmTasks('grunt-nginclude');

The "nginclude" task

Overview

In your project's Gruntfile, add a section named nginclude to the data object passed into grunt.initConfig().

grunt.initConfig({
  nginclude: {
    options: {
      discardReferencedFiles: false,
      parserOptions: {
        decodeEntities: false
      },
      replacementElementClass: '',
      replacementElementTag: 'span'
    }
  },
});

Options

options.discardReferencedFiles

Type: Boolean

Default value: false

Whether to discard referenced files on output or not.

Files that are explicitly referenced by ng-include directives are probably not referenced from any other place and don't need to be present on the output path neither on the template cache to be generated afterwards. To prevent those files from being added to the output there is this option that will discard referenced files when set to true.

options.parserOptions

Type: Object

Default value: {}

Enables parser options overrides.

For more information about available parser options check cheerio loading documentation or directly the options available in the htmlparser2 and domhandler.

options.replacementElementClass

Type: String

Default value: ''

CSS class to add to the elements replacing ng-include element directives.

If, for some reason, there is the need to add a class to the replaced ng-include element directive, it can be set with this configuration. This gives a way of identifying the replacement element or of adding extra styling to the new element.

By setting this option to 'nginclude-replaced', the following HTML

<ng-include ng-if="showPartial" src="'partial.html'"></ng-include>

would turn to

<span class="nginclude-replaced" ng-if="showPartial">partial contents</span>

options.replacementElementTag

Type: String

Default value: 'span'

HTML tag used to replace ng-include element directives.

As ng-include element directives can't just be removed because there might be some other attributes that need to be kept in order to be processed by angular or the browser, these elements must be replaced by other ones that have no special meaning for angular.

By setting this option to 'section', the following HTML

<ng-include ng-if="showPartial" src="'partial.html'"></ng-include>

would turn to

<section ng-if="showPartial">partial contents</section>

Usage Examples

Default Options

grunt.initConfig({
  nginclude: {
    options: {
      discardReferencedFiles: true
      parserOptions: {},
      replacementElementClass: 'nginclude-replaced',
      replacementElementTag: 'section'
    },
    your_target: {
      files: [{
        cwd: '<%= project.path.app %>'
        src: '**/*.html',
        dest: '<%= project.path.dist %>'
      }]
    },
  },
});

grunt-nginclude's Issues

Error: File 'file' not present in dictionary

I am trying to include the templates in an html file. There are two templates referenced in home.client.view.html. one of them is 'modules/core/views/templates/top-promoted-items.template.html'. My folder structure is:
modules
.core
..server
..client
....views
.....templates
......top-promoted-items.template.html
....home.client.view..html

the view file static path is defined in the express server. for example the file top-promoted-items.template.html is referenced as 'modules/core/views/templates/top-promoted-items.template.html'. Note that there is no '/client/' in the url. it is handeled by express. But when i tried to compile such views the grunt-nginclude gives the above error.

My nginclude config is below:
nginclude: { options: { discardReferencedFiles: true, parserOptions: {}, replacementElementClass: 'nginclude-replaced', replacementElementTag: 'section' }, your_target: { files: [{ cwd: process.cwd(), src: 'modules/core/client/views/home.client.view.html', dest: 'public/dist' }] } }

div's are being replaced instead of having content inserted since 0.4.1

Apparently, version 0.3.0 has the correct behaviour: includes are inserted into the ng-include tagged element.

As of 0.4.1, this behaviour is broken and the element containing the ng-include tag is replaced by the included template.

Behavior is different from AngularJS's ngInclude

The task removes the element with the ngInclude directive. This is not in line with AngularJS.

Example

Original file:

<body ng-controller="MainCtrl">
  <div ng-include="'fixtures/partial-1.html'" class="mydiv"></div>
</body>

AngularJS:

<body ng-controller="MainCtrl">
  <div ng-include="'fixtures/partial-1.html'" class="mydiv">
    <p>bar</p>
  </div>
</body>

This task:

<body ng-controller="MainCtrl">
  <!-- ngInclude: 'fixtures/partial-1.html' -->
    <p>bar</p>
</body>

The Problem

Because the original element goes missing, it can cause issues, like styling problems.

Unable to read file

I am trying to integrate this to my build process but can't seem to get it working.

Here is my config:

nginclude: {
      options: {
        discardReferencedFiles: false,
      },
      dist: {
        files: [{
          expand: true, 
          cwd: process.cwd(),
          src: 'modules/**/view/*.html',
          dest: 'dist/'
        }]
      },
    }

When I run grunt nginclude -v, I see all my html files loaded

Running "nginclude:dist" (nginclude) task
Verifying property nginclude.dist exists in config...OK
Files: /PATH_TO_MY_PROJECT/modules/foo/view/bar.html -> dist/modules/foo/view/bar.html

And so on, but after it loads all the files, I see this error:

Reading undefined/PATH_TO_MY_PROJECT/modules/foo/view/bar.html...ERROR
Warning: Unable to read "undefined/PATH_TO_MY_PROJECT/modules/foo/view/bar.html" file (Error code: ENOENT). Use --force to continue.

Aborted due to warnings.

It seems undefined/ is added before my filenames before processing happens.

$ grunt -V
grunt-cli v1.2.0
grunt v1.0.1

My dependencies:

"devDependencies": {
    "grunt": "^1.0.1",
    "grunt-assemble": "^0.5.0",
    "grunt-bump": "0.8.0",
    "grunt-contrib-clean": "^1.0.0",
    "grunt-contrib-concat": "^1.0.1",
    "grunt-contrib-copy": "^1.0.0",
    "grunt-contrib-cssmin": "^1.0.1",
    "grunt-contrib-htmlmin": "^2.0.0",
    "grunt-contrib-jshint": "^1.0.0",
    "grunt-contrib-sass": "^1.0.0",
    "grunt-contrib-symlink": "^1.0.0",
    "grunt-contrib-uglify": "^2.0.0",
    "grunt-contrib-watch": "^1.0.0",
    "grunt-ng-annotate": "^3.0.0",
    "grunt-nginclude": "^1.0.1",
    "grunt-preprocess": "^5.1.0",
    "grunt-sass": "^2.0.0",
    "grunt-usemin": "^3.1.1",
    "jshint": "^2.9.2",
    "ng-annotate": "^1.2.1"
  }

Recursion

The task is not recursive.

i.e., if file foo.html includes bar.html, which includes baz.html, the ng-include tags in bar.html won't be parsed.
As a result, we'll still have a ng-include tag referencing baz.html.