Templating, AJAX & APIs

A Quick Guide to using Handlebars

1. Include the Handlebars script in the page (CDN or local)

2. Insert templates into the page using script tags, like:

   <script id="my-template" type="text/x-handlebars-template"></script>

   1. The type attribute must be set to text/x-handlebars!!
   2. Also, your template script block should have an id set on it in order to find and use the template...

3. Inside those tags you add Handlebars template code that looks like:

   <script id="my-template" type="text/x-handlebars-template">
     <div class="entry">
       <h3>{{title}}</h3>
       <div class="body">
         <p>{{body}}</p>
       </div>
     </div>
   </script>

   The {{<something>}}s are where we will insert data which is relevant to the piece of HTML we are creating.

4. The next step is to get hold of the template markup and use it. To do this we need to copy it, and then Handlebars needs to 'compile' it.

   Compilation is when Handlebars takes the contents of that script block and turns it into a function that outputs html. The function accepts an argument (which is an object) that contains any extra data required to manufacture that particular piece of HTML.

   Once stored, you can use a template repeatedly, say for rendering a list of products, by calling that function and passing the data for a different product each time. We refer to this data as the 'context' in which the template is rendered.

   var source   = $("#my-template").html(); //Gets template markup from inside the script tag
   var template = Handlebars.compile(source); //Returns a function we'll use to create HTML chunks

5. Next you must get hold of the data that you'll use to render that particular piece of html. (The context) e.g.:

   var data = {title: "New HTML", body: "This is my templated content!"};

6. You then call the template function we created above, passing the data. This will return the new HTML:

   var html = template(data);

   This produces the HTML:

   <div class="entry">
     <h3>New HTML</h3>
     <div class="body">
       <p>This is my templated content!</p>
     </div>
   </div>

7. Now insert it into the page:

   $('#targetArea').html(html);