karma-ng-jade2module-preprocessor

Preprocessor for converting Jade template files to AngularJS templates.

Note: If you are looking for a general preprocessor that is not tight to Angular, check out karma-html2js-preprocessor.

Installation

The easiest way is to keep @linagora/karma-ng-jade2module-preprocessor as a devDependency in your package.json.

{
  "devDependencies": {
    "karma": "~0.12",
    "@linagora/karma-ng-jade2module-preprocessor": "~0.5"
  }
}

You can simple do it by:

npm install @linagora/karma-ng-jade2module-preprocessor --save-dev

Configuration

// karma.conf.js
module.exports = function(config) {
  config.set({
    preprocessors: {
      '**/*.jade': ['ng-jade2module']
    },

    files: [
      '*.js',
      '*.html'
    ],

    ngJade2ModulePreprocessor: {
      // strip this from the file path
      stripPrefix: 'public/',
      // prepend this to the file path
      prependPrefix: 'served/',

      // or define a custom transform function
      cacheIdFromPath: function(filepath) {
        return cacheId;
      },

      // the locals object, eg:
      jadeRenderLocals: {
        __: function(str) {
          return str;
        }
      },

      // the configuration options that will be sent to jade render() method,
      // see Options section bellow, eg:
      jadeRenderOptions: {
        pretty: true
      },

      // DEPRECATED: the locals object, eg:
      jadeRenderConfig: {
        __: function(str) {
          return str;
        }
      },

      // setting this option will create only a single module that contains templates
      // from all the files, so you can load them all with module('foo')
      moduleName: 'foo'
    }
  });
};

Options

• basedir: string The root directory of all absolute inclusion.

• doctype: string If the doctype is not specified as part of the template, you can specify it here. It is sometimes useful to get self-closing tags and remove mirroring of boolean attributes.

• pretty: boolean | string Adds whitespace to the resulting HTML to make it easier for a human to read using ' ' as indentation. If a string is specified, that will be used as indentation instead (e.g. '\t'). Defaults to false.

• filters: object Hash table of custom filters. Defaults to undefined.

• self: boolean Use a self namespace to hold the locals. It will speed up the compilation, but instead of writing variable you will have to write self.variable to access a property of the locals object. Defaults to false.

• debug: boolean If set to true, the tokens and function body are logged to stdout.

• compileDebug: boolean If set to true, the function source will be included in the compiled template for better error messages (sometimes useful in development). It is enabled by default unless used with Express in production mode.

• globals: Array Add a list of global names to make accessible in templates.

• cache: boolean If set to true, compiled functions are cached. filename must be set as the cache key. Only applies to render functions. Defaults to false.

• inlineRuntimeFunctions: boolean Inline runtime functions instead of require-ing them from a shared version. For compileClient functions, the default is true so that one does not have to include the runtime. For all other compilation or rendering types, the default is false.

• name: string The name of the template function. Only applies to compileClient functions. Defaults to 'template'.

• __: function This i18n function is passed as a local argument for jade.compile

How does it work ?

This preprocessor converts Jade file into HTML files, and then into JS strings and generates Angular modules. These modules, when loaded, puts these HTML files into the $templateCache and therefore Angular won't try to fetch them from the server.

For instance this template.jade...

div something

... will be served as template.html. The underlaying code does a:

angular.module('foo', []).config(function($templateCache) {
  $templateCache.put('template.html', '<div>something</div>');
});

(foo comes from the moduleName configuration property).

So testing a directive that is declared like:

angular.module('example')
.directive('exampleDirective', function() {
  return {
    restrict: 'E',
    templateUrl: 'template.html'
  };
})

will have the template.jade injected !

For more information on Karma see the homepage.