diff options
Diffstat (limited to 'railties/guides')
7 files changed, 169 insertions, 31 deletions
diff --git a/railties/guides/source/action_controller_overview.textile b/railties/guides/source/action_controller_overview.textile index 038ca903c1..ec2d5b2787 100644 --- a/railties/guides/source/action_controller_overview.textile +++ b/railties/guides/source/action_controller_overview.textile @@ -162,23 +162,38 @@ If you need a different session storage mechanism, you can change it in the +con # Use the database for sessions instead of the cookie-based default, # which shouldn't be used to store highly confidential information # (create the session table with "rake db:sessions:create") -# ActionController::Base.session_store = :active_record_store +# YourApp::Application.config.session_store :active_record_store </ruby> -Rails sets up a session key (the name of the cookie) and (for the CookieStore) a secret key used when signing the session data. These can also be changed in +config/initializers/session_store.rb+: +Rails sets up a session key (the name of the cookie) when signing the session data. These can also be changed in +config/initializers/session_store.rb+: <ruby> -# Your secret key for verifying cookie session data integrity. -# If you change this key, all old sessions will become invalid! -# Make sure the secret is at least 30 characters and all random, +# Be sure to restart your server when you modify this file. + +YourApp::Application.config.session_store :cookie_store, :key => '_your_app_session' +</ruby> + +You can also pass a +:domain+ key and specify the domain name for the cookie: + +<ruby> +# Be sure to restart your server when you modify this file. + +YourApp::Application.config.session_store :cookie_store, :key => '_your_app_session', :domain => ".example.com" +</ruby> + +Rails sets up (for the CookieStore) a secret key used for signing the session data. This can be changed in +config/initializers/secret_token.rb+ + +<ruby> +# Be sure to restart your server when you modify this file. + +# Your secret key for verifying the integrity of signed cookies. +# If you change this key, all old signed cookies will become invalid! +# Make sure the secret is at least 30 characters and all random, # no regular words or you'll be exposed to dictionary attacks. -ActionController::Base.session = { - :key => '_yourappname_session', - :secret => '4f50711b8f0f49572...' -} +YourApp::Application.config.secret_token = '49d3f3de9ed86c74b94ad6bd0...' </ruby> -NOTE: Changing the secret when using the CookieStore will invalidate all existing sessions. +NOTE: Changing the secret when using the +CookieStore+ will invalidate all existing sessions. h4. Accessing the Session diff --git a/railties/guides/source/active_record_querying.textile b/railties/guides/source/active_record_querying.textile index 5c4ed3a803..53095a2bd3 100644 --- a/railties/guides/source/active_record_querying.textile +++ b/railties/guides/source/active_record_querying.textile @@ -764,7 +764,7 @@ This loads all the posts and the associated category and comments for each post. h5. Nested Associations Hash <ruby> -Category.find(1).includes(:posts => [{:comments => :guest}, :tags]) +Category.includes(:posts => [{:comments => :guest}, :tags]).find(1) </ruby> This will find the category with id 1 and eager load all of the associated posts, the associated posts' tags and comments, and every comment's guest association. diff --git a/railties/guides/source/active_support_core_extensions.textile b/railties/guides/source/active_support_core_extensions.textile index 136fcde82a..9a449debae 100644 --- a/railties/guides/source/active_support_core_extensions.textile +++ b/railties/guides/source/active_support_core_extensions.textile @@ -2979,11 +2979,11 @@ Note in the previous example that increments may be negative. To perform the computation the method first increments years, then months, then weeks, and finally days. This order is important towards the end of months. Say for example we are at the end of February of 2010, and we want to move one month and one day forward. -The method +advance+ advances first one month, and the one day, the result is: +The method +advance+ advances first one month, and then one day, the result is: <ruby> -Date.new(2010, 2, 28).advance(:months => 1, :day => 1) -# => Sun, 28 Mar 2010 +Date.new(2010, 2, 28).advance(:months => 1, :days => 1) +# => Sun, 29 Mar 2010 </ruby> While if it did it the other way around the result would be different: @@ -3053,30 +3053,30 @@ h4(#date-conversions). Conversions h3. Extensions to +DateTime+ -NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+. - WARNING: +DateTime+ is not aware of DST rules and so some of these methods have edge cases when a DST change is going on. For example +seconds_since_midnight+ might not return the real amount in such a day. h4(#calculations-datetime). Calculations +NOTE: All the following methods are defined in +active_support/core_ext/date_time/calculations.rb+. + The class +DateTime+ is a subclass of +Date+ so by loading +active_support/core_ext/date/calculations.rb+ you inherit these methods and their aliases, except that they will always return datetimes: <ruby> yesterday tomorrow -beginning_of_week -end_on_week +beginning_of_week (monday, at_beginning_of_week) +end_on_week (at_end_of_week) next_week months_ago months_since -beginning_of_month -end_of_month +beginning_of_month (at_beginning_of_month) +end_of_month (at_end_of_month) prev_month next_month -beginning_of_quarter -end_of_quarter -beginning_of_year -end_of_year +beginning_of_quarter (at_beginning_of_quarter) +end_of_quarter (at_end_of_quarter) +beginning_of_year (at_beginning_of_year) +end_of_year (at_end_of_year) years_ago years_since prev_year @@ -3086,10 +3086,10 @@ next_year The following methods are reimplemented so you do *not* need to load +active_support/core_ext/date/calculations.rb+ for these ones: <ruby> -beginning_of_day +beginning_of_day (midnight, at_midnight, at_beginning_of_day) end_of_day ago -since +since (in) </ruby> On the other hand, +advance+ and +change+ are also defined and support more options, they are documented below. @@ -3132,6 +3132,37 @@ now.utc? # => false now.utc.utc? # => true </ruby> +h6(#datetime-advance). +advance+ + +The most generic way to jump to another datetime is +advance+. This method receives a hash with keys +:years+, +:months+, +:weeks+, +:days+, +:hours+, +:minutes+, and +:seconds+, and returns a datetime advanced as much as the present keys indicate. + +<ruby> +d = DateTime.current +# => Thu, 05 Aug 2010 11:33:31 +0000 +d.advance(:years => 1, :months => 1, :days => 1, :hours => 1, :minutes => 1, :seconds => 1) +# => Tue, 06 Sep 2011 12:34:32 +0000 +</ruby> + +This method first computes the destination date passing +:years+, +:months+, +:weeks+, and +:days+ to +Date#advance+ documented above. After that, it adjusts the time calling +since+ with the number of seconds to advance. This order is relevant, a different ordering would give different datetimes in some edge-cases. The example in +Date#advance+ applies, and we can extend it to show order relevance related to the time bits. + +If we first move the date bits (that have also a relative order of processing, as documented before), and then the time bits we get for example the following computation: + +<ruby> +d = DateTime.new(2010, 2, 28, 23, 59, 59) +# => Sun, 28 Feb 2010 23:59:59 +0000 +d.advance(:months => 1, :seconds => 1) +# => Mon, 29 Mar 2010 00:00:00 +0000 +</ruby> + +but if we computed them the other way around, the result would be different: + +<ruby> +d.advance(:seconds => 1).advance(:months => 1) +# => Thu, 01 Apr 2010 00:00:00 +0000 +</ruby> + +WARNING: Since +DateTime+ is not DST-aware you can end up in a non-existing point in time with no warning or error telling you so. + h5(#datetime-changing-components). Changing Components The method +change+ allows you to get a new datetime which is the same as the receiver except for the given options, which may include +:year+, +:month+, +:day+, +:hour+, +:min+, +:sec+, +:offset+, +:start+: @@ -3168,7 +3199,93 @@ h4(#datetime-conversions). Conversions h3. Extensions to +Time+ -... +h4(#time-calculations). Calculations + +NOTE: All the following methods are defined in +active_support/core_ext/time/calculations.rb+. + +Active Support adds to +Time+ many of the methods available for +DateTime+: + +<ruby> +past? +today? +future? +yesterday +tomorrow +seconds_since_midnight +change +advance +ago +since (in) +beginning_of_day (midnight, at_midnight, at_beginning_of_day) +end_of_day +beginning_of_week (monday, at_beginning_of_week) +end_on_week (at_end_of_week) +next_week +months_ago +months_since +beginning_of_month (at_beginning_of_month) +end_of_month (at_end_of_month) +prev_month +next_month +beginning_of_quarter (at_beginning_of_quarter) +end_of_quarter (at_end_of_quarter) +beginning_of_year (at_beginning_of_year) +end_of_year (at_end_of_year) +years_ago +years_since +prev_year +next_year +</ruby> + +They are analogous. Please refer to their documentation above and take into account the following differences: + +* +change+ accepts an additional +:usec+ option. +* +Time+ understands DST, so you get correct DST calculations as in + +<ruby> +# In Barcelona, 2010/03/28 02:00 +0100 becomes 2010/03/28 03:00 +0200 due to DST. +t = Time.local_time(2010, 3, 28, 1, 59, 59) +# => Sun Mar 28 01:59:59 +0100 2010 +t.advance(:seconds => 1) +# => Sun Mar 28 03:00:00 +0200 2010 +</ruby> + +* If +since+ or +ago+ jump to a time that can't be expressed with +Time+ a +DateTime+ object is returned instead. + +h4. Time Constructors + +Active Support defines +Time.current+ to be +Time.zone.now+ if there's a user time zone defined, with fallback to +Time.now+: + +<ruby> +Time.zone_default +# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...> +Time.current +# => Fri, 06 Aug 2010 17:11:58 CEST +02:00 +</ruby> + +Analogously to +DateTime+, the predicates +past?+, and +future?+ are relative to +Time.current+. + +Use the +local_time+ class method to create time objects honoring the user time zone: + +<ruby> +Time.zone_default +# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...> +Time.local_time(2010, 8, 15) +# => Sun Aug 15 00:00:00 +0200 2010 +</ruby> + +The +utc_time+ class method returns a time in UTC: + +<ruby> +Time.zone_default +# => #<ActiveSupport::TimeZone:0x7f73654d4f38 @utc_offset=nil, @name="Madrid", ...> +Time.utc_time(2010, 8, 15) +# => Sun Aug 15 00:00:00 UTC 2010 +</ruby> + +Both +local_time+ and +utc_time+ accept up to seven positional arguments: year, month, day, hour, min, sec, usec. Year is mandatory, month and day default to 1, and the rest default to 0. + +If the time to be constructed lies beyond the range supported by +Time+ in the runtime platform, usecs are discarded and a +DateTime+ object is returned instead. h3. Extensions to +Process+ diff --git a/railties/guides/source/api_documentation_guidelines.textile b/railties/guides/source/api_documentation_guidelines.textile index d9a0d39d9d..9f201de49b 100644 --- a/railties/guides/source/api_documentation_guidelines.textile +++ b/railties/guides/source/api_documentation_guidelines.textile @@ -29,7 +29,7 @@ Documentation has to be concise but comprehensive. Explore and document edge cas The proper names of Rails components have a space in between the words, like "Active Support". +ActiveRecord+ is a Ruby module, whereas Active Record is an ORM. Historically there has been lack of consistency regarding this, but we checked with David when docrails started. All Rails documentation consistently refer to Rails components by their proper name, and if in your next blog post or presentation you remember this tidbit and take it into account that'd be fenomenal :). -Spell names correctly: HTML, MySQL, JavaScript, ERb. +Spell names correctly: HTML, MySQL, JavaScript, ERb. Use the article "an" for "SQL", as in "an SQL statement". Also "an SQLite database". h3. Example Code diff --git a/railties/guides/source/form_helpers.textile b/railties/guides/source/form_helpers.textile index 1f1b7d076e..146b75da3f 100644 --- a/railties/guides/source/form_helpers.textile +++ b/railties/guides/source/form_helpers.textile @@ -647,7 +647,7 @@ the +params+ hash will contain {'person' => {'name' => 'Henry'}} </erb> -and +params["name"]+ will retrieve the submitted value in the controller. +and +params[:person][:name]+ will retrieve the submitted value in the controller. Hashes can be nested as many levels as required, for example diff --git a/railties/guides/source/getting_started.textile b/railties/guides/source/getting_started.textile index 12f2bb146b..ffb0310816 100644 --- a/railties/guides/source/getting_started.textile +++ b/railties/guides/source/getting_started.textile @@ -213,9 +213,9 @@ If you open this file in a new Rails application, you'll see a default database * The +test+ environment is used to run automated tests * The +production+ environment is used when you deploy your application for the world to use. -h5. Configuring a SQLite3 Database +h5. Configuring an SQLite3 Database -Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using a SQLite database when creating a new project, but you can always change it later. +Rails comes with built-in support for "SQLite3":http://www.sqlite.org, which is a lightweight serverless database application. While a busy production environment may overload SQLite, it works well for development and testing. Rails defaults to using an SQLite database when creating a new project, but you can always change it later. Here's the section of the default configuration file (<tt>config/database.yml</tt>) with connection information for the development environment: diff --git a/railties/guides/source/routing.textile b/railties/guides/source/routing.textile index 7b665d81e7..625941ba31 100644 --- a/railties/guides/source/routing.textile +++ b/railties/guides/source/routing.textile @@ -762,6 +762,12 @@ formatted_users GET /users.:format {:controller=>"users", :action=>"index"} POST /users.:format {:controller=>"users", :action=>"create"} </pre> +You may restrict the listing to the routes that map to a particular controller setting the +CONTROLLER+ environment variable: + +<shell> +$ CONTROLLER=users rake routes +</shell> + TIP: You'll find that the output from +rake routes+ is much more readable if you widen your terminal window until the output lines don't wrap. h4. Testing Routes |