Project

handlebars

0.19
No release in over 3 years
Low commit activity in last 3 years
There's a lot of open issues
Uses the actual JavaScript implementation of Handlebars, but supports using Ruby objects as template contexts and Ruby procs as view functions and named helpers
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
 Dependencies

Development

>= 0
~> 2.0

Runtime

 Project Readme

Handlebars.rb

Gem Version Build Status Dependency Status

This uses therubyracer to bind to the actual JavaScript implementation of Handlebars.js so that you can use it from ruby.

Usage

Simple stuff

require 'handlebars'
handlebars = Handlebars::Context.new
template = handlebars.compile("{{say}} {{what}}")
template.call(:say => "Hey", :what => "Yuh!") #=> "Hey Yuh!"

functions as properties

template.call(:say => "Hey ", :what => lambda {|this| ("yo" * 2) + "!"}) #=> "Hey yoyo!"

Block Helpers:

Just like JavaScript, you can write block helpers with an {{else}} section. To print out a section twice if a condition is met:

# V8 maps the first argument sent to a block to "this". All subsequent arguments are as
# described in the Handlebars documentation.
handlebars.register_helper(:twice) do |context, condition, block|
  if condition
    "#{block.fn(context)}#{block.fn(context)}"
  else
    block.inverse(context)
  end
end
template = handlebars.compile("{{#twice foo}}Hurray!{{else}}Boo!{{/twice}}")
template.call(foo: true) #=> Hurray!Hurray!
template.call(foo: false) #=> Boo!

Private variables:

Just like JavaScript, block helpers can inject private variables into their child templates. These can be accessed in a template using the @ prefix:

handlebars.register_helper(:list) do |this, context, block|
  "<ul>" + context.each_with_index.map do |x, i|
    if block.keys.include? "data"
      data = handlebars.create_frame(block.data)
      data.index = i
    end
    "<li>" + block.fn(x, data: data) + "</li>"
  end.join + "</ul>"
end
template = handlebars.compile("{{#list array}}{{@index}}. {{title}}{{/list}}")
template.call(array: [{title: "Memento"}, {title: "Inception"}])
#=> "<ul><li>0. Memento</li><li>1. Inception</li></ul>"

Hash arguments:

When using hash arguments, beware of one gotcha - V8 defines the #hash method for every object. Therefore, to access the hash object of the options argument Handlebars sends to your block, you must use the [] method:

handlebars.register_helper :list do |this, context, options|
  attrs = options[:hash].map{|k,v| "#{k}=\"#{v}\""}.join(' ')
  "<ul #{attrs}>" + context.map{|item| "<li>" + options.fn(item) + "</li>"}.join + "</ul>"
end
template = handlebars.compile(%({{#list nav id="nav-bar" class="top"}}<a href="{{url}}">{{title}}</a>{{/list}}))
template.call({nav: [{url: 'www.google.com', title: 'Google'}]})
#=> <ul class="top" id="nav-bar"><li><a href="www.google.com">Google</a></li></ul>

Safe Strings

By default, handlebars will escape strings that are returned by your block helpers. To mark a string as safe:

template = handlebars.compile("{{safe}}")
template.call(:safe => proc {Handlebars::SafeString.new("<pre>Totally Safe!<pre>")})

Partials

You can directly register partials

handlebars.register_partial("whoami", "I am {{who}}")
handlebars.compile("{{>whoami}}").call(:who => 'Legend') #=> I am Legend

Partials can also be dynamically looked up by defining a partial_missing behavior:

handlebars.partial_missing do |name|
  "unable to find >#{name}"
end
handlebars.compile("{{>missing}}").call #=> unable to find >missing

Missing partials can also be returned as a function:

count = 0
handlebars.partial_missing do |name|
  lambda do |this, context, options|
    count += 1
    "#{count} miss(es) when trying to look up a partial"
  end
end
t = handlebars.compile("{{>missing}}")
t.call #=> 1 miss(es) when trying to look up a partial
t.call #=> 2 miss(es) when tyring to look up a partial

Security

In general, you should not trust user-provided templates: a template can call any method (with no arguments) or access any property on any object in the Handlebars::Context.

If you'd like to render user-provided templates, you'd want to make sure you do so in a sanitized Context, e.g. no filesystem access, read-only or no database access, etc.

Test

rspec spec/