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

author: Vijay Dev <vijaydev.cse@gmail.com> 2012-09-01 23:51:23 +0530
committer: Vijay Dev <vijaydev.cse@gmail.com> 2012-09-01 23:51:23 +0530
commit: a6674991037fc360c7a72e7c28eec448f0231a3e (patch)
tree: f31b246cf779b8a09b4bc1d0db132c0e712d732b /guides
parent: 7f800b4d69c0750bb47989027580299751a22616 (diff)
parent: 831b814a8778aad0d038aab550b7d405d4a69d37 (diff)
download: rails-a6674991037fc360c7a72e7c28eec448f0231a3e.tar.gz
rails-a6674991037fc360c7a72e7c28eec448f0231a3e.tar.bz2
rails-a6674991037fc360c7a72e7c28eec448f0231a3e.zip
12 files changed, 91 insertions, 31 deletions
diff --git a/guides/source/action_controller_overview.textile b/guides/source/action_controller_overview.textile
index f861b233d2..1d43b44391 100644
--- a/guides/source/action_controller_overview.textile
+++ b/guides/source/action_controller_overview.textile
@@ -278,26 +278,31 @@ To reset the entire session, use +reset_session+.
 
 h4. The Flash
 
-The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for storing error messages etc. It is accessed in much the same way as the session, like a hash. Let's use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request:
+The flash is a special part of the session which is cleared with each request. This means that values stored there will only be available in the next request, which is useful for passing error messages etc.
+
+It is accessed in much the same way as the session, as a hash (it's a "FlashHash":http://api.rubyonrails.org/classes/ActionDispatch/Flash/FlashHash.html instance).
+
+Let's use the act of logging out as an example. The controller can send a message which will be displayed to the user on the next request:
 
 <ruby>
 class LoginsController < ApplicationController
   def destroy
     session[:current_user_id] = nil
-    flash[:notice] = "You have successfully logged out"
+    flash[:notice] = "You have successfully logged out."
     redirect_to root_url
   end
 end
 </ruby>
 
-Note it is also possible to assign a flash message as part of the redirection.
+Note that it is also possible to assign a flash message as part of the redirection. You can assign +:notice+, +:alert+ or the general purpose +:flash+:
 
 <ruby>
-redirect_to root_url, :notice => "You have successfully logged out"
+redirect_to root_url, :notice => "You have successfully logged out."
+redirect_to root_url, :alert => "You're stuck here!"
+redirect_to root_url, :flash => { :referral_code => 1234 }
 </ruby>
 
-
-The +destroy+ action redirects to the application's +root_url+, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display eventual errors or notices from the flash in the application's layout:
+The +destroy+ action redirects to the application's +root_url+, where the message will be displayed. Note that it's entirely up to the next action to decide what, if anything, it will do with what the previous action put in the flash. It's conventional to display any error alerts or notices from the flash in the application's layout:
 
 <ruby>
 <html>
@@ -306,15 +311,23 @@ The +destroy+ action redirects to the application's +root_url+, where the messag
     <% if flash[:notice] %>
       <p class="notice"><%= flash[:notice] %></p>
     <% end %>
-    <% if flash[:error] %>
-      <p class="error"><%= flash[:error] %></p>
+    <% if flash[:alert] %>
+      <p class="alert"><%= flash[:alert] %></p>
     <% end %>
     <!-- more content -->
   </body>
 </html>
 </ruby>
 
-This way, if an action sets an error or a notice message, the layout will display it automatically.
+This way, if an action sets a notice or an alert message, the layout will display it automatically.
+
+You can pass anything that the session can store; you're not limited to notices and alerts:
+
+<ruby>
+<% if flash[:just_signed_up] %>
+  <p class="welcome">Welcome to our site!</p>
+<% end %>
+</ruby>
 
 If you want a flash value to be carried over to another request, use the +keep+ method:
 
diff --git a/guides/source/action_mailer_basics.textile b/guides/source/action_mailer_basics.textile
index abfa68b76d..bca403ae72 100644
--- a/guides/source/action_mailer_basics.textile
+++ b/guides/source/action_mailer_basics.textile
@@ -451,7 +451,7 @@ The following configuration options are best made in one of the environment file
 
 |+template_root+|Determines the base from which template references will be made.|
 |+logger+|Generates information on the mailing run if available. Can be set to +nil+ for no logging. Compatible with both Ruby's own +Logger+ and +Log4r+ loggers.|
-|+smtp_settings+|Allows detailed configuration for <tt>:smtp</tt> delivery method:<ul><li><tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.</li><li><tt>:port</tt>  - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li><tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.</li><li><tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.</li><li><tt>:password</tt> - If your mail server requires authentication, set the password in this setting.</li><li><tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.</li></ul>|
+|+smtp_settings+|Allows detailed configuration for <tt>:smtp</tt> delivery method:<ul><li><tt>:address</tt> - Allows you to use a remote mail server. Just change it from its default "localhost" setting.</li><li><tt>:port</tt>  - On the off chance that your mail server doesn't run on port 25, you can change it.</li><li><tt>:domain</tt> - If you need to specify a HELO domain, you can do it here.</li><li><tt>:user_name</tt> - If your mail server requires authentication, set the username in this setting.</li><li><tt>:password</tt> - If your mail server requires authentication, set the password in this setting.</li><li><tt>:authentication</tt> - If your mail server requires authentication, you need to specify the authentication type here. This is a symbol and one of <tt>:plain</tt>, <tt>:login</tt>, <tt>:cram_md5</tt>.</li><li><tt>:enable_starttls_auto</tt> - Set this to <tt>false</tt> if there is a problem with your server certificate that you cannot resolve.</li></ul>|
 |+sendmail_settings+|Allows you to override options for the <tt>:sendmail</tt> delivery method.<ul><li><tt>:location</tt> - The location of the sendmail executable. Defaults to <tt>/usr/sbin/sendmail</tt>.</li><li><tt>:arguments</tt> - The command line arguments to be passed to sendmail. Defaults to <tt>-i -t</tt>.</li></ul>|
 |+raise_delivery_errors+|Whether or not errors should be raised if the email fails to be delivered.|
 |+delivery_method+|Defines a delivery method. Possible values are <tt>:smtp</tt> (default), <tt>:sendmail</tt>, <tt>:file</tt> and <tt>:test</tt>.|
diff --git a/guides/source/asset_pipeline.textile b/guides/source/asset_pipeline.textile
index e385ec4f17..2a15e95282 100644
--- a/guides/source/asset_pipeline.textile
+++ b/guides/source/asset_pipeline.textile
@@ -70,11 +70,11 @@ The query string strategy has several disadvantages:
 
 <ol>
   <li>
-    <strong>Not all caches will reliably cache content where the filename only differs by query parameters</strong>.<br>
+    <strong>Not all caches will reliably cache content where the filename only differs by query parameters</strong>.<br />
     "Steve Souders recommends":http://www.stevesouders.com/blog/2008/08/23/revving-filenames-dont-use-querystring/, "...avoiding a querystring for cacheable resources". He found that in this case 5-20% of requests will not be cached. Query strings in particular do not work at all with some CDNs for cache invalidation.
   </li>
   <li>
-    <strong>The file name can change between nodes in multi-server environments.</strong><br>
+    <strong>The file name can change between nodes in multi-server environments.</strong><br />
     The default query string in Rails 2.x is based on the modification time of the files. When assets are deployed to a cluster, there is no guarantee that the timestamps will be the same, resulting in different values being used depending on which server handles the request.
   </li>
   <li>
@@ -473,6 +473,7 @@ Precompiled assets exist on the filesystem and are served directly by your web s
 For Apache:
 
 <plain>
+# The Expires* directives requires the Apache module +mod_expires+ to be enabled.
 <LocationMatch "^/assets/.*$">
   # Use of ETag is discouraged when Last-Modified is present
   Header unset ETag
diff --git a/guides/source/contributing_to_ruby_on_rails.textile b/guides/source/contributing_to_ruby_on_rails.textile
index 4bb4e3b546..427733fe03 100644
--- a/guides/source/contributing_to_ruby_on_rails.textile
+++ b/guides/source/contributing_to_ruby_on_rails.textile
@@ -385,7 +385,7 @@ A CHANGELOG entry should summarize what was changed and should end with author's
 
     You can continue after the code example and you can attach issue number. GH#1234
 
-    * Your Name *
+    *Your Name*
 </plain>
 
 Your name can be added directly after the last word if you don't provide any code examples or don't need multiple paragraphs. Otherwise, it's best to make as a new paragraph.
diff --git a/guides/source/credits.html.erb b/guides/source/credits.html.erb
index 04deec6a11..e25168d58d 100644
--- a/guides/source/credits.html.erb
+++ b/guides/source/credits.html.erb
@@ -64,7 +64,7 @@ Oscar Del Ben is a software engineer at <a href="http://www.wildfireapp.com/">Wi
 <% end %>
 
 <%= author('Pratik Naik', 'lifo') do %>
-  Pratik Naik is a Ruby on Rails consultant with <a href="http://www.actionrails.com">ActionRails</a> and also a member of the <a href="http://rubyonrails.org/core">Rails core team</a>. He maintains a blog at <a href="http://m.onkey.org">has_many :bugs, :through =&gt; :rails</a> and has an active <a href="http://twitter.com/lifo">twitter account</a>.
+  Pratik Naik is a Ruby on Rails developer at <a href="http://www.37signals.com">37signals</a> and also a member of the <a href="http://rubyonrails.org/core">Rails core team</a>. He maintains a blog at <a href="http://m.onkey.org">has_many :bugs, :through =&gt; :rails</a> and has a semi-active <a href="http://twitter.com/lifo">twitter account</a>.
 <% end %>
 
 <%= author('Emilio Tagua', 'miloops') do %>
diff --git a/guides/source/engines.textile b/guides/source/engines.textile
index de4bbb5656..fe8fcfbb3f 100644
--- a/guides/source/engines.textile
+++ b/guides/source/engines.textile
@@ -217,7 +217,7 @@ This helps prevent conflicts with any other engine or application that may have
 
 Finally, two files that are the assets for this resource are generated, +app/assets/javascripts/blorgh/posts.js+ and +app/assets/javascripts/blorgh/posts.css+. You'll see how to use these a little later.
 
-By default, the scaffold styling is not applied to the engine as the engine's layout file, +app/views/blorgh/application.html.erb+ doesn't load it. To make this apply, insert this line into the +<head>+ tag of this layout:
+By default, the scaffold styling is not applied to the engine as the engine's layout file, +app/views/blorgh/application.html.erb+ doesn't load it. To make this apply, insert this line into the +&lt;head&gt;+ tag of this layout:
 
 <erb>
 <%= stylesheet_link_tag "scaffold" %>
@@ -369,7 +369,7 @@ This partial will be responsible for rendering just the comment text, for now. C
 <%= comment_counter + 1 %>. <%= comment.text %>
 </erb>
 
-The +comment_counter+ local variable is given to us by the +<%= render @post.comments %>+ call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created.
+The +comment_counter+ local variable is given to us by the +&lt;%= render @post.comments %&gt;+ call, as it will define this automatically and increment the counter as it iterates through each comment. It's used in this example to display a small number next to each comment when it's created.
 
 That completes the comment function of the blogging engine. Now it's time to use it within an application.
 
@@ -536,7 +536,7 @@ Finally, the author's name should be displayed on the post's page. Add this code
 </p>
 </erb>
 
-By outputting +@post.author+ using the +<%=+ tag the +to_s+ method will be called on the object. By default, this will look quite ugly:
+By outputting +@post.author+ using the +&lt;%=+ tag the +to_s+ method will be called on the object. By default, this will look quite ugly:
 
 <plain>
 #<User:0x00000100ccb3b0>
diff --git a/guides/source/form_helpers.textile b/guides/source/form_helpers.textile
index 58338ce54b..d507a04c1b 100644
--- a/guides/source/form_helpers.textile
+++ b/guides/source/form_helpers.textile
@@ -98,7 +98,7 @@ form_tag({:controller => "people", :action => "search"}, :method => "get", :clas
 
 h4. Helpers for Generating Form Elements
 
-Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as +text_field_tag+ and +check_box_tag+), generate just a single +&lt;input&gt;+ element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the +params+ hash in the controller with the value entered by the user for that field. For example, if the form contains +<%= text_field_tag(:query) %>+, then you would be able to get the value of this field in the controller with +params[:query]+.
+Rails provides a series of helpers for generating form elements such as checkboxes, text fields, and radio buttons. These basic helpers, with names ending in "_tag" (such as +text_field_tag+ and +check_box_tag+), generate just a single +&lt;input&gt;+ element. The first parameter to these is always the name of the input. When the form is submitted, the name will be passed along with the form data, and will make its way to the +params+ hash in the controller with the value entered by the user for that field. For example, if the form contains +&lt;%= text_field_tag(:query) %&gt;+, then you would be able to get the value of this field in the controller with +params[:query]+.
 
 When naming inputs, Rails uses certain conventions that make it possible to submit parameters with non-scalar values such as arrays or hashes, which will also be accessible in +params+. You can read more about them in "chapter 7 of this guide":#understanding-parameter-naming-conventions. For details on the precise usage of these helpers, please refer to the "API documentation":http://api.rubyonrails.org/classes/ActionView/Helpers/FormTagHelper.html.
 
@@ -654,7 +654,7 @@ If +f+ is an instance of FormBuilder then this will render the +form+ partial, s
 h3. Understanding Parameter Naming Conventions
 
 As you've seen in the previous sections, values from forms can be at the top level of the +params+ hash or nested in another hash. For example in a standard +create+
-action for a Person model, +params[:model]+ would usually be a hash of all the attributes for the person to create. The +params+ hash can also contain arrays, arrays of hashes and so on.
+action for a Person model, +params[:person]+ would usually be a hash of all the attributes for the person to create. The +params+ hash can also contain arrays, arrays of hashes and so on.
 
 Fundamentally HTML forms don't know about any sort of structured data, all they generate is name–value pairs, where pairs are just plain strings. The arrays and hashes you see in your application are the result of some parameter naming conventions that Rails uses.
 
diff --git a/guides/source/getting_started.textile b/guides/source/getting_started.textile
index 22da369a2a..226c3dce14 100644
--- a/guides/source/getting_started.textile
+++ b/guides/source/getting_started.textile
@@ -124,7 +124,7 @@ application. Most of the work in this tutorial will happen in the +app/+ folder,
 |config.ru|Rack configuration for Rack based servers used to start the application.|
 |db/|Contains your current database schema, as well as the database migrations.|
 |doc/|In-depth documentation for your application.|
-|Gemfile<BR />Gemfile.lock|These files allow you to specify what gem dependencies are needed for your Rails application. These files are used by the Bundler gem. For more information about Bundler, see "the Bundler website":http://gembundler.com |
+|Gemfile<br />Gemfile.lock|These files allow you to specify what gem dependencies are needed for your Rails application. These files are used by the Bundler gem. For more information about Bundler, see "the Bundler website":http://gembundler.com |
 |lib/|Extended modules for your application.|
 |log/|Application log files.|
 |public/|The only folder seen to the world as-is. Contains the static files and compiled assets.|
diff --git a/guides/source/plugins.textile b/guides/source/plugins.textile
index fbd317f0c2..50ea6b166a 100644
--- a/guides/source/plugins.textile
+++ b/guides/source/plugins.textile
@@ -174,11 +174,11 @@ require 'test_helper'
 class ActsAsYaffleTest < Test::Unit::TestCase
 
   def test_a_hickwalls_yaffle_text_field_should_be_last_squawk
-    assert_equal :last_squawk, Hickwall.yaffle_text_field
+    assert_equal "last_squawk", Hickwall.yaffle_text_field
   end
 
   def test_a_wickwalls_yaffle_text_field_should_be_last_tweet
-    assert_equal :last_tweet, Wickwall.yaffle_text_field
+    assert_equal "last_tweet", Wickwall.yaffle_text_field
   end
 
 end
diff --git a/guides/source/rails_application_templates.textile b/guides/source/rails_application_templates.textile
index f50ced3307..2fa40bc4cc 100644
--- a/guides/source/rails_application_templates.textile
+++ b/guides/source/rails_application_templates.textile
@@ -38,7 +38,7 @@ rake("db:migrate")
 
 git :init
 git :add => "."
-git :commit => "-a -m 'Initial commit'"
+git :commit => %Q{ -m 'Initial commit' }
 </ruby>
 
 The following sections outlines the primary methods provided by the API:
diff --git a/guides/source/security.textile b/guides/source/security.textile
index 773a47ab28..4c6c78a353 100644
--- a/guides/source/security.textile
+++ b/guides/source/security.textile
@@ -1019,6 +1019,47 @@ Content-Type: text/html
 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. Default Headers
+
+Every HTTP response from your Rails application receives the following default security headers.
+
+<ruby>
+config.action_dispatch.default_headers = {
+  'X-Frame-Options' => 'SAMEORIGIN',
+  'X-XSS-Protection' => '1; mode=block',
+  'X-Content-Type-Options' => 'nosniff'
+}
+</ruby>
+
+You can configure default headers in <ruby>config/application.rb</ruby>.
+
+<ruby>
+config.action_dispatch.default_headers = {
+  'Header-Name' => 'Header-Value',
+  'X-Frame-Options' => 'DENY'
+}
+</ruby>
+
+Or you can remove them.
+
+<ruby>
+config.action_dispatch.default_headers.clear
+</ruby>
+
+Here is the list of common headers:
+* X-Frame-Options
+_'SAMEORIGIN' in Rails by default_ - allow framing on same domain. Set it to 'DENY' to deny framing at all or 'ALLOWALL' if you want to allow framing for all website. 
+* X-XSS-Protection
+_'1; mode=block' in Rails by default_ - use XSS Auditor and block page if XSS attack is detected. Set it to '0;' if you want to switch XSS Auditor off(useful if response contents scripts from request parameters)
+* X-Content-Type-Options
+_'nosniff' in Rails by default_ - stops the browser from guessing the MIME type of a file.
+* X-Content-Security-Policy
+"A powerful mechanism for controlling which sites certain content types can be loaded from":http://dvcs.w3.org/hg/content-security-policy/raw-file/tip/csp-specification.dev.html
+* Access-Control-Allow-Origin
+Used to control which sites are allowed to bypass same origin policies and send cross-origin requests.
+* Strict-Transport-Security
+"Used to control if the browser is allowed to only access a site over a secure connection":http://en.wikipedia.org/wiki/HTTP_Strict_Transport_Security
+
 h3. Additional Resources
 
 The security landscape shifts and it is important to keep up to date, because missing a new vulnerability can be catastrophic. You can find additional resources about (Rails) security here:
diff --git a/guides/w3c_validator.rb b/guides/w3c_validator.rb
index 5e340499c4..6ef3df45a9 100644
--- a/guides/w3c_validator.rb
+++ b/guides/w3c_validator.rb
@@ -5,9 +5,9 @@
 # Guides are taken from the output directory, from where all .html files are
 # submitted to the validator.
 #
-# This script is prepared to be launched from the railties directory as a rake task:
+# This script is prepared to be launched from the guides directory as a rake task:
 #
-# rake validate_guides
+# rake guides:validate
 #
 # If nothing is specified, all files will be validated, but you can check just
 # some of them using this environment variable:
@@ -17,12 +17,12 @@
 #     enough:
 #
 #       # validates only association_basics.html
-#       ONLY=assoc rake validate_guides
+#       rake guides:validate ONLY=assoc
 #
 #     Separate many using commas:
 #
 #       # validates only association_basics.html and migrations.html
-#       ONLY=assoc,migrations rake validate_guides
+#       rake guides:validate ONLY=assoc,migrations
 #
 # ---------------------------------------------------------------------------
 
@@ -38,7 +38,12 @@ module RailsGuides
       errors_on_guides = {}
 
       guides_to_validate.each do |f|
-        results = validator.validate_file(f)
+        begin
+          results = validator.validate_file(f)
+        rescue Exception => e
+          puts "\nCould not validate #{f} because of #{e}"
+          next
+        end
 
         if results.validity
           print "."
@@ -53,15 +58,15 @@ module RailsGuides
 
     private
     def guides_to_validate
-      guides = Dir["./guides/output/*.html"]
-      guides.delete("./guides/output/layout.html")
+      guides = Dir["./output/*.html"]
+      guides.delete("./output/layout.html")
       ENV.key?('ONLY') ? select_only(guides) : guides
     end
 
     def select_only(guides)
       prefixes = ENV['ONLY'].split(",").map(&:strip)
       guides.select do |guide|
-        prefixes.any? {|p| guide.start_with?("./guides/output/#{p}")}
+        prefixes.any? {|p| guide.start_with?("./output/#{p}")}
       end
     end
author	Vijay Dev <vijaydev.cse@gmail.com>	2012-09-01 23:51:23 +0530
committer	Vijay Dev <vijaydev.cse@gmail.com>	2012-09-01 23:51:23 +0530
commit	a6674991037fc360c7a72e7c28eec448f0231a3e (patch)
tree	f31b246cf779b8a09b4bc1d0db132c0e712d732b /guides
parent	7f800b4d69c0750bb47989027580299751a22616 (diff)
parent	831b814a8778aad0d038aab550b7d405d4a69d37 (diff)
download	rails-a6674991037fc360c7a72e7c28eec448f0231a3e.tar.gz rails-a6674991037fc360c7a72e7c28eec448f0231a3e.tar.bz2 rails-a6674991037fc360c7a72e7c28eec448f0231a3e.zip