Merge branch 'master' of git@github.com:lifo/docrails

4 files changed, 229 insertions, 9 deletions

diff --git a/railties/guides/source/credits.erb.textile b/railties/guides/source/credits.erb.textile
index b09a931fd6..512f4b0809 100644
--- a/railties/guides/source/credits.erb.textile
+++ b/railties/guides/source/credits.erb.textile
@@ -8,7 +8,7 @@ p. We'd like to thank the following people for their tireless contributions to t
 <h3 class="section">Rails Documentation Team</h3>
 
 <% author('Mike Gunderloy', 'mgunderloy') do %>
-  Mike Gunderloy is a consultant with "ActionRails":http://www.actionrails.com and also a member of the "Rails activism team":http://rubyonrails.org/activists . He brings 25 years of experience in a variety of languages to bear on his current work with Rails. His near-daily links and other blogging can be found at "A Fresh Cup":http://afreshcup.com and he "twitters":http://twitter.com/MikeG1 too much.
+  Mike Gunderloy is a consultant with "ActionRails":http://www.actionrails.com. He brings 25 years of experience in a variety of languages to bear on his current work with Rails. His near-daily links and other blogging can be found at "A Fresh Cup":http://afreshcup.com and he "twitters":http://twitter.com/MikeG1 too much.
 <% end %>
 
 <% author('Pratik Naik', 'lifo') do %>
diff --git a/railties/guides/source/layouts_and_rendering.textile b/railties/guides/source/layouts_and_rendering.textile
index 809d2b2172..d7573e6314 100644
--- a/railties/guides/source/layouts_and_rendering.textile
+++ b/railties/guides/source/layouts_and_rendering.textile
@@ -447,7 +447,7 @@ redirect_to :back
 
 h5. Getting a Different Redirect Status Code
 
-Rails uses HTTP status code 302 (permanent redirect) when you call +redirect_to+. If you'd like to use a different status code (perhaps 301, temporary redirect), you can do so by using the +:status+ option:
+Rails uses HTTP status code 302 (temporary redirect) when you call +redirect_to+. If you'd like to use a different status code (perhaps 301, permanent redirect), you can do so by using the +:status+ option:
 
 <ruby>
 redirect_to photos_path, :status => 301
diff --git a/railties/guides/source/rails_application_templates.textile b/railties/guides/source/rails_application_templates.textile
index 49cd5bf5f5..3068d0fd7f 100644
--- a/railties/guides/source/rails_application_templates.textile
+++ b/railties/guides/source/rails_application_templates.textile
@@ -1,18 +1,238 @@
 h2. Rails Application Templates
 
-This guide covers the Rails application templates, By referring to this guide, you will be able to:
+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 existing templates to generate a customized Rails application
-* Write your own reusable Rails application templates
+* Use templates to generate/customize Rails applications
+* Write your own reusable application templates using the Rails template API
 
 endprologue.
 
-h3. Introduction
+h3. Usage
 
