underscore-template-loader
Advanced tools
An Underscore.js and Lodash template loader for Webpack
npm install underscore-template-loader
Make sure you have the underscore or lodash package installed.
module.exports = {
//...
module: {
loaders: [
{ test: /\.html$/, loader: "underscore-template-loader" }
]
},
};
You can specify an engine to specify the library used when you call underscore methods inside the template if you don't want to rely on the global _ that is used by default.
module.exports = {
//...
module: {
loaders: [
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
engine: 'lodash',
}
}
]
}
};
<!-- File: hello.html -->
<p>Hello <%=name%></p>
var compiled = require('./hello.html');
return compiled({name: "world"});
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. <!-- view/user/edit.html -->).
module.exports = {
//...
module: {
loaders: [
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
prependFilenameComment: __dirname,
}
}
]
}
};
You can override the delimiters used to determine data to injected (HTML-escaped or not) or code to evaluate in the templates.
module.exports = {
//...
module: {
loaders: [
//...
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
interpolate: '\\{\\[(.+?)\\]\\}',
evaluate: '\\{%([\\s\\S]+?)%\\}',
escape: '\\{\\{(.+?)\\}\\}'
}
}
]
}
};
_.templateSettings.imports automatically includes variables or functions in your templates. This is useful when you have utility functions that you want to make available to all templates without explicitly passing them in every time the template is used.
<!-- File: hello.html -->
<p><%= greet(name) %></p>
var _ = require('lodash');
// Imports must be defined before the template is required
_.templateSettings.imports = {
greet: function(name) {
return 'Hello, ' + name + '!';
},
};
var compiled = require('./hello.html');
return compiled({name: "world"});
This is enabled by default when lodash is the engine used, but can be explicitly toggled using withImports option.
module.exports = {
//...
module: {
loaders: [
//...
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
withImports: true,
}
}
]
}
};
In order to load images you must install either the file-loader or the url-loader package.
module.exports = {
//...
module: {
loaders: [
{ test: /\.html$/, loader: "underscore-template-loader" },
{ test: /\.jpg$/, loader: "file-loader" },
{ test: /\.png$/, loader: "url-loader?mimetype=image/png" },
]
}
};
<!-- Require image using file-loader -->
<img src="img/portrait.jpg">
<!-- Require image using url-loader -->
<img src="img/icon.png">
Images with an absolute path are not translated unless a root option is defined
<!-- Using root = undefined => no translation -->
<img src="/not_translated.jpg">
<!-- Using root = 'images' => require('images/image.jpg') -->
<img src="/image.jpg">
In order to deactivate image processing define attributes as an empty array.
module.exports = {
//...
module: {
loaders: [
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
attributes: []
}
}
]
}
};
You could also add which attributes need to be processed in the form of pairs tag:attribute.
module.exports = {
//...
module: {
loaders: [
//...
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
attributes: ['img:src', 'x-img:src']
}
}
]
}
};
Dynamic attributes won't be afected by this behaviour by default.
<!-- Ignore "root" argument if attribute contains a template expression -->
<img src="/img/cat-<%- currentCat.url %>.png" class="cat-img">
In order to append the root directory you'll need to specify the parseDynamicRoutes argument.
module.exports = {
//...
module: {
loaders: [
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
root: "myapp",
parseDynamicRoutes: true
}
}
]
}
};
<!-- Attribute now translates to "myapp/img/cat-<%- currentCat.url %>.png" -->
<img src="/img/cat-<%- currentCat.url %>.png" class="cat-img">
Macros allow additional features like including templates or inserting custom text in compiled templates.
The require macro expects a path to a underscore template. The macro is then translated into a webpack require expression that evaluates the template using the same arguments.
<h4>Profile</h4>
Name: <strong><%=name%></strong>
<br>
Surname: <strong><%=surname%></strong>
<div class="profile-details">
@require('profile-details.html')
</div>
This macro also supports an object literal as an additional argument.
<div class="top-section">
@require('header.html', {"title": "First Section"})
</div>
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.
<div class="wiki">
<h3>Introduction</h3>
@include('intro.htm')
<h3>Authors</h3>
@include('authors.htm')
</div>
The br and nl macros insert a <br> tag and a new line respectively. They accept a optional argument with the amount of strings to insert.
<p>Lorem ipsum</p>
@br(3)
<p>Sit amet</p>
@nl()
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.
// File: webpack.config.js
module.exports = {
// ...
module: {
loaders: {
// ...
{ test: /\.html$/, loader: "underscore-template-loader" },
}
},
macros: {
copyright: function () {
return "'<p>Copyright FakeCorp 2014 - 2016</p>'";
}
}
}
We then invoke this macro from within the template as usual.
<footer>
@copyright()
</footer>
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.
module.exports = {
// ...
module: {
loaders: {
// ...
{
test: /\.html$/,
loader: "underscore-template-loader",
query: {
parseMacros: false
}
},
}
}
}
Macros can accept an arbitrary number of arguments of different types: boolean, strings, numbers an object literals are supported.
// 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 + ">'";
}
}
}
@header(1, 'Welcome')
<p>Lorem ipsum</p>
@header(3, 'Contents')
<p>Sit amet</p>
Macro expressions can be escaped with the \ character.
@br(3)
\@nl()
@br()
Translates to
<br><br><br>
@nl()
<br>
Released under the MIT license.
FAQs
An Underscore and Lodash template loader for Webpack
The npm package underscore-template-loader receives a total of 26,454 weekly downloads. As such, underscore-template-loader popularity was classified as popular.
We found that underscore-template-loader demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.