Handlebars: How to use templates

Handlebars supports multiple templates in the same Single Page Application. To use templates with Handlebars, you must define a template id in the opening Handlebars script tag. For example, in this case the name of the template is “verse-set-grid”:

<script id="verse-set-grid" type="text/x-handlebars-template">

The pattern for a template is:

<!-- 1. Opening script tag with the name of the template set in the id -->
<script id="verse-set-grid" type="text/x-handlebars-template">

<!-- 2. The body of the template where all of the Handlebars substitutions are made. -->
...
...

<!-- 3. The closing script tag -->
</script>

Here is a complete template example. Inside the < script > tags is the handlebars template definition. Somewhere else on the page, in this case following the template definition, is the target div (called “verse-set-grid” ). When the handlebars template is compiled it will be placed inside the specified target div.

<!-- BEGIN verse-set-grid template -->
<script id="verse-set-grid" type="text/x-handlebars-template">
{{#each this}}
<div class="verse-set" id="{{setID}}">
  <div class="verse-set-header"><span>{{setTitle}}</span></div>
  <div class="verse-set-box">
	<ul>
	  {{#each verses}}
	  <li>{{verseRef}}<div class="view-verse-text">{{verseText}}</div>
	  {{/each}}
	</ul>
   </div>
  <div class="play-button">Play This Set</div>
</div>
{{/each}}
</script>
<!-- END verse-set-grid template -->

<!-- Target div: this is where the handlebars template will appear on the page -->
<div class="verse-set-grid"></div>

Now the second part of getting templates to work in Handlebars is the behind the scenes steps in JavaScript.

Step 1: Access the template via jQuery

Notice the jQuery selector here is targeting the template ID “verse-set-grid”, not the div class with the same name:

let verseSetsGrid = $('#verse-set-grid').html();

Step 2: Compile the template with Handlebars.compile

let verseSetsGridCompiled = Handlebars.compile(verseSetsGrid);

Step 3: Get the data that Handlebars will use for the template substitutions

let verseSetsData = []
let verseSetsData = JSON.parse(result)

Step 4: Pass the data to the compiled Handlebars object, which then places it in a new html variable

let html = verseSetsGridCompiled(verseSetsData);

Step 5: Use jQuery to place the updated html back into the template DOM

Notice the selector target here is the ‘.verse-set-grid’ class, not id! This is the div that contains the verse-set-grid template.

$('.verse-set-grid').html(html);

All five steps together looks like this:

// Step 1
let verseSetsGrid = $('#verse-set-grid').html();
// Step 2
let verseSetsGridCompiled = Handlebars.compile(verseSetsGrid);

// Step 3
let verseSetsData = []
// This is an AJAX query that calls a PHP function to return MySQL query results
$.get(cardSets, args, function(result)
{
   let verseSetsData = JSON.parse(result)
   // Step 4
   let html = verseSetsGridCompiled(verseSetsData);
   // Step 5
   $('.verse-set-grid').html(html);
});

 

For more information about Handlebars templates, see:
http://handlebarsjs.com/