Handlebars Quick
Simple extension for handlebars to get up and running within minutes and with no dependency on other libraries.
Background
Handlebars provides the power necessary to let you build semantic templates effectively with no frustration. This plugin makes using Handlebars easier than before.
This simple extension makes life easier for developers starting to use handlebars or for developers who simply need the tempting abilities of handlebars right out of the box.
What do you get?
Simply store your HTML template in a file, your specifications in a JSON file and ask Handlebars Quick to access them and apply the result to a DOM element.
You would not need jQuery or other libraries for AJAX or DOM manipulation.
Usage Example
v1.xusers of this plugin should refer to the upgrading section before upgrading.
<html>
<head>
<script src="handlebars.js"></script>
<script src="handlebars.quick.min.js"></script>
</head>
<body>
<div id="content"></div>
<script type="text/javascript">
Handlebars.quick.render('#content', '<div class="entry"><h1>{{title}}</h1><div class="body">{{body}}</div></div>', {
title: "My New Post",
body: "This is my first post!"
});
</script>
</body>
</html>The first parameter is the element selector to which the compiled template from second parameter will be rendered in
context of the specification object in third parameter. The selector can be an element id prefixed by # or a class
name prefixed by .. The selector can also be a tag name or an array of all the aforementioned combinations.
The selector parameter does not support full blown selection functionalities in order to reduce the weight and complexity of this library. You can pair
Handlebars.quickwith jQuery, Sizzle or other such libraries (or use nativequerySelectorAll) to achieve advanced selection capabilities.
Loading templates and spec JSON from files
In case you want to store your handlebars template and specifications in separate files, you may use the quickAsync
function to fetch them using AJAX.
<html>
<head>
<script src="handlebars.js"></script>
<script src="handlebars.quick.min.js"></script>
</head>
<body>
<div id="content"></div>
<script type="text/javascript">
Handlebars.quick.renderAsync('#content' 'template-filename', 'spec-filename', function () {
console.log('Handlebars.quick.renderAsync has completed its job!');
});
</script>
</body>
</html>Note that by default
Handlebars.quickexpects the template file's name to have a.hbsextension and the specification file to have.jsonextension. It also expects the file to stay in a path relative to the URL. You can configure these behaviours inHandlebars.quick.optionsobject.
An absolute URL can be provided to fetch content from a separate domain. One can also load just the template and pass an
object as the JSON spec.
Handlebars.quick.renderAsync('#content' 'template-filename', { title: 'sherlock', body: 'watson' }, function () {
console.log('Handlebars.quick.renderAsync has completed its job!');
});Loading partials from file
Handlebars.quick also allow you to load partials asynchronously from files. Using the registerPartialAsync and then
waiting for the callback to use the partials would do the trick.
Handlebars.quick.registerPartialAsync('partial-name', function () {
console.log('Handlebars.quick.registerPartialAsync has done its job!');
});Note that
Handlebars.quickexpects the partial file's name to start with an underscore (_) and this behaviour can be configured inHandlebars.quick.optionsobject.
Multiple partials can be loaded by passing the partial names as an array. The callback for completion of loading the
partials will be executed only once - after all partials in the array are loaded.
Handlebars.quick.registerPartialAsync(['partial-name-1', 'partial-name-2'], function () {
console.log('Handlebars.quick.registerPartialAsync has done its job!');
});Configuration options
The following is the default configuration object located at Handlebars.quick.options and it's default values. The
option names are likely to be self explanatory.
{
templatePath: '',
templateFileExtension: '.hbs',
partialPath: '',
partialFilePrefix: '_',
specPath: '',
specFileExtension: '.json'
}Installing Handlebars Quick
You can either download the latest release from GitHub or use bower to install the package. To download, simply follow
the latest release link on GitHub. To install the
package using bower, type bower install handlebars-quick in your project working directory using a terminal.
Upgrading from v1.x of this plugin to v2.x
Handlebars.quick 1.x users would need to modify their usage of this plugin since v2.0 introduces breaking changes.
You should upgrade only if you have the oportunity to change your codebase.
-
1.xused actual file references while2.xuses template and spec file names only. -
1.xaccepted all parameters as objects while2.xaccepts polymorphic parameters.
Happy Templating!
