railties 3.0.1 → 3.0.2

data/guides/assets/stylesheets/syntaxhighlighter/shThemeRailsGuides.css

@@ -0,0 +1,116 @@
+/**
+ * Theme by fxn, took shThemeEclipse.css as starting point.
+ */
+.syntaxhighlighter {
+  background-color: #eee !important;
+  font-family: "Anonymous Pro", "Inconsolata", "Menlo", "Consolas", "Bitstream Vera Sans Mono", "Courier New", monospace !important;
+  overflow-y: hidden !important;
+  overflow-x: auto !important;
+}
+.syntaxhighlighter .line.alt1 {
+  background-color: #eee !important;
+}
+.syntaxhighlighter .line.alt2 {
+  background-color: #eee !important;
+}
+.syntaxhighlighter .line.highlighted.alt1, .syntaxhighlighter .line.highlighted.alt2 {
+  background-color: #c3defe !important;
+}
+.syntaxhighlighter .line.highlighted.number {
+  color: #eee !important;
+}
+.syntaxhighlighter table caption {
+  color: #222 !important;
+}
+.syntaxhighlighter .gutter {
+  color: #787878 !important;
+}
+.syntaxhighlighter .gutter .line {
+  border-right: 3px solid #d4d0c8 !important;
+}
+.syntaxhighlighter .gutter .line.highlighted {
+  background-color: #d4d0c8 !important;
+  color: #eee !important;
+}
+.syntaxhighlighter.printing .line .content {
+  border: none !important;
+}
+.syntaxhighlighter.collapsed {
+  overflow: visible !important;
+}
+.syntaxhighlighter.collapsed .toolbar {
+  color: #3f5fbf !important;
+  background: #eee !important;
+  border: 1px solid #d4d0c8 !important;
+}
+.syntaxhighlighter.collapsed .toolbar a {
+  color: #3f5fbf !important;
+}
+.syntaxhighlighter.collapsed .toolbar a:hover {
+  color: #aa7700 !important;
+}
+.syntaxhighlighter .toolbar {
+  color: #a0a0a0 !important;
+  background: #d4d0c8 !important;
+  border: none !important;
+}
+.syntaxhighlighter .toolbar a {
+  color: #a0a0a0 !important;
+}
+.syntaxhighlighter .toolbar a:hover {
+  color: red !important;
+}
+.syntaxhighlighter .plain, .syntaxhighlighter .plain a {
+  color: #222 !important;
+}
+.syntaxhighlighter .comments, .syntaxhighlighter .comments a {
+  color: #708090 !important;
+}
+.syntaxhighlighter .string, .syntaxhighlighter .string a {
+  font-style: italic !important;
+  color: #6588A8 !important;
+}
+.syntaxhighlighter .keyword {
+  color: #64434d !important;
+}
+.syntaxhighlighter .preprocessor {
+  color: #646464 !important;
+}
+.syntaxhighlighter .variable {
+  color: #222 !important;
+}
+.syntaxhighlighter .value {
+  color: #009900 !important;
+}
+.syntaxhighlighter .functions {
+  color: #ff1493 !important;
+}
+.syntaxhighlighter .constants {
+  color: #0066cc !important;
+}
+.syntaxhighlighter .script {
+  color: #222 !important;
+  background-color: none !important;
+}
+.syntaxhighlighter .color1, .syntaxhighlighter .color1 a {
+  color: gray !important;
+}
+.syntaxhighlighter .color2, .syntaxhighlighter .color2 a {
+  color: #222 !important;
+  font-weight: bold !important;
+}
+.syntaxhighlighter .color3, .syntaxhighlighter .color3 a {
+  color: red !important;
+}
+
+.syntaxhighlighter .xml .keyword {
+  color: #64434d !important;
+  font-weight: normal !important;
+}
+.syntaxhighlighter .xml .color1, .syntaxhighlighter .xml .color1 a {
+  color: #7f007f !important;
+}
+.syntaxhighlighter .xml .string {
+  font-style: italic !important;
+  color: #6588A8 !important;
+}

data/guides/rails_guides/generator.rb

@@ -207,10 +207,28 @@ module RailsGuides
     # with code blocks by hand.
     def with_workaround_for_notextile(body)
       code_blocks = []