-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.
+To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option :
+
+<shell>
+$ rails blog -m ~/template.rb
+</shell>
+
+It's also possible to apply a template using a URL :
+
+<shell>
+$ rails blog -m http://gist.github.com/31208.txt
+</shell>
+
+Alternatively, you can use the rake task +rails:template+ to apply a template to an existing Rails application :
+
+<shell>
+$ rake rails:template LOCATION=~/template.rb
+</shell>
+
+h3. Template API
+
+Rails templates API is very self explanatory and 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 "map.root :controller => 'people'"
+rake("db:migrate")
+
+git :init
+git :add => "."
+git :commit => "-a -m 'Initial commit'"
+</ruby>
+
+The following sections outlines the primary methods provided by the API :
+
+h4. 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+ :
+
+<ruby>
+gem "bj"
+gem "hpricot", :version => '0.6', :source => "http://code.whytheluckystiff.net"
+</ruby>
+
+Please note that this will NOT install the gems for you. So you may want to run the +rake gems:install+ task too :
+
+<ruby>
+rake "gems:install"
+</ruby>
+
+And let Rails take care of installing the required gems if they’re not already installed.
+
+h4. plugin(name, options = {})
+
+Installs a plugin to the generated application.
+
+Plugin can be installed from Git :
+
+<ruby>
+plugin 'authentication', :git => 'git://github.com/foor/bar.git'
+</ruby>
+
+You can even install plugins as git submodules :
+
+<ruby>
+plugin 'authentication', :git => 'git://github.com/foor/bar.git', 
+                         :submodule => true
+</ruby>
+
+Please note that you need to +git :init+ before you can install a plugin as a submodule.
+
+Or use plain old SVN :
+
+<ruby>
+plugin 'wtfsvn' :svn => 'svn://crap.com/wtf/trunk'
+</ruby>
+
+h4. 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?+ :
+
+<ruby>
+initializer 'bloatlol.rb', <<-CODE
+class Object
+  def not_nil?
+    !nil?
+  end
+  
+  def not_blank?
+    !blank?
+  end
+end
+CODE
+</ruby>
+
+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 :
+
+<ruby>
+file 'app/components/foo.rb', <<-CODE
+class Foo
+end
+CODE
+</ruby>
+
+That’ll create +app/components+ directory and put +foo.rb+ in there.
+
+h4. rakefile(filename, data = nil, &block)
+
+Creates a new rake file under +lib/tasks+ with the supplied tasks :
+
+<ruby>
+rakefile("bootstrap.rake") do
+  <<-TASK
+    namespace :boot do
+      task :strap do
+        puts "i like boots!"
+      end
+    end
+  TASK
+end
+</ruby>
+
+The above creates +lib/tasks/bootstrap.rake+ with a +boot:strap+ rake task.
+
+h4. generate(what, args)
+
+Runs the supplied rails generator with given arguments. For example, I love to scaffold some whenever I’m playing with Rails :
+
+<ruby>
+generate(:scaffold, "person", "name:string", "address:text", "age:number")
+</ruby>
+
+h4. run(command)
+
+Executes an arbitrary command. Just like the backticks. Let's say you want to remove the +public/index.html+ file :
+
+<ruby>
+run "rm public/index.html"
+</ruby>
+
+h4. rake(command, options = {})
+
+Runs the supplied rake tasks in the Rails application. Let's say you want to migrate the database :
+
+<ruby>
+rake "db:migrate"
+</ruby>
+
+You can also run rake tasks with a different Rails environment :
+
+<ruby>
+rake "db:migrate", :env => 'production'
+</ruby>
+
+Or even use sudo :
+
+<ruby>
+rake "gems:install", :sudo => true
+</ruby>
+
+h4. 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 :
+
+<ruby>
+route "map.root :controller => :person"
+</ruby>
+
+h4. 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 :
+
+<ruby>
+inside('vendor') do
+  run "ln -s ~/commit-rails/rails rails"
+end
+</ruby>
+
+So +inside()+ runs the command from the given directory.
+
+h4. 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 :
+
+<ruby>
+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
+</ruby>
+
+h4. 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 :
+
+<ruby>
+rake("rails:freeze:gems") if yes?("Freeze rails gems ?")
+no?(question) acts just the opposite.
+</ruby>
+
+h4. git(:must => "-a love")
+
+Rails templates let you run any git command :
+
+<ruby>
+git :init
+git :add => "."
+git :commit => "-a -m 'Initial commit'"
+</ruby>
 
 h3. Changelog
 
 "Lighthouse ticket":http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/78
 
-* April 17, 2009: Initial version by "Pratik":credits.html#lifo
+* April 29, 2009: Initial version by "Pratik":credits.html#lifo
diff --git a/railties/guides/source/security.textile b/railties/guides/source/security.textile
index 7b93fa7561..875c4ae6e5 100644
--- a/railties/guides/source/security.textile
+++ b/railties/guides/source/security.textile
@@ -967,7 +967,7 @@ Transfer-Encoding: chunked
 Content-Type: text/html
 </plain>
 
-Under certain circumstances this would present the malicious HTML to the victim. However, this seems to work with Keep-Alive connections, only (and many browsers are using one-time connections). But you can't rely on this. _(highlight)In any case this is a serious bug, and you should update your Rails to version 2.0.5 or 2.1.2 to eliminate Header Injection (and thus response splitting) risks._
+Under certain circumstances this would present the malicious HTML to the victim. However, this only seems to work with Keep-Alive connections (and many browsers are using one-time connections). But you can't rely on this. _(highlight)In any case this is a serious bug, and you should update your Rails to version 2.0.5 or 2.1.2 to eliminate Header Injection (and thus response splitting) risks._
 
 
 h3. Additional Resources