Precompiling handlebars templates with custom helpers

HandlebarsTemplatesUsageGuide.md

Small guide on how to manage your Handlebars.js templates.

Be sure you are familiar with {{mustache}} templating techniques.

#Installation Install Handlebars npm package running this command:

npm install -g handlebars (installed node and npm required)

#Managing a template ###Basic approaches:

1. Directly in the Javascript file

var my_template_source = "<p>Hello {{user}}</p>";

2. A script tag in the HTML file:

<script id="my_template" type="text/x-handlebars-template">
  <p>Hello {{user}}</p>`
</script>

3. An individual file with filename.handlebars extension:

<p>Hello {{user}}</p>

Note: Best practive is to store the templates together in a separate folder (/js/templates)

#Compiling and Precompiling ##Compiling

var template_source = "<p>Hello {{user}}</p>"; //Template
var template_compiled = Handlebars.compile(template_source); //Compiling procedure
var template_result = template_compiled(data); //Passing the data to the compiled template
//Use template_result to render the block/page

##Precompiling

For example the folder hierarchy look like this

.
└──/templates 
  ├── main.handlebars
  ├── library.handlebars
  └── about.handelbars

Precompile a template using the following handlebars command:

handlebars <input> -f <output>
//Example: handlebars main.handlebars -f main_tmpl.js

Note: the file extension .handlebars is automatically stripped when compiling the templates.

Include the genereted main_tmpl.js

<script src="js/handlebars.js"></script>
<script src="js/templates/main_tmpl.js"></script>

Access the template from the script:

var main_page_tmpl = Handlebars.templates['main'];

When having a lot of templates the best option would be concatenating and precompiling them into one file.

handlebars -m templates/ > templates/templates.js

Note: -m flag stands for "minification"

Resulted templates.js would guarantee access to all the templates from the scripts in the folder.

##Precompiling with a helper

Precompile a template with a helper using the following command:

handlebars <input> -f <output> -k <helper>
//Example: handlebars about.handlebars -f about.tmpl.js -k unless -k with

Note: Use -k flag for every helper used: -k if -k each

##Precompiling with a custom helper It might happen that a custom helper is used. For example:

{{#whatever}}
 Do stuff
{{else}}
 Do other stuff
{{/whatever}}

I suggest storing custom helpers in a separate script file called customhelpers.js:

Handlebars.registerHelper("whatever", function () { ... });

Note: Don't forget to include this script

Precompile a specific template which uses a custom helper with the following command:

handlebars <input> -f <output> -k <helper>
//Example: handlebars main.handlebars -f main.tmpl.js -k customhelpers.js

Precompile a group of templates handlebars -m templates/ > templates/templates.js

I discovered that including the customhelpers.js script allows not to specify the custom helpers while precompiling procedure.