Skip to content
Browse files

Merge remote branch 'docrails/master'

  • Loading branch information...
2 parents db6190a + 28474a7 commit 8b2e4fddbf7e9d204579cd87ac72f14bc592d5a5 @fxn fxn committed Sep 1, 2010
View
5 actionpack/lib/action_view/helpers/url_helper.rb
@@ -269,8 +269,9 @@ def link_to(*args, &block)
# The +options+ hash accepts the same options as url_for.
#
# There are a few special +html_options+:
- # * <tt>:method</tt> - Specifies the anchor name to be appended to the path.
- # * <tt>:disabled</tt> - Specifies the anchor name to be appended to the path.
+ # * <tt>:method</tt> - Symbol of HTTP verb. Supported verbs are <tt>:post</tt>, <tt>:get</tt>,
+ # <tt>:delete</tt> and <tt>:put</tt>. By default it will be <tt>:post</tt>.
+ # * <tt>:disabled</tt> - If set to true, it will generate a disabled button.
# * <tt>:confirm</tt> - This will use the unobtrusive JavaScript driver to
# prompt with the question specified. If the user accepts, the link is
# processed normally, otherwise no action is taken.
View
90 railties/guides/source/active_record_querying.textile
@@ -234,23 +234,23 @@ 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.
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.
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,21 +344,21 @@ 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
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)+.
View
2 railties/guides/source/layouts_and_rendering.textile
@@ -1087,7 +1087,7 @@ Partials are very useful in rendering collections. When you pass a collection to
When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is +_product+, and within the +_product+ partial, you can refer to +product+ to get the instance that is being rendered.
-In Rails 3.0 there is also a shorthand for this, assuming +@posts+ is a collection of +post+ instances, you can simply do in the +index.html.erb+:
+In Rails 3.0 there is also a shorthand for this, assuming +@products+ is a collection of +product+ instances, you can simply do in the +index.html.erb+:
<erb>
<h1>Products</h1>
View
12 railties/guides/source/performance_testing.textile
@@ -20,7 +20,7 @@ In a freshly generated Rails application, +test/performance/browsing_test.rb+ co
<ruby>
require 'test_helper'
-require 'performance_test_help'
+require 'rails/performance_test_help'
# Profiling results for each test method are written to tmp/performance.
class BrowsingTest < ActionController::PerformanceTest
@@ -34,17 +34,17 @@ This example is a simple performance test case for profiling a GET request to th
h4. Generating Performance Tests
-Rails provides a generator called +performance_test+ for creating new performance tests:
+Rails provides a generator called +test_unit:performance+ for creating new performance tests:
<shell>
-rails generate performance_test homepage
+rails generate test_unit:performance homepage
</shell>
This generates +homepage_test.rb+ in the +test/performance+ directory:
<ruby>
require 'test_helper'
-require 'performance_test_help'
+require 'rails/performance_test_help'
class HomepageTest < ActionController::PerformanceTest
# Replace this with your real tests.
@@ -103,7 +103,7 @@ Here's the performance test for +HomeController#dashboard+ and +PostsController#
<ruby>
require 'test_helper'
-require 'performance_test_help'
+require 'rails/performance_test_help'
class PostPerformanceTest < ActionController::PerformanceTest
def setup
@@ -131,7 +131,7 @@ Performance test for +Post+ model:
<ruby>
require 'test_helper'
-require 'performance_test_help'
+require 'rails/performance_test_help'
class PostModelTest < ActionController::PerformanceTest
def test_creation

0 comments on commit 8b2e4fd

Please sign in to comment.
Something went wrong with that request. Please try again.