Haml Coffee Assets 技术文档

1. 安装指南

使用 Bundler 安装

最简单的安装方式是使用 Bundler。在你的 Gemfile 中添加 haml_coffee_assets 和 execjs：

group :assets do
  gem 'haml_coffee_assets'
  gem 'execjs'
end

注意：Rails 4.0 已经移除了 assets 组，因此如果你使用的是 Rails 4.0 或更高版本，不需要添加 group :assets do 这一行。

引入 hamlcoffee.js

在你的 app/assets/javascripts/templates/context.js.coffee 文件中引入 hamlcoffee.js：

#= require hamlcoffee

如果你使用 AMD 支持，则不需要手动引入上述文件，因为它会自动包含。

2. 项目的使用说明

Haml Coffee 模板生成

扩展名：.hamlc

如果你省略 .jst 扩展名，只使用 .hamlc 扩展名，Haml Coffee Assets 将处理 JavaScript 模板的生成。这种方式允许你通过简单的配置定义自己的命名空间，并使用模板名称过滤器。

你可以将所有 Haml Coffee 模板放在 app/assets/javascripts/templates 目录中，并在 app/assets/javascripts/application.js.coffee 中包含所有模板：

#= require_tree ./templates

由于 Haml Coffee Assets 提供了默认的模板名称过滤器，templates/ 前缀将自动被移除。

Sprocket JST 处理器模板生成

扩展名：.jst.hamlc

当你为模板使用 .jst.hamlc 扩展名时，Haml Coffee Assets 只会生成模板函数，然后由 Sprocket JST 处理器 进一步处理。由于 Haml Coffee Assets 不会生成模板，因此你无法使用 AMD 支持、模板名称过滤器，并且 JST 命名空间的定义比 Haml Coffee 模板生成更复杂。

使用这种方式时，你应该将所有 Haml Coffee 模板放在 app/assets/templates 目录中，并在 app/assets/javascripts/application.js.coffee 中包含所有模板：

#= require_tree ../templates

如果你将模板放在 app/assets/javascripts/templates 中，所有 JST 模板名称将以 templates/ 开头，这可能不是你想要的。

服务器端渲染

Haml Coffee Assets 注册了 .hamlc 扩展名，因此 Rails 模板可以使用 Haml Coffee 编写。Rails 将识别放在 app/assets/javascripts/templates 中的模板（尽管路径可以更改，如果你将模板存储在其他目录中），并且相同的模板文件可以通过 Rails 或客户端的 JavaScript 渲染。服务器端渲染仅在使用全局放置时可用，不适用于 AMD 放置。

3. 项目API使用文档

配置选项

文档格式

默认情况下，所有 Haml Coffee 模板都渲染为 HTML5 文档。你可以选择以下输出格式：

• html5
• html4
• xhtml

如果你希望使用其他 HTML 格式，可以在 config/application.rb 中设置：

config.hamlcoffee.format = 'xhtml'

模板放置

默认情况下，所有 Haml Coffee 模板都放置在配置的模板命名空间下。你可以选择以下放置方式：

• global
• amd

通过将 placement 选项设置为 amd，每个模板将被包装在一个 define 函数中，从而支持模块加载器的使用。

config.hamlcoffee.placement = 'amd'

注意：placement 选项仅适用于使用 .hamlc 扩展名并让 Haml Coffee Assets 处理 JST 生成的情况。

全局模板依赖

Haml Coffee Assets 允许你全局定义所有模板的模块依赖。默认情况下，Haml Coffee Assets 助手会被包含，但你也可以添加自己的依赖：

config.hamlcoffee.dependencies = { '_' => 'underscore', :hc => 'hamlcoffee_amd' }

如果你不包含 hamlcoffee_amd 模块作为 hc，则助手方法将被包含在每个模板中，增加模板的大小。建议始终包含 hamlcoffee 模块。

模板命名空间

默认情况下，所有 Haml Coffee 模板都注册在 JST 命名空间下。例如，app/assets/javascripts/templates/header.hamlc 模板的内容如下：

%header
  %h2= @title

在浏览器中可以通过 JST['header'] 访问。你可以渲染预编译的模板并传递要渲染的数据：

JST['header']({ title: 'Hello Haml Coffee' })

如果你希望使用其他命名空间，可以在 config/application.rb 中设置：

config.hamlcoffee.namespace = 'window.HAML'

你甚至可以设置一个深层嵌套的命名空间，如 window.templates.HAML，Haml Coffee 将处理所有层次的创建。

4. 项目安装方式

使用 Bundler 安装

在 Gemfile 中添加以下内容：

group :assets do
  gem 'haml_coffee_assets'
  gem 'execjs'
end

然后运行 bundle install 进行安装。

引入 hamlcoffee.js

在 app/assets/javascripts/templates/context.js.coffee 中引入 hamlcoffee.js：

#= require hamlcoffee

清理 Sprockets 缓存

如果你更改了配置，但模板已经编译，新的设置不会应用到已编译的模板。你可以通过以下命令清理 Sprockets 缓存：

rake assets:clean