Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
tree: e6f2102178
Fetching contributors…

Cannot retrieve contributors at this time

239 lines (160 sloc) 5.924 kb

Rails Application Templates

Application templates are simple ruby files containing DSL for adding plugins/gems/initializers etc. to your freshly created Rails project or an existing Rails project.

By referring to this guide, you will be able to:

  • Use templates to generate/customize Rails applications
  • Write your own reusable application templates using the Rails template API

endprologue.

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

Template API

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

  1. 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 :

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 hpricot :

gem “bj”
gem “hpricot”, :version => ‘0.6’, :source => “http://code.whytheluckystiff.net”

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.

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’

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.

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.

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”)

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”

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

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”

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.

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

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.

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

Rails templates let you run any git command :

git :init
git :add => “.”
git :commit => “-a -m ‘Initial commit’”

Changelog

Lighthouse ticket

  • April 29, 2009: Initial version by Pratik
Jump to Line
Something went wrong with that request. Please try again.