Lo-Dash AMD Template Loader
Created by Tim Branyen @tbranyen
RequireJS, Dojo, and Curl are excellent module loaders, but through the
flexibility of plugin architecture they should really be seen as resource
loaders.
We've come to expect our development environments to be raw and our builds to
be as optimized as possible. This plugin will fetch your Lo-Dash templates
during development and inline them in a production build.
Unlike requirejs-tpl it does not
use a hardcoded template function, but instead uses the exact one from your
copy of Lo-Dash. Consistency is a key difference here.
Almost every single article and tutorial on using client side templates with
AMD, will advocate the use of the RequireJS text! plugin. While this is a fine
tool for loading text, it is not optimized for templates. It requires the
duplicative act of compiling the templates before use in production.
Installing:
Bower:
bower install lodash-template-loader
NPM:
npm install lodash-template-loader
Alternatively you can download the loader.js
file and place anywhere in your
project.
Loading the plugin:
require.config({
paths: {
"ldsh": "path/to/lodash-template-loader/loader"
}
});
You must not end the path in .js
unless you are providing a url.
Examples:
vendor/libraries/loader
http://cdn.mysite.com/vendor/libraries/loader.js
Using:
Inside an AMD module you can now load templates like so:
define(["ldsh!path/to/template"], function(template) {
var contents = template({
});
});
The path to your templates directory can be configured as well as the default
extension to search for. More details below.
Configuring templateSettings:
There are a few default settings in place to make consumption easier.
The extension appended by default is .html
. The default root path is your
configuration's baseUrl
. No templateSettings
are configured by default.
To change these options, add the following to your configuration:
require.config({
lodashLoader: {
ext: ".html",
root: "/",
templateSettings: {}
}
});
What about Underscore?
I've decided to go with the compatible .source
attribute for obtaining the
template function source string, which makes this plugin work with Underscore
as well. You'll have to manually map the resource identifier which is
explained in detail below.
Mapping Underscore to Lo-Dash:
In order to use Underscore with this plugin, you must map the identifier.
Internally the plugin specifically looks for the identifier lodash
. In the
configuration simply:
require.config({
map: {
"*": {
"lodash": "underscore"
}
}
});
Using with Dojo:
Ensure Dojo's loader is in async
mode:
<script data-dojo-config="async:1" src="dojo/dojo.js"></script>
Set up your configuration:
require({
paths: {
"ldsh": "path/to/loader"
}
});
And Require in your template:
require(["ldsh!path/to/template"], function(template) {
var contents = template({
});
});
Using with Curl:
Set up your configuration:
curl.config({
paths: {
"ldsh": "path/to/loader"
}
});
And Curl in your template:
curl(["ldsh!path/to/template"], function(template) {
var contents = template({
});
});
Running tests
You will need Node.js and Grunt installed to run tests.
Clone this project, open the directory in a terminal, and execute the following
commands:
npm install
grunt
You can also run an http-server in the root and hit the tests directly. Since
XHR is used, tests must be run from a server.
Release notes:
2.0.0
1.0.1
- Fixes Dojo support and unit tests
1.0.0
- Reintroduced: SourceURL automatically attached
- Locked lodash to ~3 to avoid backwards breaking API
0.1.9
- Revert breaking change in
_.template
to reduce confusion
0.1.8
- Old IE support
- SourceURL automatically attached
0.1.7
- Removes Bower from install process in NPM.
- Makes Lo-Dash available in the render context.
0.1.6
- Ensure
root
option works as expected.
0.1.5
- Tests are now accurate.
- Fixed relative loading and conformance between Dojo, Curl, and RequireJS.
0.1.4
- Less restrictive handling of Lo-Dash version within Bower dependencies.
- Fixes edge case where an undefined baseUrl root would get a leading slash.
0.1.3
- Added RequireJS optimizer testing.
- Fixed bug with absolute URL fetching (double /).
0.1.2
- Resolved issue with baseUrl concatenation to moduleName.
0.1.1
- Hotfix for building in r.js projects.
0.1.0