Fork me on GitHub

ICanHaz.js

Simple & powerful client-side templating

Download

Or... you can clone the whole project from GitHub with Git by running:

$ git clone git://github.com/HenrikJoreteg/ICanHaz.js

Okay, let's do things

The Quick Demo:

Step 1. - Define your template

<script id="user" type="text/html">
  <li>
    <p class="name">Hello I'm {{ name }}</p>
    <p><a href="http://twitter.com/{{ twitter }}">@{{ twitter }}</a></p>
  </li>
</script>

Step 2. - Retrieve your populated template:

// I Can Haz User?
var user = ich.user(user_data_object)

Step 3. - There is no step 3!

What else do I need to know?

For simplicity and ease of use, ICanHaz includes janl's Mustache.js v0.4.0 (inside a closure) that way you can just include ICanHaz and then YOU CAN HAZ stuffs. Luckily Mustache and Mustache.js are generously MIT licensed. Mr. Github founder himself Chris Wanstrath (@defunkt) created mustache. Read the mustache documentation for more info. Then it was ported to JS by Jan Lehnardt.

Why would we need this?

Because building html elements using javascript or jQuery is ugly. There's several ways to do it, but the point is — it's ugly.

// vanilla JS
hello_div = document.createElement('div');
hello_div.setAttribute('class', 'hello');
my_list = document.createElement('ul');
hello_div.appendChild(my_list);
list_item = document.createElement('li');
list_item.innerHTML = 'My list item';
my_list.appendChild(list_item);

// jQuery
hello_div = $('<div class="hello"><ul></ul></div>');
hello_div.children('ul').append('<li>My list<li>');

It gets really problematic if what you're building is a lot longer or more complex than this example. Not to mention, it's also not a clean separation of concerns to write html in javascript.

Mustache.js gives us an awesome templating solution, here's a snippet from their docs:

var view = {
  title: "Joe",
  calc: function() {
    return 2 + 4;
  }
}

var template = "{{title}} spends {{calc}}";

var html = Mustache.to_html(template, view);

But the beauty fades when we're dealing with multi-line html in the browser because strings in JS can't include new-lines so everything has to be escaped. Then there's the problem of double vs. single quotes and before you know it... we're back in ugly land:

var template = '<div class="hello">\
  <span class="title">{{ title }}</span>\
  <ul></ul>\
</div>'

I Can Haz Better Solution?

YES!

With ICanHaz.js you define your Mustache.js template snippets in script blocks of type="text/html" and give them an "id" as a title for your snippet (which validates, btw). This approach was suggested by jQuery developer @jeresig on his blog.Then, on document ready ICanHaz.js builds a cache of all the templates and creates a function for each snippet. All you have to do is say to yourself for example "I can haz user?":

var data = {
  first_name: "Henrik",
  last_name: "Joreteg"
}

// I can has user??
html = ich.user(data)

At this point 'html' is jQuery or Zepto (if they're included) object containing your complete html with your data injected.

For each template you define (except partials), ICanHaz builds a retrieval function with the same name. If you don't want a jQuery object but just want the populated string you can just pass in true as the second argument to get the raw string. This is useful if your template isn't producing html.

If you don't have jQuery or Zepto, you can still use ICanHaz. You'll just get strings back instead of jQuery objects.

I'm in ur templates, making macroz.

ICanHaz.js also supports mustache partials. To quote the original mustache.js announcement:

Partials are good for including often-used snippets, like navigation or headers and footer.

In mustache, partials are dead simple. You have a special tag {{>partial}} that you put where you want to insert the partial, create the partial that you want to be displayed and that's it. It is just a basic replace or macro include mechanism. Nothing fancy.

Just add your partial like any other template

<!-- Main template, includes the "winnings" partial. -->
<script id="welcome" type="text/html">
<p>Welcome, {{name}}! {{>winnings}}</p>
</script>

<!-- Partial included via {{>winnings}} -->
<script id="winnings" class="partial" type="text/html">
You just won ${{value}} (which is ${{taxed_value}} after tax)
</script>

Then call the main template normally.

Adding templates/partials later

Optionally, you can call ich.addTemplate(name, templateString) to add templates and partials if you'd prefer to pull them from a server with ajax or whatnot. You can even do ich.grabTemplates if you've loaded in some other page

Available Methods

Beyond the retrieval functions that ICanHaz creates based on template names, these additional methods exist.

Examples

Full Working Example

<!DOCTYPE html>
<html>
  <head>
    <title>ICanHaz.js Demo</title>
    <script src="test/jquery-1.4.4.min.js"></script>
    <script src="ICanHaz.min.js" ></script>

    <script id="user" type="text/html">
      <li>
        <p>Hi I&apos;m <a href="http://twitter.com/{{ twitter }}">@{{ twitter }}</a></p>
        <p>I work for {{ employer }} as a {{ job_title }}.</p>
      </li>
    </script>

    <script type="text/javascript">
      // when the dom's ready
      $(document).ready(function () {
        // add a simple click handler for the "add user" button.
        $('#add_user').click(function () {
          var user_data, user;

          // build a simple user object, in a real app this
          // would probably come from a server somewhere.
          // Otherwise hardcoding here is just silly.
          user_data = {
            name: "Henrik Joreteg",
            twitter: "HenrikJoreteg",
            employer: "&yet",
            job_title: "JS nerd"
          };

          // Here's all the magic.
          user = ich.user(user_data);

          // append it to the list, tada!
          //Now go do something more useful with this.
          $('#user_list').append(user);
        });
      });
    </script>

    <style>
      body {
        font-family: Helvetica;
      }
    </style>
  </head>
  <body>
    <h1>ICanHaz.js Demo</h1>
    <h3>User List</h3>
    <button id="add_user">Add User</button>
    <ul id="user_list"></ul>
  </body>
</html>

Pulling templates from a remote server

 
$.getJSON('/myserver/templates.json', function (templates) {
    $.each(templates, function (index, template) {
        ich.addTemplate(template.name, template.template);
    });
});

Credits

ICanHaz.js was created by @HenrikJoreteg.

Other Contributors:

Browser Support:

This has been tested in a pile of browsers. Thanks to BrowserStack. The only thing that may fail is the automatic grabbing of templates if you're in a browser that doesn't support DOMContentLoaded and you didn't include jQuery or Zepto. Other than that all browsers should work. If not, it's a bug.

Changelog