Ruby on Rails Guides: Rails Application Templates

1 Usage

To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option :

$ rails new blog -m ~/template.rb

It’s also possible to apply a template using a URL :

$ rails new blog -m http://gist.github.com/31208.txt

Alternatively, you can use the rake task rails:template to apply a template to an existing Rails application :

$ rake rails:template LOCATION=~/template.rb

2 Template API

Rails templates API is very self explanatory and easy to understand. Here’s an example of a typical Rails template :

# template.rb
run "rm public/index.html"
generate(:scaffold, "person name:string")
route "map.root :controller => 'people'"
rake("db:migrate")

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

The following sections outlines the primary methods provided by the API :

2.1 gem(name, options = {})

Adds a config.gem entry for the supplied gem to the generated application’s config/environment.rb.

For example, if your application depends on the gems bj and nokogiri :

gem "bj"
gem "nokogiri"

Please note that this will NOT install the gems for you. So you may want to run the rake gems:install task too :

rake "gems:install"

And let Rails take care of installing the required gems if they’re not already installed.

2.2 plugin(name, options = {})

Installs a plugin to the generated application.

Plugin can be installed from Git :

plugin 'authentication', :git => 'git://github.com/foor/bar.git'

You can even install plugins as git submodules :

plugin 'authentication', :git => 'git://github.com/foor/bar.git',
                         :submodule => true

Please note that you need to git :init before you can install a plugin as a submodule.

Or use plain old SVN :

plugin 'usingsvn', :svn => 'svn://example.com/usingsvn/trunk'

2.3 vendor/lib/file/initializer(filename, data = nil, &block)

Adds an initializer to the generated application’s config/initializers directory.

Lets say you like using Object#not_nil? and Object#not_blank? :

initializer 'bloatlol.rb', <<-CODE
class Object
  def not_nil?
    !nil?
  end

  def not_blank?
    !blank?
  end
end
CODE

Similarly lib() creates a file in the lib/ directory and vendor() creates a file in the vendor/ directory.

There is even file(), which accepts a relative path from Rails.root and creates all the directories/file needed :

file 'app/components/foo.rb', <<-CODE
class Foo
end
CODE

That’ll create app/components directory and put foo.rb in there.

2.4 rakefile(filename, data = nil, &block)

Creates a new rake file under lib/tasks with the supplied tasks :

rakefile("bootstrap.rake") do
  <<-TASK
    namespace :boot do
      task :strap do
        puts "i like boots!"
      end
    end
  TASK
end

The above creates lib/tasks/bootstrap.rake with a boot:strap rake task.

2.5 generate(what, args)

Runs the supplied rails generator with given arguments. For example, I love to scaffold some whenever I’m playing with Rails :

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

2.6 run(command)

Executes an arbitrary command. Just like the backticks. Let’s say you want to remove the public/index.html file :

run "rm public/index.html"

2.7 rake(command, options = {})

Runs the supplied rake tasks in the Rails application. Let’s say you want to migrate the database :

rake "db:migrate"

You can also run rake tasks with a different Rails environment :

rake "db:migrate", :env => 'production'

Or even use sudo :

rake "gems:install", :sudo => true

2.8 route(routing_code)

This adds a routing entry to the config/routes.rb file. In above steps, we generated a person scaffold and also removed public/index.html. Now to make PeopleController#index as the default page for the application :

route "map.root :controller => :person"

2.9 inside(dir)

I have my edge rails lying at ~/commit-rails/rails. So every time i have to manually symlink edge from my new app. But now :

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

So inside() runs the command from the given directory.

2.10 ask(question)

ask() gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding :

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.11 yes?(question) or no?(question)

These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to :

rake("rails:freeze:gems") if yes?("Freeze rails gems ?")
no?(question) acts just the opposite.

2.12 git(:must => “-a love”)

Rails templates let you run any git command :

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

3 Changelog

April 29, 2009: Initial version by Pratik

Feedback

You're encouraged to help in keeping the quality of this guide.

If you see any typos or factual errors you are confident to patch please clone docrails and push the change yourself. That branch of Rails has public write access. Commits are still reviewed, but that happens after you've submitted your contribution. docrails is cross-merged with master periodically.

You may also find incomplete content, or stuff that is not up to date. Please do add any missing documentation for master. Check the Ruby on Rails Guides Guidelines guide for style and conventions.

Issues may also be reported in Github.

And last but not least, any kind of discussion regarding Ruby on Rails documentation is very welcome in the rubyonrails-docs mailing list.

Guides.rubyonrails.org

Rails Application Templates

Chapters