Hamlbars

Hamlbars is a Ruby gem which allows you to easily generate Handlebars templates using Haml.

Installation

Add the following line to your Gemfile (on Rails, inside the :assets group):

gem 'hamlbars', '~> 1.0'

If you are stuck with an older, yanked version like 2012.3.21 and it won't update to 1.0, be sure to add '~> 1.0' as the version spec and run bundle install.

Demo Site

If you're unsure how all the pieces fit together then take a quick look at the demo site.

Attribute bindings

You can easily add attribute bindings by adding a :bind hash to the tag attributes, like so:

%div{ :class => 'widget', :bind => { :title => 'App.widgetController.title' }

Which will generate the following output:

<div class="widget" {{bindAttr title="App.widgetController.title"}}></div>

Event bindings

You can add one or more event actions by adding an event hash or array or event hashes to the tag options:

%a{ :event => { :on => 'click', :action => 'clicked' } } Click

or

%div{ :events => [ { :on => 'mouseover', :action => 'highlightView' }, { :on => 'mouseout', :action => 'disableViewHighlight' } ] }

Note that the default event is click, so it's not necessary to specify it:

%a{ :event => { :action => 'clicked' } } Click

Handlebars helper

You can use the handlebars helper (or just hb for short) to generate both Handlebars blocks and expressions.

Expressions

Generating Handlebars expressions is as simple as using the handlebars helper and providing the expression as a string argument:

= hb 'App.widgetController.title'

which will will generate:

{{App.widgetController.title}}

Blocks

Whereas passing a block to the handlebars helper will create a Handlebars block expression:

%ul.authors
= hb 'each authors' do
  %li<
    = succeed ',' do
      = hb 'lastName'
    = hb 'firstName'

will result in the following markup:

<ul class="authors">
   {{#each authors}}
     <li>{{lastName}}, {{firstName}}</li>
   {{/each}}
</ul>

Options

The hb helper can take an optional hash of options which will be rendered inside the expression:

= hb 'view App.InfoView', :tagName => 'span'

will result in:

{{view App.InfoView tagName="span"}}

Tripple-stash

You can use the handlebars! or hb! variant of the handlebars helper to output "tripple-stash" expressions within which Handlebars does not escape the output.

Configuring template output:

hamlbars has three configuration options, which pertain to the generated JavaScript:

Hamlbars::Template.template_destination    # default 'Handlebars.templates'
Hamlbars::Template.template_compiler       # default 'Handlebars.compile'
Hamlbars::Template.template_partial_method # default 'Handlebars.registerPartial'

These settings will work find by default if you are using Handlebars as a standalone JavaScript library, however if you are using something that embeds Handlebars within it then you'll have to change these.

If you're using Ember.js then you can use:

Hamlbars::Template.render_templates_for :ember

Which is effectively the same as:

Hamlbars::Template.template_destination = 'Ember.TEMPLATES'
Hamlbars::Template.template_compiler = 'Ember.Handlebars.compile'
Hamlbars::Template.template_partial_method = 'Ember.Handlebars.registerPartial'

The good news is that if you're using the emberjs-rails gem then it will automatically detect hamlbars and change it for you. Magic!

If you're using ember-rails then you'll need to put this in a initializer.

Configuring JavaScript output:

Hamlbars has experimental support for template precompilation using ExecJS. To enable it, call

Hamlbars::Template.enable_precompiler!

You can also disable enclosification (which is enabled by default) using:

Hamlbars::Template.disable_closures!

Asset pipeline

Hamlbars is specifically designed for use with Rails 3.1's asset pipeline. Simply create templates ending in .js.hamlbars and Sprockets will know what to do.

Rails helpers

You can enable support by calling Hamlbars::Template.enable_rails_helpers!. Probably the best way to do this is to create an initializer. This is dangerous and possibly stupid as a large number of Rails' helpers require access to the request object, which is not present when compiling assets.

Use at your own risk. You have been warned.

License and Copyright.

Hamlbars is Copyright © 2012 Sociable Limited and licensed under the terms of the MIT License.