metalsmith-angular-templatecache

metalsmith-angular-templatecache

This plugin concatenates and registers AngularJS templates in $templateCache. The HTML is wrapped in JavaScript and a new JavaScript file is generated. This is a version of gulp-angular-templatecache that has been adjusted to work natively for Metalsmith. Because of this, it takes the same options as the well-used gulp version.

The JavaScript generated by this plugin, when beautified, looks similar to this.

angular.module("templates").run([
    $templateCache,
    function ($templateCache) {
        $templateCache.put("template1.html", "... escaped HTML content ...");
        $tempalteCache.put("template2.html", "... escaped HTML content ...");
        // etc.
    }
]);

Including the generated JavaScript in your app and AngularJS will use the $templateCache when available.

Note: This plugin will not create a new AngularJS module by default and will use a module called templates. If you would like to create a new module, set options.standalone to true.

Installation

Use npm to install this package easily.

$ npm install --save metalsmith-angular-templatecache

Alternately you may edit your package.json and add this to your dependencies object:

{
    ...
    "dependencies": {
        ...
        "metalsmith-angular-templatecache": "*"
        ...
    }
    ...
}

Example

Include this the same as any other Metalsmith plugin. Here's an example using the JSON format that also shows the default options. It is not necessary to specify any of these values unless you wish to change the defaults.

{
    "plugins": {
        "metalsmith-angular-templatecache": {
            "bufferEncoding": "utf8",
            "destination": "templates.js",
            "destinationMode": "0644",
            "match": "**/*.html",
            "matchOptions": {},
            "module": "templates",
            "moduleSystem": "",
            "removeSource": true,
            "root": "",
            "standalone": false,
            "templateBody": "... see below ...",
            "templateFooter": "... see below ...",
            "templateHeader": "... see below ...",
            "transformUrl": null
        }
    }
}

And this is how you would add the plugin using JavaScript. This example also includes a brief description of each option.

// Load this just like any other plugin.
var angularTemplatecache = require("metalsmith-angular-templatecache");

// Then in your list of plugins you use it.  Here, we use default options.
use(angularTemplatecache())

// Alternately, you can specify options. The values shown here are the
// defaults.
use(angularTemplatecache({
    // When converting file buffers to strings and strings back into
    // buffers, what encoding should be used?
    bufferEncoding: "utf8",

    // Name of the generated file.
    destination: "templates.js",

    // File permissions of the generated JavaScript file.
    destinationMode: "0644",

    // Pattern of files to match.
    match: "**/*.html",

    // Options for matching files. See minimatch for more information.
    matchOptions: {},

    // Name of the module.
    module: "templates",

    // Wrap the cache in the given module system.  Supported systems:
    // "RequireJS", "Browserify", "ES6", and "IIFE" (Immediately-Invoked
    // Function Expression).
    moduleSystem: null,

    // When true, this option will remove the source files (**/*.html)
    // when they are compiled into the JavaScript.
    removeSource: true,

    // Prefix for template URLs; prepended to the filename.
    root: "",

    // Create a new AngularJS module instead of using an existing module.
    standalone: false,

    // Controls how the templates are generated. This is given its own
    // section in the documentation.
    templateBody: "... see below ...",
    templateFooter: "... see below ...",
    templateHeader: "... see below ...",

    // Transform the generated URL before it's put into $templateCache.
    // Sample:
    //   transformUrl: function (url) {
    //       return url.replace(/\.tpl\.html$/, '.html');
    //   }
    transformUrl: null
})

This plugin uses minimatch to match files. The .matchOptions object can be filled with options that the minimatch library uses.

You will see that many options match up with gulp-angular-templatecache but not all of them align properly.

• base - Removed in favor of using metalsmith-move-remove.
• root - This is always prepended verbatim instead of using the path module to resolve a filename.

Template Generation

The templateHeader, templateBody and templateFooter options control how the JavaScript is generated to include the HTML templates in JavaScript. They are written in Mustache, unlike gulp-angular-templatecache. Newlines have been added here to help with readability.

templateHeader = "angular.module('{{{module}}}'{{#standalone}}, []{{/standalone}})
    .run(['$templateCache', function ($templateCache) {\n";
templateBody = "$templateCache.put('{{{uri}}}','{{{contentEscaped}}}');\n";
templateFooter = "}]);\n";

The JavaScript is assembled by building one header, one body section per included HTML file, then one footer.

License

This software is licensed under a MIT license that contains additional non-advertising and patent-related clauses. Read full license terms.