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.

API

metalsmith-angular-templatecache

Metalsmith Angular $templateCache

Populates the $templateCache in Angular by converting the HTML templates into a single JavaScript file.

• metalsmith-angular-templatecache
  • module.exports([options]) ⇒ function ⏏
    • ~wrapInModuleSystem(moduleSystem, js) ⇒ string
    • ~processFileInfo(options, templateFile)
    • ~templateFile : Object
    • ~options : Object

module.exports([options]) ⇒ function ⏏

Factory to build middleware for Metalsmith.

Kind: Exported function Params

• [options] Object

module.exports~wrapInModuleSystem(moduleSystem, js) ⇒ string

Wraps JavaScript in a given module system's loader.

Kind: inner method of module.exports Params

• moduleSystem string
• js string

module.exports~processFileInfo(options, templateFile)

Takes a file info object and adds a couple properties.

.content = Buffer from reading the file .contentEscaped = File contents as an escaped string (not a Buffer) .filename = File's name from Metalsmith .uri = Generated from filename and options

Kind: inner method of module.exports Params

• options options
• templateFile templateFile

module.exports~templateFile : Object

A template file, which is typically an HTML file that is to be converted into JavaScript.

Kind: inner typedef of module.exports Properties

• content Buffer
• contentEscaped string - .content converted to a string and escaped for JavaScript.
• filename string - Filename from Metalsmith.
• uri string - Generated from filename and options.

module.exports~options : Object

Options controlling the middleware factory.

Kind: inner typedef of module.exports See: https://github.com/fidian/metalsmith-plugin-kit
Properties

• bufferEncoding string - Used when converting file buffers into strings.
• destination string - Destination file that will be generated from the HTML templates.
• destinationMode string - File permissions for the generated file.
• match module:metalsmith-plugin-kit~matchList - Files to match. Defaults to all *.html files.
• matchOptions module:metalsmith-plugin-kit~matchOptions - Options controlling the matching behavior.
• module string - Name of module that should have these templates.
• moduleSystem null | string - What module system to use. Can only be one of browserify, es6, iife, and requirejs. When falsy, this does not wrap in any module system.
• removeSource boolean - When truthy, the template files are removed from the build.
• root= string - Sets the root path to the templates. The path here is prepended to all of the paths of matched files.
• standalone boolean - When true, declares the module as a standalone module with no dependencies. Otherwise the module must be declared in other JavaScript.
• templateBody string - Controls how templates are added to the template cache. Mustache template.
• templateFooter string - How the generated JavaScript finishes. Mustache template.
• templateHeader string - How the generated JavaScript starts. Mustache template.
• transformUrl function - A function that changes the filename into a URL. The default function does not change the filename at all.

License

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