+
       body.gsub!(%r{<(yaml|shell|ruby|erb|html|sql|plain)>(.*?)</\1>}m) do |m|
-        es = ERB::Util.h($2)
-        css_class = ['erb', 'shell'].include?($1) ? 'html' : $1
-        code_blocks << %{<div class="code_container"><code class="#{css_class}">#{es}</code></div>}
+        brush = case $1
+          when 'ruby', 'sql', 'plain'
+            $1
+          when 'erb'
+            'ruby; html-script: true'
+          when 'html'
+            'xml' # html is understood, but there are .xml rules in the CSS
+          else
+            'plain'
+        end
+
+        code_blocks.push(<<HTML)
+<notextile>
+<div class="code_container">
+<pre class="brush: #{brush}; gutter: false; toolbar: false">
+#{ERB::Util.h($2).strip}
+</pre>
+</div>
+</notextile>
+HTML
         "\ndirty_workaround_for_notextile_#{code_blocks.size - 1}\n"
       end
 

data/guides/source/3_0_release_notes.textile

@@ -18,13 +18,11 @@ These release notes cover the major upgrades, but don't include every little bug
 
 endprologue.
 
-WARNING: Rails 3.0 is currently in beta. This means that there are probably bugs and that you should "report them":http://rails.lighthouseapp.com/projects/8994-ruby-on-rails/overview if you see them. You also may not want to run the NORAD nuclear launch application off a beta version. But if you're starting development on a new application and you don't mind getting wind in your hair, please do jump on board!
-
-To install the last Rails 3 beta:
+To install Rails 3:
 
 <shell>
 # Use sudo if your setup requires it
-gem install rails --pre
+gem install rails
 </shell>
 
 
@@ -77,10 +75,8 @@ More information - "The Path to Rails 3: Approaching the upgrade":http://omgblog
 
 h3. Creating a Rails 3.0 application
 
-The new installing rails sequence (for the beta) is:
-
 <shell>
-$ gem install rails --prerelease
+# You should have the 'rails' rubygem installed
 $ rails new myapp
 $ cd myapp
 </shell>

data/guides/source/action_controller_overview.textile

@@ -242,7 +242,7 @@ class LoginsController < ApplicationController
   # "Delete" a login, aka "log the user out"
   def destroy
     # Remove the user id from the session
-    session[:current_user_id] = nil
+    @_current_user = session[:current_user_id] = nil
     redirect_to root_url
   end
 end
@@ -264,6 +264,13 @@ class LoginsController < ApplicationController
 end
 </ruby>
 
+Note it is also possible to assign a flash message as part of the redirection.
+
+<ruby>
+redirect_to root_url, :notice => "You have successfully logged out"
+</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:
 
 <ruby>

data/guides/source/action_mailer_basics.textile

@@ -462,7 +462,7 @@ class UserMailerTest < ActionMailer::TestCase
     user = users(:some_user_in_your_fixtures)
 
     # Send the email, then test that it got queued
-    email = UserMailer.deliver_welcome_email(user)
+    email = UserMailer.welcome_email(user).deliver
     assert !ActionMailer::Base.deliveries.empty?
 
     # Test the body of the sent email contains what we expect it to

data/guides/source/action_view_overview.textile

@@ -233,7 +233,7 @@ h4. AssetTagHelper
 
 This module provides methods for generating HTML that links views to assets such as images, javascripts, stylesheets, and feeds.
 
-By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting +ActionController::Base.asset_host+ in your +config/environment.rb+. For example, let's say your asset host is +assets.example.com+:
+By default, Rails links to these assets on the current host in the public folder, but you can direct Rails to link to assets from a dedicated assets server by setting +ActionController::Base.asset_host+ in the application configuration, typically in +config/environments/production.rb+. For example, let's say your asset host is +assets.example.com+:
 
 <ruby>
 ActionController::Base.asset_host = "assets.example.com"

data/guides/source/active_record_querying.textile

@@ -159,14 +159,14 @@ The following may seem very straight forward at first:
 
 <ruby>
 # Very inefficient when users table has thousands of rows.
-User.each do |user|
+User.all.each do |user|
   NewsLetter.weekly_deliver(user)
 end
 </ruby>
 
 But if the total number of rows in the table is very large, the above approach may vary from being under performant to just plain impossible.
 
-This is because +User.each+ makes Active Record fetch _the entire table_, build a model object per row, and keep the entire array in the memory. Sometimes that is just too many objects and demands too much memory.
+This is because +User.all.each+ makes Active Record fetch _the entire table_, build a model object per row, and keep the entire array in the memory. Sometimes that is just too many objects and demands too much memory.
 
 h5. +find_each+
 
@@ -234,7 +234,7 @@ h4. Array Conditions
 Now what if that number could vary, say as an argument from somewhere, or perhaps from the user's level status somewhere? The find then becomes something like:
 
 <ruby>
-Client.where(["orders_count = ?", params[:orders]])
+Client.where("orders_count = ?", params[:orders])
 </ruby>
 
 Active Record will go through the first element in the conditions value and any additional elements will replace the question marks +(?)+ in the first element.
@@ -242,7 +242,7 @@ Active Record will go through the first element in the conditions value and any
 Or if you want to specify two conditions, you can do it like:
 
 <ruby>
-Client.where(["orders_count = ? AND locked = ?", params[:orders], false])
+Client.where("orders_count = ? AND locked = ?", params[:orders], false)
 </ruby>
 
 In this example, the first question mark will be replaced with the value in +params[:orders]+ and the second will be replaced with the SQL representation of +false+, which depends on the adapter.
@@ -250,7 +250,7 @@ In this example, the first question mark will be replaced with the value in +par
 The reason for doing code like:
 
 <ruby>
-Client.where(["orders_count = ?", params[:orders]])
+Client.where("orders_count = ?", params[:orders])
 </ruby>
 
 instead of:
@@ -268,8 +268,8 @@ h5. Placeholder Conditions
 Similar to the +(?)+ replacement style of params, you can also specify keys/values hash in your array conditions:
 
 <ruby>
-Client.where(
-  ["created_at >= :start_date AND created_at <= :end_date", { :start_date => params[:start_date], :end_date => params[:end_date] }])
+Client.where("created_at >= :start_date AND created_at <= :end_date",
+  {:start_date => params[:start_date], :end_date => params[:end_date]})
 </ruby>
 
 This makes for clearer readability if you have a large number of variable conditions.
@@ -279,8 +279,8 @@ h5(#array-range_conditions). Range Conditions
 If you're looking for a range inside of a table (for example, users created in a certain timeframe) you can use the conditions option coupled with the +IN+ SQL statement for this. If you had two dates coming in from a controller you could do something like this to look for a range:
 
 <ruby>
-Client.where(["created_at IN (?)",
-  (params[:start_date].to_date)..(params[:end_date].to_date)])
+Client.where("created_at IN (?)",
+  (params[:start_date].to_date)..(params[:end_date].to_date))
 </ruby>
 
 This would generate the proper query which is great for small ranges but not so good for larger ranges. For example if you pass in a range of date objects spanning a year that's 365 (or possibly 366, depending on the year) strings it will attempt to match your field against.
@@ -301,8 +301,8 @@ h5. Time and Date Conditions
 Things can get *really* messy if you pass in Time objects as it will attempt to compare your field to *every second* in that range:
 
 <ruby>
-Client.where(["created_at IN (?)",
-  (params[:start_date].to_date.to_time)..(params[:end_date].to_date.to_time)])
+Client.where("created_at IN (?)",
+  (params[:start_date].to_date.to_time)..(params[:end_date].to_date.to_time))
 </ruby>
 
 <sql>
@@ -323,14 +323,14 @@ In this example it would be better to use greater-than and less-than operators i
 
 <ruby>
 Client.where(
-  ["created_at > ? AND created_at < ?", params[:start_date], params[:end_date]])
+  "created_at > ? AND created_at < ?", params[:start_date], params[:end_date])
 </ruby>
 
 You can also use the greater-than-or-equal-to and less-than-or-equal-to like this:
 
 <ruby>
 Client.where(
-  ["created_at >= ? AND created_at <= ?", params[:start_date], params[:end_date]])
+  "created_at >= ? AND created_at <= ?", params[:start_date], params[:end_date])
 </ruby>
 
 Just like in Ruby. If you want a shorter syntax be sure to check out the "Hash Conditions":#hash-conditions section later on in the guide.
