FlavourSaver

Handlebars templates in pure Ruby. Use the same templates on the server and in the browser.

• Works with Rails, and with Sinatra or anything else that uses Tilt
• One runtime dependency (tilt), no native extensions
• Ruby 3.1+, tested on 3.1 through 4.0

# Gemfile
gem "flavour_saver"

require "flavour_saver"

Person = Struct.new(:name, :admin)

FlavourSaver.evaluate("Hello {{name}}!", Person.new("Ana", true))
# => "Hello Ana!"

FS is an alias for FlavourSaver.

The context can be any object. Templates read its public methods: {{name}} calls context.name. Use a Struct, a Data class, a model or a presenter.

template = Tilt["handlebars"].new { "{{greeting}}, {{name}}!" }
template.render(Struct.new(:greeting, :name).new("Hi", "Ana"))
# => "Hi, Ana!"

.hbs and .handlebars files are registered with Tilt, so Tilt.new("welcome.hbs") works too.

Put templates in app/views with a .hbs or .handlebars extension. See Rails.

{{#each posts}}
  {{@index}}. {{title}}{{#if @last}} (latest){{/if}}
{{/each}}

{{#if author.admin}}
  Admin
{{else}}
  Member
{{/if}}

On Rails, FlavourSaver.logger is Rails.logger. Elsewhere, set one before using log:

require "logger"
FlavourSaver.logger = Logger.new($stdout)

Register a helper with a block. Positional arguments come first; key=value arguments arrive as a final hash with symbol keys.

FS.register_helper(:shout) { |text| text.upcase }
FS.register_helper(:greet) { |name, options| "#{options[:greeting]}, #{name}" }

{{shout "hi"}}                  {{! HI }}
{{greet "Ana" greeting="Hola"}} {{! Hola, Ana }}

Helper output is HTML-escaped. Return an html_safe string (from ActiveSupport) to skip escaping.

A block helper takes the template block as &block. block.call.contents renders the main section, optionally with a new context. block.call.inverse renders the {{else}} section.

FS.register_helper(:admins) do |people, &block|
  admins = people.select(&:admin)
  if admins.any?
    admins.map { |person| block.call.contents(person) }.join
  else
    block.call.inverse
  end
end

{{#admins people}}
  <li>{{name}}</li>
{{else}}
  <li>No admins</li>
{{/admins}}

You can also register a method. Inside a method, yield works the same way as block.call:

def twice
  yield.contents * 2
end

FS.register_helper(method(:twice))

Wrap a helper call in parentheses to use its result as an argument:

FS.register_helper(:sum) { |a, b| a + b }

{{sum (sum 5 10) (sum 2 3)}}     {{! 20 }}
{{chart total=(sum boys girls)}}

FS.register_partial(:user_card, "<b>{{name}}</b>")

{{#each people}}{{> user_card this}}{{/each}}

A partial can also be a block that receives the context and returns a string:

FS.register_partial(:user_card) { |person| "<b>#{person.name}</b>" }

On Rails, partials come from your views instead. See below.

FlavourSaver registers .hbs and .handlebars template handlers with Action View.

No instance variables. Templates can't see controller instance variables. This keeps them portable to Handlebars.js. Expose data through helper methods or a presenter:

# app/helpers/application_helper.rb
module ApplicationHelper
  def current_user
    Current.user
  end
end

{{#if current_user}}
  Welcome back, {{current_user.first_name}}!
{{/if}}

Call view helpers through @root inside blocks. The view is the root context. Inside {{#each}} or {{#with}}, names are looked up on the current item, so {{post_url id}} renders blank. Use @root to reach the view:

{{#each posts}}
  <a href="{{@root.post_url id}}">{{title}}</a>
{{/each}}

Partials use render. You don't register partials in Rails. The partial syntax maps to Rails partials, and the argument is passed as object::

Invalid templates raise a subclass of FlavourSaver::Error:

begin
  FS.evaluate("{{#if ok}}unclosed", context)
rescue FlavourSaver::Error => e
  # FlavourSaver::Parser::NotInLanguage, ::UnbalancedBlockError,
  # or FlavourSaver::Lexer::LexingError
end

A template can only call registered helpers and the public methods of its context. Methods every object inherits, like send, instance_eval or class, raise FlavourSaver::ForbiddenMethodException. Private methods like system and eval can't be reached at all. Even so, only pass objects you're comfortable exposing to template authors.

These Handlebars features don't parse or don't behave like Handlebars.js yet. Pull requests are welcome.

• Whitespace control ({{~foo~}})
• {{else if …}} chains
• Block parameters ({{#each items as |item|}})
• {{else}} inside {{#each}} and {{#with}}
• Inline partials, partial blocks, dynamic partials, and hash arguments on partials
• The lookup helper
• ./ paths

Bug reports and pull requests are welcome on GitHub.

git clone https://github.com/FlavourSaver/FlavourSaver.git
cd FlavourSaver
bundle install
bundle exec rspec

Changes are listed in the CHANGELOG.

MIT. Copyright (c) 2013 Resistor Limited. See LICENSE.