1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
rails--rails/guides/source/rails_application_templates.md

231 lines
5.7 KiB
Markdown
Raw Normal View History

Rails Application Templates
===========================
2009-04-17 09:28:46 -04:00
2012-01-02 15:49:18 -05:00
Application templates are simple Ruby files containing DSL for adding gems/initializers etc. to your freshly created Rails project or an existing Rails project.
2009-07-25 11:03:58 -04:00
After reading this guide, you will know:
2009-04-17 09:28:46 -04:00
* How to use templates to generate/customize Rails applications.
* How to write your own reusable application templates using the Rails template API.
2009-04-17 09:28:46 -04:00
--------------------------------------------------------------------------------
2009-04-17 09:28:46 -04:00
Usage
-----
2009-04-17 09:28:46 -04:00
2011-07-22 16:51:05 -04:00
To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option. This can either be path to a file or a URL.
2009-07-25 11:03:58 -04:00
2012-09-01 20:45:26 -04:00
```bash
$ rails new blog -m ~/template.rb
2011-07-22 16:51:05 -04:00
$ rails new blog -m http://example.com/template.rb
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
You can use the rake task `rails:template` to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named LOCATION. Again, this can either be path to a file or a URL.
2009-07-25 11:03:58 -04:00
2012-09-01 20:45:26 -04:00
```bash
2009-07-25 11:03:58 -04:00
$ rake rails:template LOCATION=~/template.rb
2011-07-22 16:51:05 -04:00
$ rake rails:template LOCATION=http://example.com/template.rb
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
Template API
------------
2009-07-25 11:03:58 -04:00
2011-04-13 20:58:26 -04:00
Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
# template.rb
run "rm public/index.html"
generate(:scaffold, "person name:string")
2012-11-16 05:30:12 -05:00
route "root to: 'people#index'"
2009-07-25 11:03:58 -04:00
rake("db:migrate")
git :init
2012-11-16 05:30:12 -05:00
git add: "."
git commit: %Q{ -m 'Initial commit' }
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
2011-04-13 20:58:26 -04:00
The following sections outlines the primary methods provided by the API:
2009-07-25 11:03:58 -04:00
### gem(*args)
2009-07-25 11:03:58 -04:00
Adds a `gem` entry for the supplied gem to the generated applications `Gemfile`.
2009-07-25 11:03:58 -04:00
For example, if your application depends on the gems `bj` and `nokogiri`:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
gem "bj"
gem "nokogiri"
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
Please note that this will NOT install the gems for you and you will have to run `bundle install` to do that.
2009-07-25 11:03:58 -04:00
```bash
2011-06-11 12:01:45 -04:00
bundle install
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### gem_group(*names, &block)
2011-09-04 04:14:53 -04:00
Wraps gem entries inside a group.
For example, if you want to load `rspec-rails` only in `development` and `test` group:
2011-09-04 04:14:53 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2011-09-04 04:14:53 -04:00
gem_group :development, :test do
gem "rspec-rails"
end
2012-09-01 17:08:06 -04:00
```
2011-09-04 04:14:53 -04:00
### add_source(source, options = {})
Adds the given source to the generated application's `Gemfile`.
For example, if you need to source a gem from "http://code.whytheluckystiff.net":
2012-09-01 17:08:06 -04:00
```ruby
add_source "http://code.whytheluckystiff.net"
2012-09-01 17:08:06 -04:00
```
### environment/application(data=nil, options={}, &block)
Adds a line inside the `Application` class for `config/application.rb`.
2012-11-16 14:43:52 -05:00
If `options[:env]` is specified, the line is appended to the corresponding file in `config/environments`.
```ruby
2012-11-16 05:30:12 -05:00
environment 'config.action_mailer.default_url_options = {host: 'http://yourwebsite.example.com'}, env: 'production'
```
A block can be used in place of the `data` argument.
### vendor/lib/file/initializer(filename, data = nil, &block)
2009-07-25 11:03:58 -04:00
Adds an initializer to the generated applications `config/initializers` directory.
2009-07-25 11:03:58 -04:00
Lets say you like using `Object#not_nil?` and `Object#not_blank?`:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
initializer 'bloatlol.rb', <<-CODE
class Object
def not_nil?
!nil?
end
def not_blank?
!blank?
end
2009-07-25 11:03:58 -04:00
end
CODE
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
Similarly `lib()` creates a file in the `lib/` directory and `vendor()` creates a file in the `vendor/` directory.
2009-07-25 11:03:58 -04:00
There is even `file()`, which accepts a relative path from `Rails.root` and creates all the directories/file needed:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
file 'app/components/foo.rb', <<-CODE
class Foo
end
2009-07-25 11:03:58 -04:00
CODE
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
Thatll create `app/components` directory and put `foo.rb` in there.
2009-07-25 11:03:58 -04:00
### rakefile(filename, data = nil, &block)
2009-07-25 11:03:58 -04:00
Creates a new rake file under `lib/tasks` with the supplied tasks:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
rakefile("bootstrap.rake") do
<<-TASK
namespace :boot do
task :strap do
puts "i like boots!"
end
end
TASK
end
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
The above creates `lib/tasks/bootstrap.rake` with a `boot:strap` rake task.
2009-07-25 11:03:58 -04:00
### generate(what, *args)
2009-07-25 11:03:58 -04:00
2011-08-15 11:06:32 -04:00
Runs the supplied rails generator with given arguments.
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
generate(:scaffold, "person", "name:string", "address:text", "age:number")
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### run(command)
2009-07-25 11:03:58 -04:00
Executes an arbitrary command. Just like the backticks. Let's say you want to remove the `public/index.html` file:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
run "rm public/index.html"
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### rake(command, options = {})
2009-07-25 11:03:58 -04:00
2011-04-13 20:58:26 -04:00
Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
rake "db:migrate"
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
2011-04-13 20:58:26 -04:00
You can also run rake tasks with a different Rails environment:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2012-11-16 05:30:12 -05:00
rake "db:migrate", env: 'production'
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### route(routing_code)
2009-07-25 11:03:58 -04:00
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:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2012-11-16 05:30:12 -05:00
route "root to: 'person#index'"
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### inside(dir)
2009-07-25 11:03:58 -04:00
2011-02-20 11:01:12 -05:00
Enables you to run a command from the given directory. For example, if you have a copy of edge rails that you wish to symlink from your new apps, you can do this:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
inside('vendor') do
run "ln -s ~/commit-rails/rails rails"
end
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### ask(question)
2009-07-25 11:03:58 -04:00
`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 youre adding:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
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
2009-07-25 11:03:58 -04:00
CODE
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### yes?(question) or no?(question)
2009-07-25 11:03:58 -04:00
2011-04-13 20:58:26 -04:00
These methods let you ask questions from templates and decide the flow based on the users answer. Lets say you want to freeze rails only if the user want to:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2012-11-16 05:31:14 -05:00
rake("rails:freeze:gems") if yes?("Freeze rails gems?")
# no?(question) acts just the opposite.
2012-09-01 17:08:06 -04:00
```
2009-07-25 11:03:58 -04:00
### git(:command)
2009-07-25 11:03:58 -04:00
2011-04-13 20:58:26 -04:00
Rails templates let you run any git command:
2009-07-25 11:03:58 -04:00
2012-09-01 17:08:06 -04:00
```ruby
2009-07-25 11:03:58 -04:00
git :init
2012-11-16 05:30:12 -05:00
git add: "."
git commit: "-a -m 'Initial commit'"
2012-09-01 17:08:06 -04:00
```