# Rails应用模版
应用模版是一个包括使用DSL添加gems/initializers等操作的普通Ruby文件.可以很方便的在你的应用中创建。
读完本章节，你将会学到：
* 如何使用模版生成/个性化一个应用。
* 如何使用Rails的模版API编写可复用的应用模版。
### Chapters
1. [模版应用简介](#%E6%A8%A1%E7%89%88%E5%BA%94%E7%94%A8%E7%AE%80%E4%BB%8B)
2. [模版API](#%E6%A8%A1%E7%89%88api)
* [gem(*args)](#gem(*args))
* [gem_group(*names, &block)](#gem_group(*names,-&block))
* [add_source(source, options = {})](#add_source(source,-options-=-%7B%7D))
* [environment/application(data=nil, options={}, &block)](#environment/application(data=nil,-options=%7B%7D,-&block))
* [vendor/lib/file/initializer(filename, data = nil, &block)](#vendor/lib/file/initializer(filename,-data-=-nil,-&block))
* [rakefile(filename, data = nil, &block)](#rakefile(filename,-data-=-nil,-&block))
* [generate(what, *args)](#generate(what,-*args))
* [run(command)](#run(command))
* [rake(command, options = {})](#rake(command,-options-=-%7B%7D))
* [route(routing_code)](#route(routing_code))
* [inside(dir)](#inside(dir))
* [ask(question)](#ask(question))
* [yes?(question) or no?(question)](#yes-questionmark(question)-or-no-questionmark(question))
* [git(:command)](#git(:command))
3. [高级应用](#%E9%AB%98%E7%BA%A7%E5%BA%94%E7%94%A8)
### 1 模版应用简介
为了使用一个模版，你需要为Rails应用生成器在生成新应用时提供一个'-m'选项来配置模版的路径。该路径可以是本地文件路径也可以是URL地址。
```
$ rails new blog -m ~/template.rb
$ rails new blog -m http://example.com/template.rb
```
你可以使用rake的任务命令`rails:template`为Rails应用配置模版。模版的文件路径需要通过名为'LOCATION'的环境变量设定。再次强调，这个路径可以是本地文件路径也可以是URL地址：
```
$ bin/rake rails:template LOCATION=~/template.rb
$ bin/rake rails:template LOCATION=http://example.com/template.rb
```
### 2 模版API
Rails模版API很容易理解，下面我们来看一个典型的模版例子：
```
# template.rb
generate(:scaffold, "person name:string")
route "root to: 'people#index'"
rake("db:migrate")
git :init
git add: "."
git commit: %Q{ -m 'Initial commit' }
```
下面的章节将详细介绍模版API的主要方法：
#### 2.1 gem(*args)
向一个Rails应用的`Gemfile`配置文件添加一个'gem'实体。 举个例子，如果你的应用的依赖项包含`bj` 和 `nokogiri`等gem ：
```
gem "bj"
gem "nokogiri"
```
需要注意的是上述代码不会安装gem文件到你的应用里，你需要运行`bundle install` 命令来安装它们。
```
bundle install
```
#### 2.2 gem_group(*names, &block)
将gem实体嵌套在一个组里。
比如，如果你只希望在`development`和`test`组里面使用`rspec-rails`，可以这么做 ：
```
gem_group :development, :test do
gem "rspec-rails"
end
```
#### 2.3 add_source(source, options = {})
为Rails应用的`Gemfile`文件指定数据源。
举个例子。如果你需要从`"http://code.whytheluckystiff.net"`下载一个gem：
```
add_source "http://code.whytheluckystiff.net"
```
#### 2.4 environment/application(data=nil, options={}, &block)
为`Application`在`config/application.rb`中添加一行内容。
如果声明了`options[:env]`参数，那么这一行会在`config/environments`添加。
```
environment 'config.action_mailer.default_url_options = {host: "http://yourwebsite.example.com"}', env: 'production'
```
可以使用一个 'block'标志代替`data`参数。
#### 2.5 vendor/lib/file/initializer(filename, data = nil, &block)
为一个应用的`config/initializers`目录添加初始化器。
假如你喜欢使用`Object#not_nil?` 和 `Object#not_blank?`：
```
initializer 'bloatlol.rb', <<-CODE
class Object
def not_nil?
!nil?
end
def not_blank?
!blank?
end
end
CODE
```
一般来说，`lib()`方法会在 `lib/` 目录下创建一个文件，而`vendor()`方法会在`vendor/`目录下创建一个文件。
甚至可以用`Rails.root`的`file()`方法创建所有Rails应用必须的文件和目录。
```
file 'app/components/foo.rb', <<-CODE
class Foo
end
CODE
```
上述操作会在`app/components`目录下创建一个 `foo.rb` 文件。
#### 2.6 rakefile(filename, data = nil, &block)
在 `lib/tasks`目录下创建一个新的rake文件执行任务：
```
rakefile("bootstrap.rake") do
<<-TASK
namespace :boot do
task :strap do
puts "i like boots!"
end
end
TASK
end
```
上述代码将在`lib/tasks/bootstrap.rake`中创建一个`boot:strap`任务。
#### 2.7 generate(what, *args)
通过给定参数执行生成器操作：
```
generate(:scaffold, "person", "name:string", "address:text", "age:number")
```
#### 2.8 run(command)
执行命令行命令，和你在命令行终端敲命令效果一样。比如你想删除`README.rdoc`文件：
```
run "rm README.rdoc"
```
#### 2.9 rake(command, options = {})
执行Rails应用的rake任务，比如你想迁移数据库：
```
rake "db:migrate"
```
你也可以在不同的Rails应用环境中执行rake任务：
```
rake "db:migrate", env: 'production'
```
#### 2.10 route(routing_code)
在`config/routes.rb`文件中添加一个路径实体。比如我们之前为某个人生成了一些简单的页面并且把 `README.rdoc`删除了。现在我们可以把应用的`PeopleController#index`设置为默认页面：
```
route "root to: 'person#index'"
```
#### 2.11 inside(dir)
允许你在指定目录执行命令。举个例子，你如果希望将一个外部应用添加到你的新应用中，可以这么做：
```
inside('vendor') do
run "ln -s ~/commit-rails/rails rails"
end
```
#### 2.12 ask(question)
`ask()`方法为你提供了一个机会去获取用户反馈。比如你希望用户在你的新应用'shiny library'提交用户反馈意见：
```
lib_name = ask("What do you want to call the shiny library ?")
lib_name << ".rb" unless lib_name.index(".rb")
lib lib_name, <<-CODE
class Shiny
end
CODE
```
#### 2.13 yes?(question) or no?(question)
这些方法是根据用户的选择之后做一些操作的。比如你的用户希望停止Rails应用，你可以这么做：
```
rake("rails:freeze:gems") if yes?("Freeze rails gems?")
# no?(question) acts just the opposite.
```
#### 2.14 git(:command)
Rails模版允许你运行任何git命令：
```
git :init
git add: "."
git commit: "-a -m 'Initial commit'"
```
### 3 高级应用
应用模版是在`Rails::Generators::AppGenerator`实例的上下文环境中执行的，它使用`apply` 动作来执行操作[Thor](https://github.com/erikhuda/thor/blob/master/lib/thor/actions.rb#L207)。这意味着你可以根据需要扩展它的功能。
比如重载`source_paths`方法实现把本地路径添加到你的模版应用中。那么类似`copy_file`方法会在你的模版路径中识别相对路径参数。
```
def source_paths
[File.expand_path(File.dirname(__FILE__))]
end
```
### 反馈
欢迎帮忙改善指南质量。
如发现任何错误，欢迎修正。开始贡献前，可先行阅读[贡献指南：文档](http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation)。
翻译如有错误，深感抱歉，欢迎 [Fork](https://github.com/ruby-china/guides/fork) 修正，或至此处[回报](https://github.com/ruby-china/guides/issues/new)。
文章可能有未完成或过时的内容。请先检查 [Edge Guides](http://edgeguides.rubyonrails.org) 来确定问题在 master 是否已经修掉了。再上 master 补上缺少的文件。内容参考 [Ruby on Rails 指南准则](ruby_on_rails_guides_guidelines.html)来了解行文风格。
最后，任何关于 Ruby on Rails 文档的讨论，欢迎到 [rubyonrails-docs 邮件群组](http://groups.google.com/group/rubyonrails-docs)。
- Ruby on Rails 指南 (651bba1)
- 入门
- Rails 入门
- 模型
- Active Record 基础
- Active Record 数据库迁移
- Active Record 数据验证
- Active Record 回调
- Active Record 关联
- Active Record 查询
- 视图
- Action View 基础
- Rails 布局和视图渲染
- 表单帮助方法
- 控制器
- Action Controller 简介
- Rails 路由全解
- 深入
- Active Support 核心扩展
- Rails 国际化 API
- Action Mailer 基础
- Active Job 基础
- Rails 程序测试指南
- Rails 安全指南
- 调试 Rails 程序
- 设置 Rails 程序
- Rails 命令行
- Rails 缓存简介
- Asset Pipeline
- 在 Rails 中使用 JavaScript
- 引擎入门
- Rails 应用的初始化过程
- Autoloading and Reloading Constants
- 扩展 Rails
- Rails 插件入门
- Rails on Rack
- 个性化Rails生成器与模板
- Rails应用模版
- 贡献 Ruby on Rails
- Contributing to Ruby on Rails
- API Documentation Guidelines
- Ruby on Rails Guides Guidelines
- Ruby on Rails 维护方针
- 发布记
- A Guide for Upgrading Ruby on Rails
- Ruby on Rails 4.2 发布记
- Ruby on Rails 4.1 发布记
- Ruby on Rails 4.0 Release Notes
- Ruby on Rails 3.2 Release Notes
- Ruby on Rails 3.1 Release Notes
- Ruby on Rails 3.0 Release Notes
- Ruby on Rails 2.3 Release Notes
- Ruby on Rails 2.2 Release Notes