@@ -344,13 +344,13 @@ NOTE: Only equality, range and subset checking are possible with Hash conditions
 h5. Equality Conditions
 
 <ruby>
-Client.where({ :locked => true })
+Client.where(:locked => true)
 </ruby>
 
 The field name can also be a string:
 
 <ruby>
-Client.where({ 'locked' => true })
+Client.where('locked' => true)
 </ruby>
 
 h5(#hash-range_conditions). Range Conditions
@@ -358,7 +358,7 @@ h5(#hash-range_conditions). Range Conditions
 The good thing about this is that we can pass in a range for our fields without it generating a large query as shown in the preamble of this section.
 
 <ruby>
-Client.where({ :created_at => (Time.now.midnight - 1.day)..Time.now.midnight})
+Client.where(:created_at => (Time.now.midnight - 1.day)..Time.now.midnight)
 </ruby>
 
 This will find all clients created yesterday by using a +BETWEEN+ SQL statement:
@@ -374,7 +374,7 @@ h5. Subset Conditions
 If you want to find records using the +IN+ expression you can pass an array to the conditions hash:
 
 <ruby>
-Client.where({ :orders_count => [1,3,5] })
+Client.where(:orders_count => [1,3,5])
 </ruby>
 
 This code will generate SQL like this:
@@ -496,7 +496,7 @@ SQL uses the +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You
 For example:
 
 <ruby>
-Order.group("date(created_at)".having(["created_at > ?", 1.month.ago])
+Order.group("date(created_at)".having("created_at > ?", 1.month.ago)
 </ruby>
 
 The SQL that would be executed would be something like this:
@@ -509,22 +509,16 @@ This will return single order objects for each day, but only for the last month.
 
 h4. Readonly Objects
 
-To explicitly disallow modification/destruction of the matching records returned in a Relation object, you could chain the +readonly+ method as +true+ to the find call.
-
-Any attempt to alter or destroy the readonly records will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception. To set this option, specify it like this:
+Active Record provides +readonly+ method on a relation to explicitly disallow modification or deletion of any of the returned object. Any attempt to alter or destroy a readonly record will not succeed, raising an +ActiveRecord::ReadOnlyRecord+ exception.
 
 <ruby>
-Client.first.readonly(true)
-</ruby>
-
-For example, calling the following code will raise an +ActiveRecord::ReadOnlyRecord+ exception:
-
-<ruby>
-client = Client.first.readonly(true)
-client.locked = false
+client = Client.readonly.first
+client.visits += 1
 client.save
 </ruby>
 
+As +client+ is explicitly set to be a readonly object, the above code will raise an +ActiveRecord::ReadOnlyRecord+ exception when calling +client.save+ with an updated value of _visists_.
+
 h4. Locking Records for Update
 
 Locking is helpful for preventing race conditions when updating records in the database and ensuring atomic updates.
@@ -571,13 +565,13 @@ end
 
 h5. Pessimistic Locking
 
-Pessimistic locking uses a locking mechanism provided by the underlying database. Passing +:lock => true+ to +Model.find+ obtains an exclusive lock on the selected rows. +Model.find+ using +:lock+ are usually wrapped inside a transaction for preventing deadlock conditions.
+Pessimistic locking uses a locking mechanism provided by the underlying database. Using +lock+ when building a relation obtains an exclusive lock on the selected rows. Relations using +lock+ are usually wrapped inside a transaction for preventing deadlock conditions.
 
 For example:
 
 <ruby>
 Item.transaction do
-  i = Item.first(:lock => true)
+  i = Item.lock.first
   i.name = 'Jones'
   i.save
 end
@@ -592,25 +586,25 @@ Item Update (0.4ms)   UPDATE `items` SET `updated_at` = '2009-02-07 18:05:56', `
 SQL (0.8ms)   COMMIT
 </sql>
 
-You can also pass raw SQL to the +:lock+ option to allow different types of locks. For example, MySQL has an expression called +LOCK IN SHARE MODE+ where you can lock a record but still allow other queries to read it. To specify this expression just pass it in as the lock option:
+You can also pass raw SQL to the +lock+ method for allowing different types of locks. For example, MySQL has an expression called +LOCK IN SHARE MODE+ where you can lock a record but still allow other queries to read it. To specify this expression just pass it in as the lock option:
 
 <ruby>
 Item.transaction do
-  i = Item.find(1, :lock => "LOCK IN SHARE MODE")
+  i = Item.lock("LOCK IN SHARE MODE").find(1)
   i.increment!(:views)
 end
 </ruby>
 
 h3. Joining Tables
 
-<tt>Model.find</tt> provides a +:joins+ option for specifying +JOIN+ clauses on the resulting SQL. There are multiple ways to specify the +:joins+ option:
+Active Record provides a finder method called +joins+ for specifying +JOIN+ clauses on the resulting SQL. There are multiple ways to use the +joins+ method.
 
 h4. Using a String SQL Fragment
 
-You can just supply the raw SQL specifying the +JOIN+ clause to the +:joins+ option. For example:
+You can just supply the raw SQL specifying the +JOIN+ clause to +joins+:
 
 <ruby>
-Client.all(:joins => 'LEFT OUTER JOIN addresses ON addresses.client_id = clients.id')
+Client.joins('LEFT OUTER JOIN addresses ON addresses.client_id = clients.id')
 </ruby>
 
 This will result in the following SQL:
@@ -625,7 +619,7 @@ WARNING: This method only works with +INNER JOIN+,
 
 <br />
 
-Active Record lets you use the names of the "associations":association_basics.html defined on the model as a shortcut for specifying the +:joins+ option.
+Active Record lets you use the names of the "associations":association_basics.html defined on the model as a shortcut for specifying +JOIN+ clause for those associations when using the +joins+ method.
 
 For example, consider the following +Category+, +Post+, +Comments+ and +Guest+ models:
 
@@ -838,13 +832,13 @@ Client.exists?(1,2,3)
 Client.exists?([1,2,3])
 </ruby>
 
-The +exists+ method may also take a +conditions+ option much like find:
+It's even possible to use +exists?+ without any arguments on a model or a relation.
 
 <ruby>
-Client.exists?(:conditions => "first_name = 'Ryan'")
+Client.where(:first_name => 'Ryan').exists?
 </ruby>
 
-It's even possible to use +exists?+ without any arguments:
+The above returns +true+ if there is at least one client with the +first_name+ 'Ryan' and +false+ otherwise.
 
 <ruby>
 Client.exists?
@@ -856,22 +850,24 @@ h3. Calculations
 
 This section uses count as an example method in this preamble, but the options described apply to all sub-sections.
 
-<tt>count</tt> takes conditions much in the same way +exists?+ does:
+All calculation methods work directly on a model:
 
 <ruby>
-Client.count(:conditions => "first_name = 'Ryan'")
+Client.count
+# SELECT count(*) AS count_all FROM clients
 </ruby>
 
-Which will execute:
+Or on a relation :
 
-<sql>
-SELECT count(*) AS count_all FROM clients WHERE (first_name = 'Ryan')
-</sql>
+<ruby>
+Client.where(:first_name => 'Ryan').count
+# SELECT count(*) AS count_all FROM clients WHERE (first_name = 'Ryan')
+</ruby>
 
-You can also use the +includes+ or +joins+ methods for this to do something a little more complex:
+You can also use various finder methods on a relation for performing complex calculations:
 
 <ruby>
-Client.where("clients.first_name = 'Ryan' AND orders.status = 'received'").includes("orders").count
+Client.includes("orders").where(:first_name => 'Ryan', :orders => {:status => 'received'}).count
 </ruby>
 
 Which will execute:
@@ -882,8 +878,6 @@ SELECT count(DISTINCT clients.id) AS count_all FROM clients
   (clients.first_name = 'Ryan' AND orders.status = 'received')
 </sql>
 
-This code specifies +clients.first_name+ just in case one of the join tables has a field also called +first_name+ and it uses +orders.status+ because that's the name of our join table.
-
 h4. Count
 
 If you want to see how many records are in your model's table you could call +Client.count+ and that will return the number. If you want to be more specific and find all the clients with their age present in the database you can use +Client.count(:age)+.