handlebars-template-loader

A Handlebars template loader for Webpack

###Installation
```bash npm install handlebars-template-loader ```
>Since version 0.5.4, this loaders does not include Handlebars in its dependency list. Make sure to install Handlebars before running webpack. Read https://github.com/npm/npm/issues/6565 for details.
###Usage
```javascript module.exports = { //...

module: {
    loaders: [
        { test: /\.hbs/, loader: "handlebars-template-loader" }
    ]
},

node: {
    fs: "empty" // avoids error messages
}

};

<br>
####Loading templates

<br>
```html
<!-- File: hello.hbs -->
<p>Hello&nbsp;{{name}}</p>

```javascript // File: app.js var compiled = require('./hello.hbs'); return compiled({name: "world"}); ```
####Using helpers
```javascript // File: helpers.js

// Get Handlebars instance var Handlebars = require('handlebars-template-loader').Handlebars;

Handlebars.registerHelper('list', function(items, options) { var out = "

";

for(var i=0, l=items.length; i<l; i++) { out = out + "

• " + options.fn(items[i]) + "
"; }

return out + "

"; });

Handlebars.registerHelper('link', function(text, url) { text = Handlebars.Utils.escapeExpression(text); url = Handlebars.Utils.escapeExpression(url);

var result = '' + text + '';

return new Handlebars.SafeString(result); });

<br>
```javascript
// File: main.js

// Include template helpers
require("./helpers.js");

####Prepending filename comment
When debugging a large single page app with the DevTools, it's often hard to find the template that contains a bug. With the following config a HTML comment is prepended to the template with the relative path in it (e.g. ``).

1module.exports = {
2    //...
3    
4    module: {
5        loaders: [
6            {
7                test: /\.hbs$/,
8                loader: "handlebars-template-loader",
9                query: {
10                    prependFilenameComment: __dirname,
11                }
12            }
13        ]
14    }
15};

####Images
In order to load images you must install either the `file-loader` or the `url-loader` package.

1module.exports = {
2    //...
3    
4    module: {
5        loaders: [
6            //...
7            { test: /\.hbs/, loader: "handlebars-template-loader" },
8            { test: /\.jpg/, loader: "file-loader" },
9            { test: /\.png/, loader: "url-loader?mimetype=image/png" },
10        ]
11    }
12};

```html ```
Images with an absolute path are not translated unless a `root` option is defined

1<!-- Using root = undefined => no translation -->
2<img src="/not_translated.jpg">
3
4<!-- Using root = 'images' => require('images/image.jpg') -->
5<img src="/image.jpg">

In order to deactivate image processing define the `attributes` option as an empty array.

1module.exports = {
2    //...
3    
4    module: {
5        loaders: [
6            {
7                test: /\.hbs$/,
8                loader: "handlebars-template-loader",
9                query: {
10                    attributes: []
11                }
12            }
13        ]
14    }
15};

You could also add which attributes need to be processed in the form of pairs *tag:attribute*.
```javascript module.exports = { //...

module: {
    loaders: [
        {
            test: /\.hbs$/,
            loader: "handlebars-template-loader",
            query: {
                attributes: ['img:src', 'x-img:src']
            }
        }
    ]
}

};

<br>
###Macros

<br>
Macros allow additional features like including templates or inserting custom text in a compiled templates.

<br>
####The *require* macro

<br>
The `require` macro expects a path to a handlebars template. The macro is then translated to a webpack require expression that evaluates the template using the same arguments.

<br>
```html
<h4>Profile</h4>

Name: <strong>{{name}}</strong>
<br>
Surname: <strong>{{surname}}</strong>
<div class="profile-details">
    @require('profile-details.hbs')
</div>

####The *include* macro
While the `require` macro expects a resource that returns a function, the `include` macro can be used for resources that return plain text. For example, we can include text loaded through the `html-loader` directly in our template.

1<div class="wiki">
2    <h3>Introduction</h3>
3    @include('intro.htm')
4    <h3>Authors</h3>
5    @include('authors.htm')
6</div>

####*br* and *nl*
The `br` and `nl` macros insert a `
` tag and a new line respectively. They accept a optional argument with the amount of strings to insert.

1<p>Lorem ipsum</p>
2@br(3)
3<p>Sit amet</p>
4@nl()

####Custom macros
We can include additional macros by defining them in the webpack configuration file. Remember that the value returned by a macro is inserted as plain javascript, so in order to insert a custom text we need to use nested quotes. For example, let's say that we want a macro that includes a copyright string in our template.
```javascript // File: webpack.config.js module.exports = { // ...

module: {
    loaders: {
        // ...
        { test: /\.hbs/, loader: "handlebars-template-loader" },
    }
},

macros: {
    copyright: function () {
        return "'<p>Copyright FakeCorp 2014 - 2015</p>'";
    }
}

}

<br>
We then invoke our macro from within the template as usual.

<br>
```html
<footer>
    @copyright()
</footer>

####Disabling macros
You can disable macros if you are a bit unsure about their usage or just simply want faster processing. This is achieved by setting the `parseMacros` options to false.
```javascript module.exports = { // ...

module: {
    loaders: {
        // ...
        {
            test: /\.hbs/,
            loader: "handlebars-template-loader",
            query: {
                parseMacros: false
            }
        },
    }
}

}

<br>
####Arguments

<br>
Macros can accept an arbitrary number of arguments. Only boolean, strings and numeric types are supported.

<br>
```javascript
// File: webpack.config.js
module.exports = {
    // ...

    module: {
        loaders: {
            // ...
            { test: /\.html$/, loader: "underscore-template-loader" },
        }
    },
    
    macros: {
        header: function (size, content) {
            return "'<h" + size + ">" + content + "</h" + size + ">'";
        }
    }
}

```html @header(1, 'Welcome')

Lorem ipsum

@header(3, 'Contents')

Sit amet

```
####Escaping
Macro expressions can be escaped with the `\` character.
```html @br(3) \@nl() @br() ```
Translates to
```html


@nl()
```
###License

Released under the MIT license.