更多資訊請參考 rubyonrails.org:

Rails 應用程式範本

應用程式範本是簡單的 Ruby 檔案，其中包含用於將 gem、初始化程式等新增至新建立的 Rails 專案或現有 Rails 專案的 DSL。

閱讀本指南後，您將了解

  • 如何使用範本來產生/自訂 Rails 應用程式。
  • 如何使用 Rails 範本 API 撰寫您自己的可重複使用應用程式範本。

1 使用方式

若要套用範本，您需要使用 -m 選項將您希望套用的範本位置提供給 Rails 產生器。這可以是檔案的路徑或 URL。

$ rails new blog -m ~/template.rb
$ rails new blog -m http://example.com/template.rb

您可以使用 app:template rails 命令將範本套用至現有的 Rails 應用程式。範本的位置需要透過 LOCATION 環境變數傳入。同樣地，這可以是檔案的路徑或 URL。

$ bin/rails app:template LOCATION=~/template.rb
$ bin/rails app:template LOCATION=http://example.com/template.rb

2 範本 API

Rails 範本 API 很容易理解。以下是一個典型的 Rails 範例範本：

# template.rb
generate(:scaffold, "person name:string")
route "root to: 'people#index'"
rails_command("db:migrate")

after_bundle do
  git :init
  git add: "."
  git commit: %Q{ -m 'Initial commit' }
end

以下各節概述 API 提供的主要方法

2.1 gem(*args)

為提供的 gem 將 gem 項目新增至產生的應用程式的 Gemfile。

例如，如果您的應用程式依賴 gem bj 和 nokogiri

gem "bj"
gem "nokogiri"

請注意，此方法僅將 gem 新增至 Gemfile；它不會安裝 gem。

您也可以指定確切的版本

gem "nokogiri", "~> 1.16.4"

您也可以新增將會新增至 Gemfile 的註解

gem "nokogiri", "~> 1.16.4", comment: "Add the nokogiri gem for XML parsing"

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={}, &block)

將給定的來源新增至產生的應用程式的 Gemfile。

例如，如果您需要從 "http://gems.github.com" 來源 gem

add_source "http://gems.github.com"

如果提供區塊，區塊中的 gem 項目會包裝到來源群組中。

add_source "http://gems.github.com/" do
  gem "rspec-rails"
end

2.4 environment/application(data=nil, options={}, &block)

在 config/application.rb 的 Application 類別中新增一行。

如果指定 options[:env]，則該行會附加到 config/environments 中對應的檔案。

environment 'config.action_mailer.default_url_options = {host: "http://yourwebsite.example.com"}', env: "production"

可以使用區塊來代替 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/ 目錄中建立一個檔案。

甚至還有 file()，它接受來自 Rails.root 的相對路徑，並建立所有需要的目錄/檔案

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 rake 任務。

2.7 generate(what, *args)

以給定的引數執行提供的 rails 產生器。

generate(:scaffold, "person", "name:string", "address:text", "age:number")

2.8 run(command)

執行任意命令。就像反引號一樣。假設您想移除 README.rdoc 檔案

run "rm README.rdoc"

2.9 rails_command(command, options = {})

在 Rails 應用程式中執行提供的命令。假設您想要遷移資料庫

rails_command "db:migrate"

您也可以使用不同的 Rails 環境執行命令

rails_command "db:migrate", env: "production"

您也可以以超級使用者身分執行命令

rails_command "log:clear", sudo: true

您也可以執行如果失敗應中止應用程式產生的命令

rails_command "db:migrate", abort_on_failure: true

2.10 route(routing_code)

將路由項目新增至 config/routes.rb 檔案。在上述步驟中，我們產生了一個 person scaffold，也移除了 README.rdoc。現在，將 PeopleController#index 設定為應用程式的預設頁面

route "root to: 'person#index'"

2.11 inside(dir)

讓您可以從給定的目錄執行命令。例如，如果您有想要從新應用程式建立符號連結的 edge rails 副本，您可以執行此操作

inside("vendor") do
  run "ln -s ~/commit-rails/rails rails"
end

2.12 ask(question)

ask() 讓您有機會從使用者那裡取得一些意見反應，並在您的範本中使用它。假設您希望使用者命名您正在新增的新閃亮程式庫

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) 或 no?(question)

這些方法讓您可以從範本提出問題，並根據使用者的回答決定流程。假設您想要提示使用者執行遷移

rails_command("db:migrate") if yes?("Run database migrations?")
# no?(question) acts just the opposite.

2.14 git(:command)

Rails 範本讓您執行任何 git 命令

git :init
git add: "."
git commit: "-a -m 'Initial commit'"

2.15 after_bundle(&block)

註冊一個在 gem 捆綁且 binstubs 產生後執行的回呼。適用於將產生的檔案新增至版本控制

after_bundle do
  git :init
  git add: "."
  git commit: "-a -m 'Initial commit'"
end

即使已傳遞 --skip-bundle，也會執行回呼。

3 進階使用方式

應用程式範本會在 Rails::Generators::AppGenerator 執行個體的內容中評估。它使用 Thor 提供的 apply 動作。

這表示您可以擴展和變更執行個體以符合您的需求。

例如，覆寫 source_paths 方法以包含範本的位置。現在，copy_file 等方法將接受範本位置的相對路徑。

def source_paths
  [__dir__]
end
回到頂端