Handlebars Assets 技术文档

本文档旨在帮助用户了解和使用 handlebars_assets 项目，内容涵盖安装指南、使用说明、API 文档以及安装方式。

1. 安装指南

Rails 4.0+

在 Gemfile 中添加 handlebars_assets：

gem 'handlebars_assets'

然后按照 Javascript 设置 进行操作。

Rails 3.1+

在 Gemfile 的 assets 组中添加 handlebars_assets：

group :assets do
  gem 'handlebars_assets'
end

然后按照 Javascript 设置 进行操作。

Sprockets (非 Rails 项目)

在 Gemfile 中添加 handlebars_assets：

gem 'handlebars_assets'

将 HandlebarsAssets.path 添加到 Sprockets::Environment 实例中：

env = Sprockets::Environment.new

require 'handlebars_assets'
env.append_path HandlebarsAssets.path

2. 使用说明

模板文件

将 Handlebars 模板作为独立文件放置在模板目录中。模板的组织方式类似于 Rails 视图。

例如，如果你有一个 Contact 模型的新建、编辑和显示模板：

templates/
  contacts/
    new.hbs
    edit.hbs
    show.hbs

文件扩展名 .hbs 告诉资产管道使用 Handlebars 编译模板。

如果文件是 templates/contacts/new.hbs，资产管道将生成 JavaScript 代码：

1. 将 Handlebars 模板编译为 JavaScript 代码。
2. 将模板代码添加到 HandlebarsTemplates 全局对象中，名称为 contacts/new。

你可以在应用的 JavaScript 中调用生成的模板：

HandlebarsTemplates['contacts/new'](context);

局部模板

如果模板名称以下划线开头，它将被识别为局部模板。你可以在模板中使用 Handlebars 局部语法调用局部模板：

调用一个 {{> path/to/_partial }}

3. API 使用文档

模板命名空间

默认情况下，全局 JavaScript 对象 HandlebarsTemplates 保存编译后的模板，但可以轻松重命名。另一个常见的模板命名空间是 JST。只需在初始化应用时更改 template_namespace 配置选项：

HandlebarsAssets::Config.template_namespace = 'JST'

Ember 支持

要为 Ember.js 编译模板，只需启用配置选项：

HandlebarsAssets::Config.ember = true

如果需要为 Ember 和其他框架编译模板，则启用多框架支持：

HandlebarsAssets::Config.multiple_frameworks = true

启用 mutliple_frameworks 后，扩展名为 .ember.hbs 的模板将可用于 Ember。

.hamlbars 和 .slimbars 支持

如果使用 .hamlbars 扩展名命名模板，可以使用 Haml 语法编写标记！使用 HandlebarsAssets::Config.haml_options 传递自定义选项给 Haml 渲染引擎。

例如，如果你有一个文件 widget.hamlbars，内容如下：

%h1 {{title}}
%p {{body}}

Haml 将被预处理，使得 Handlebars 模板基本上是这样的：

<h1> {{title}} </h1>
<p> {{body}} </p>

同样适用于 .slimbars 和 Slim gem。使用 HandlebarsAssets::Config.slim_options 传递自定义选项给 Slim 渲染引擎。

注意： 要在 Haml 中使用 hb Handlebars 助手，你还需要在 Gemfile 中包含 Hamlbars gem：

gem 'hamlbars', '~> 2.0'

4. 项目安装方式

Rails 4.0+

在 Gemfile 中添加 handlebars_assets：

gem 'handlebars_assets'

然后按照 Javascript 设置 进行操作。

Rails 3.1+

在 Gemfile 的 assets 组中添加 handlebars_assets：

group :assets do
  gem 'handlebars_assets'
end

然后按照 Javascript 设置 进行操作。

Sprockets (非 Rails 项目)

在 Gemfile 中添加 handlebars_assets：

gem 'handlebars_assets'

将 HandlebarsAssets.path 添加到 Sprockets::Environment 实例中：

env = Sprockets::Environment.new

require 'handlebars_assets'
env.append_path HandlebarsAssets.path

Javascript 设置

在 JavaScript 清单文件（如 application.js）中引入 handlebars.runtime.js：

//= require handlebars.runtime

如果需要在浏览器中编译 JavaScript 模板，则应引入 handlebars.js（文件较大）：

//= require handlebars

模板目录

通常你会将模板与其他资产放在一起，例如 app/assets/javascripts/templates。在 JavaScript 清单文件中，使用 require_tree 引入模板：

//= require_tree ./templates

这必须在 //= require_tree . 之前完成，以确保所有模板具有预期的前缀；并且在引入 handlebars/handlebars runtime 之后。

Rails 资产预编译

handlebars_assets 也适用于资产预编译。

rake assets:precompile

如果使用 rake assets:precompile，则必须重新运行 rake 命令以重建任何更改的模板。

Heroku 和其他云主机

如果部署到 Heroku，请确保在 config/application.rb 中设置：

config.assets.initialize_on_precompile = false

这避免了在编译资产时运行初始化程序。

总结

本文档详细介绍了 handlebars_assets 的安装、使用、API 以及安装方式。通过本文档，用户可以轻松上手并充分利用该项目的功能。