Use handlebars.js templates with the Rails asset pipeline.
Are your handlebars.js templates littering your Rails views with script tags? Wondering why the nifty Rails 3.1 asset pipeline streamlines all your JavaScript except for your Handlebars templates? Wouldn’t it be nice to have your Handlebars templates compiled, compressed, and cached like your other JavaScript?
Yea, I think so too. That is why I wrote handlebars_assets. Give your Handlebars templates their own files (including partials) and have them compiled, compressed, and cached as part of the Rails 3.1 asset pipeline!
Using sprockets with Sinatra or another framework? handlebars_assets works outside of Rails too (as of v0.2.0)
@AlexRiedler has made some larger changes to this repository for going forward; If you have existing monkey patches they may not work, and the configuration schema has changed slightly to handle multiple extensions for the same compilation pipeline.
If you have any problems, please post an issue! I will attempt to fix ASAP
My pull request to allow / in partials was pulled into Handlebars. The hack that converted partial names to underscored paths (shared/_time -> _shared_time) is no longer necessary and has been removed. You should change all the partial references in your app when upgrading from a version prior to v0.9.0.
handlebars_assets is packaged with the current stable release of handlebars.js. See the section on using another version if that does not work for you.
Load handlebars_assets in your Gemfile
gem 'handlebars_assets'
Then follow Javascript Setup
Side Note: As of Rails 4.0, the assets group is not supported in the Gemfile (source).
Load handlebars_assets in your Gemfile as part of the assets group
group :assets do
gem 'handlebars_assets'
end
Then follow Javascript Setup
handlebars_assets can work with earlier versions of Rails or other frameworks like Sinatra.
Load handlebars_assets in your Gemfile
gem 'handlebars_assets'
Add the HandlebarsAssets.path to your Sprockets::Environment instance. This
lets Sprockets know where the Handlebars JavaScript files are and is required
for the next steps to work.
env = Sprockets::Environment.new
require 'handlebars_assets'
env.append_path HandlebarsAssets.path
Require handlebars.runtime.js in your JavaScript manifest (i.e. application.js)
//= require handlebars.runtime
If you need to compile your JavaScript templates in the browser as well, you should instead require handlebars.js (which is significantly larger)
//= require handlebars
Generally you want to locate your template with your other assets, for example app/assets/javascripts/templates. In your JavaScript manifest file, use require_tree to pull in the templates
app/assets/javascripts/application.js
//= require_tree ./templates
This must be done before //= require_tree . otherwise all your templates will not have the intended prefix; and after your inclusion of handlebars/handlebars runtime.
handlebars_assets also works when you are precompiling your assets.
rake assets:precompileIf you are using rake assets:precompile, you have to re-run the rake command to rebuild any changed templates. See the Rails guide for more details.
If you are deploying to Heroku, be sure to read the Rails guide and in your config/application.rb set:
config.assets.initialize_on_precompile = false
This avoids running your initializers when compiling assets (see the guide for why you would want that).
However, that does mean that you cannot set your configuration in an initializer. This issue has a workaround, or you can set:
config.assets.initialize_on_precompile = true
This will run all your initializers before precompiling assets.
Write your Handlebars templates as standalone files in your templates directory. Organize the templates similarly to Rails views.
For example, if you have new, edit, and show templates for a Contact model
templates/
contacts/
new.hbs
edit.hbs
show.hbs
Your file extensions tell the asset pipeline how to process the file. Use .hbs to compile the template with Handlebars.
If your file is templates/contacts/new.hbs, the asset pipeline will generate JavaScript code
HandlebarsTemplates global under the name contacts/newYou can then invoke the resulting template in your application’s JavaScript
NOTE: There will be no javascript object HandlebarsTemplates unless at least ONE template is included.
HandlebarsTemplates['contacts/new'](context);
If you begin the name of the template with an underscore, it will be recognized as a partial. You can invoke partials inside a template using the Handlebars partial syntax:
Invoke a {{> path/to/_partial }}
By default, the global JavaScript object that holds the compiled templates is HandlebarsTemplates, but it can
be easily renamed. Another common template namespace is JST. Just change the template_namespace configuration option
when you initialize your application.
HandlebarsAssets::Config.template_namespace = 'JST'
To compile your templates for use with Ember.js
simply turn on the config option:
HandlebarsAssets::Config.ember = true
If you need to compile templates for Ember and another framework then enable
multiple frameworks:
HandlebarsAssets::Config.multiple_frameworks = true
After mutliple_frameworks has been enabled templates with the .ember.hbs
extension will be made available to Ember.
.hamlbars and .slimbars SupportIf you name your templates with the extension .hamlbars, you can use Haml syntax for your markup! Use HandlebarsAssets::Config.haml_options to pass custom options to the Haml rendering engine.
For example, if you have a file widget.hamlbars that looks like this:
%h1 {{title}}
%p {{body}}
The Haml will be pre-processed so that the Handlebars template is basically this:
<h1> {{title}} </h1>
<p> {{body}} </p>
The same applies to .slimbars and the Slim gem. Use HandlebarsAssets::Config.slim_options to pass custom options to the Slim rendering engine.
Note: To use the hb handlebars helper with Haml, you’ll also need to include the Hamlbars gem in your Gemfile:
gem 'hamlbars', '~> 2.0'
This will then allow you to do things like Haml blocks:
%ul.authors
= hb 'each authors' do
%li<
= succeed ',' do
= hb 'lastName'
= hb 'firstName'
Reference hamlbars for more information.
handlebars.jsOccasionally you might need to use a version of handlebars.js other than the included version. You can set the compiler_path and compiler options to use a custom version of handlebars.js.
HandlebarsAssets::Config.compiler = 'my_handlebars.js' # Change the name of the compiler file
HandlebarsAssets::Config.compiler_path = Rails.root.join('app/assets/javascripts') # Change the location of the compiler file
handlebars.jsIf you need specific customizations to the handlebars.js compiler, you can use patch the compiler with your own JavaScript patches.
The patch file(s) are concatenated with the handlebars.js file before compiling. Take a look at the test for details.
HandlebarsAssets::Config.patch_files = 'my_patch.js'
HandlebarsAssets::Config.patch_path = Rails.root.join('app/assets/javascripts') # Defaults to `Config.compiler_path`
This gem is standing on the shoulders of giants.
Thank you Yehuda Katz (@wycats) for handlebars.js and lots of other code I use every day.
Thank you Charles Lowell (@cowboyd) for therubyracer and handlebars.rb.
This gem is maintained by Alex Riedler Github.
Les Hill, follow me on Github and Twitter.
(@kendagriff) : 1.8.7 compatibility
(@cw-moshe) : Remove 'templates/' from names
(@mattmenefee) : README section for `hamlbars`
multiple_frameworksPull requests are welcome! Please do not update the version number.
In a nutshell: