Permalink
Browse files

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

  • Loading branch information...
vijaydev committed Sep 1, 2012
2 parents 7f800b4 + 831b814 commit a6674991037fc360c7a72e7c28eec448f0231a3e
@@ -2,7 +2,7 @@
module ActionDispatch
class Request < Rack::Request
- # SessionHash is responsible to lazily load the session from store.
+ # Session is responsible for lazily loading the session from store.
class Session # :nodoc:
ENV_SESSION_KEY = Rack::Session::Abstract::ENV_SESSION_KEY # :nodoc:
ENV_SESSION_OPTIONS_KEY = Rack::Session::Abstract::ENV_SESSION_OPTIONS_KEY # :nodoc:
@@ -117,6 +117,10 @@ def form_tag(url_for_options = {}, options = {}, &block)
# select_tag "destination", "<option>NYC</option><option>Paris</option><option>Rome</option>".html_safe, :disabled => true
# # => <select disabled="disabled" id="destination" name="destination"><option>NYC</option>
# # <option>Paris</option><option>Rome</option></select>
+ #
+ # select_tag "credit_card", options_for_select([ "VISA", "MasterCard" ], "MasterCard")
+ # # => <select id="credit_card" name="credit_card"><option>VISA</option>
+ # # <option selected="selected">MasterCard</option></select>
def select_tag(name, option_tags = nil, options = {})
option_tags ||= ""
html_name = (options[:multiple] == true && !name.to_s.ends_with?("[]")) ? "#{name}[]" : name
@@ -84,6 +84,7 @@ def advance(options)
end
# Returns a new Date where one or more of the elements have been changed according to the +options+ parameter.
+ # The +options+ parameter is a hash with a combination of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>.
#
# Date.new(2007, 5, 12).change(:day => 1) # => Date.new(2007, 5, 1)
# Date.new(2007, 5, 12).change(:year => 2005, :month => 1) # => Date.new(2005, 1, 12)
@@ -31,8 +31,13 @@ def seconds_since_midnight
end
# Returns a new DateTime where one or more of the elements have been changed according to the +options+ parameter. The time options
- # (hour, minute, sec) reset cascadingly, so if only the hour is passed, then minute and sec is set to 0. If the hour and
- # minute is passed, then sec is set to 0.
+ # (<tt>:hour</tt>, <tt>:minute</tt>, <tt>:sec</tt>) reset cascadingly, so if only the hour is passed, then minute and sec is set to 0. If the hour and
+ # minute is passed, then sec is set to 0. The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>, <tt>:month</tt>, <tt>:day</tt>,
+ # <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:offset</tt>, <tt>:start</tt>.
+ #
+ # DateTime.new(2012, 8, 29, 22, 35, 0).change(:day => 1) # => DateTime.new(2012, 8, 1, 22, 35, 0)
+ # DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1) # => DateTime.new(1981, 8, 1, 22, 35, 0)
+ # DateTime.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0) # => DateTime.new(1981, 8, 29, 0, 0, 0)
def change(options)
::DateTime.civil(
options.fetch(:year, year),
@@ -63,8 +63,13 @@ def seconds_since_midnight
end
# Returns a new Time where one or more of the elements have been changed according to the +options+ parameter. The time options
- # (hour, min, sec, usec) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0. If the hour and
- # minute is passed, then sec and usec is set to 0.
+ # (<tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>) reset cascadingly, so if only the hour is passed, then minute, sec, and usec is set to 0.
+ # If the hour and minute is passed, then sec and usec is set to 0. The +options+ parameter takes a hash with any of these keys: <tt>:year</tt>,
+ # <tt>:month</tt>, <tt>:day</tt>, <tt>:hour</tt>, <tt>:min</tt>, <tt>:sec</tt>, <tt>:usec</tt>.
+ #
+ # Time.new(2012, 8, 29, 22, 35, 0).change(:day => 1) # => Time.new(2012, 8, 1, 22, 35, 0)
+ # Time.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :day => 1) # => Time.new(1981, 8, 1, 22, 35, 0)
+ # Time.new(2012, 8, 29, 22, 35, 0).change(:year => 1981, :hour => 0) # => Time.new(1981, 8, 29, 0, 0, 0)
def change(options)
new_year = options.fetch(:year, year)
new_month = options.fetch(:month, month)
@@ -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:
@@ -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>.|
@@ -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
@@ -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.
@@ -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 %>
@@ -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>
@@ -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.
@@ -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.|
@@ -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
@@ -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:
Oops, something went wrong.

0 comments on commit a667499

Please sign in to comment.