diff options
Diffstat (limited to 'guides/source/rails_application_templates.md')
| -rw-r--r-- | guides/source/rails_application_templates.md | 82 |
1 files changed, 59 insertions, 23 deletions
diff --git a/guides/source/rails_application_templates.md b/guides/source/rails_application_templates.md index 9e694acb98..6512b14e60 100644 --- a/guides/source/rails_application_templates.md +++ b/guides/source/rails_application_templates.md @@ -13,7 +13,7 @@ After reading this guide, you will know: 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. This can either be path to a file or a URL. +To apply a template, you need to provide the Rails generator with the location of the template you wish to apply using the -m option. This can either be a path to a file or a URL. ```bash $ rails new blog -m ~/template.rb @@ -23,32 +23,33 @@ $ rails new blog -m http://example.com/template.rb 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. ```bash -$ rake rails:template LOCATION=~/template.rb -$ rake rails:template LOCATION=http://example.com/template.rb +$ bin/rake rails:template LOCATION=~/template.rb +$ bin/rake rails:template LOCATION=http://example.com/template.rb ``` Template API ------------ -Rails templates API is very self explanatory and easy to understand. Here's an example of a typical Rails template: +The Rails templates API is easy to understand. Here's an example of a typical Rails template: ```ruby # template.rb -run "rm public/index.html" generate(:scaffold, "person name:string") route "root to: 'people#index'" rake("db:migrate") -git :init -git add: "." -git commit: %Q{ -m 'Initial commit' } +after_bundle do + git :init + git add: "." + git commit: %Q{ -m 'Initial commit' } +end ``` -The following sections outlines the primary methods provided by the API: +The following sections outline the primary methods provided by the API: ### gem(*args) -Adds a `gem` entry for the supplied gem to the generated application’s `Gemfile`. +Adds a `gem` entry for the supplied gem to the generated application's `Gemfile`. For example, if your application depends on the gems `bj` and `nokogiri`: @@ -67,7 +68,7 @@ bundle install Wraps gem entries inside a group. -For example, if you want to load `rspec-rails` only in `development` and `test` group: +For example, if you want to load `rspec-rails` only in the `development` and `test` groups: ```ruby gem_group :development, :test do @@ -79,7 +80,7 @@ end Adds the given source to the generated application's `Gemfile`. -For example, if you need to source a gem from "http://code.whytheluckystiff.net": +For example, if you need to source a gem from `"http://code.whytheluckystiff.net"`: ```ruby add_source "http://code.whytheluckystiff.net" @@ -92,16 +93,16 @@ Adds a line inside the `Application` class for `config/application.rb`. If `options[:env]` is specified, the line is appended to the corresponding file in `config/environments`. ```ruby -environment 'config.action_mailer.default_url_options = {host: 'http://yourwebsite.example.com'}, env: 'production' +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) -Adds an initializer to the generated application’s `config/initializers` directory. +Adds an initializer to the generated application's `config/initializers` directory. -Lets say you like using `Object#not_nil?` and `Object#not_blank?`: +Let's say you like using `Object#not_nil?` and `Object#not_blank?`: ```ruby initializer 'bloatlol.rb', <<-CODE @@ -117,9 +118,9 @@ initializer 'bloatlol.rb', <<-CODE CODE ``` -Similarly `lib()` creates a file in the `lib/` directory and `vendor()` creates a file in the `vendor/` directory. +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: +There is even `file()`, which accepts a relative path from `Rails.root` and creates all the directories/files needed: ```ruby file 'app/components/foo.rb', <<-CODE @@ -128,7 +129,7 @@ file 'app/components/foo.rb', <<-CODE CODE ``` -That’ll create `app/components` directory and put `foo.rb` in there. +That'll create the `app/components` directory and put `foo.rb` in there. ### rakefile(filename, data = nil, &block) @@ -158,10 +159,10 @@ 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: +Executes an arbitrary command. Just like the backticks. Let's say you want to remove the `README.rdoc` file: ```ruby -run "rm public/index.html" +run "rm README.rdoc" ``` ### rake(command, options = {}) @@ -180,7 +181,7 @@ rake "db:migrate", env: 'production' ### route(routing_code) -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: +Adds a routing entry to the `config/routes.rb` file. In the steps above, we generated a person scaffold and also removed `README.rdoc`. Now, to make `PeopleController#index` the default page for the application: ```ruby route "root to: 'person#index'" @@ -198,7 +199,7 @@ end ### 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: +`ask()` gives you a chance to get some feedback from the user and use it in your templates. Let's say you want your user to name the new shiny library you're adding: ```ruby lib_name = ask("What do you want to call the shiny library ?") @@ -212,7 +213,7 @@ 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: +These methods let you ask questions from templates and decide the flow based on the user's answer. Let's say you want to freeze rails only if the user wants to: ```ruby rake("rails:freeze:gems") if yes?("Freeze rails gems?") @@ -228,3 +229,38 @@ git :init git add: "." git commit: "-a -m 'Initial commit'" ``` + +### after_bundle(&block) + +Registers a callback to be executed after the gems are bundled and binstubs +are generated. Useful for all generated files to version control: + +```ruby +after_bundle do + git :init + git add: '.' + git commit: "-a -m 'Initial commit'" +end +``` + +The callbacks gets executed even if `--skip-bundle` and/or `--skip-spring` has +been passed. + +Advanced Usage +-------------- + +The application template is evaluated in the context of a +`Rails::Generators::AppGenerator` instance. It uses the `apply` action +provided by +[Thor](https://github.com/erikhuda/thor/blob/master/lib/thor/actions.rb#L207). +This means you can extend and change the instance to match your needs. + +For example by overwriting the `source_paths` method to contain the +location of your template. Now methods like `copy_file` will accept +relative paths to your template's location. + +```ruby +def source_paths + [File.expand_path(File.dirname(__FILE__))] +end +``` |