Skip to content
This repository
Browse code

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

  • Loading branch information...
commit 3822673151cd0f53e0e4e671988e35603bf2901c 2 parents 0b5222f + d1e95e1
Xavier Noria fxn authored
56 actionpack/lib/action_controller/caching/fragments.rb
... ... @@ -1,40 +1,59 @@
1 1 module ActionController #:nodoc:
2 2 module Caching
3   - # Fragment caching is used for caching various blocks within templates without caching the entire action as a whole. This is useful when
4   - # certain elements of an action change frequently or depend on complicated state while other parts rarely change or can be shared amongst multiple
5   - # parties. The caching is done using the cache helper available in the Action View. A template with caching might look something like:
  3 + # Fragment caching is used for caching various blocks within
  4 + # views without caching the entire action as a whole. This is
  5 + # useful when certain elements of an action change frequently or
  6 + # depend on complicated state while other parts rarely change or
  7 + # can be shared amongst multiple parties. The caching is done using
  8 + # the <tt>cache</tt> helper available in the Action View. A
  9 + # template with fragment caching might look like:
6 10 #
7 11 # <b>Hello <%= @name %></b>
  12 + #
8 13 # <% cache do %>
9 14 # All the topics in the system:
10 15 # <%= render :partial => "topic", :collection => Topic.find(:all) %>
11 16 # <% end %>
12 17 #
13   - # This cache will bind to the name of the action that called it, so if this code was part of the view for the topics/list action, you would
14   - # be able to invalidate it using <tt>expire_fragment(:controller => "topics", :action => "list")</tt>.
  18 + # This cache will bind the name of the action that called it, so if
  19 + # this code was part of the view for the topics/list action, you
  20 + # would be able to invalidate it using:
  21 + #
  22 + # expire_fragment(:controller => "topics", :action => "list")
15 23 #
16   - # This default behavior is of limited use if you need to cache multiple fragments per action or if the action itself is cached using
17   - # <tt>caches_action</tt>, so we also have the option to qualify the name of the cached fragment with something like:
  24 + # This default behavior is limited if you need to cache multiple
  25 + # fragments per action or if the action itself is cached using
  26 + # <tt>caches_action</tt>. To remedy this, there is an option to
  27 + # qualify the name of the cached fragment by using the
  28 + # <tt>:action_suffix</tt> option:
18 29 #
19 30 # <% cache(:action => "list", :action_suffix => "all_topics") do %>
20 31 #
21   - # That would result in a name such as <tt>/topics/list/all_topics</tt>, avoiding conflicts with the action cache and with any fragments that use a
22   - # different suffix. Note that the URL doesn't have to really exist or be callable - the url_for system is just used to generate unique
23   - # cache names that we can refer to when we need to expire the cache.
  32 + # That would result in a name such as
  33 + # <tt>/topics/list/all_topics</tt>, avoiding conflicts with the
  34 + # action cache and with any fragments that use a different suffix.
  35 + # Note that the URL doesn't have to really exist or be callable
  36 + # - the url_for system is just used to generate unique cache names
  37 + # that we can refer to when we need to expire the cache.
24 38 #
25 39 # The expiration call for this example is:
26 40 #
27   - # expire_fragment(:controller => "topics", :action => "list", :action_suffix => "all_topics")
  41 + # expire_fragment(:controller => "topics",
  42 + # :action => "list",
  43 + # :action_suffix => "all_topics")
28 44 module Fragments
29   - # Given a key (as described in <tt>expire_fragment</tt>), returns a key suitable for use in reading,
30   - # writing, or expiring a cached fragment. If the key is a hash, the generated key is the return
31   - # value of url_for on that hash (without the protocol). All keys are prefixed with <tt>views/</tt> and uses
  45 + # Given a key (as described in <tt>expire_fragment</tt>), returns
  46 + # a key suitable for use in reading, writing, or expiring a
  47 + # cached fragment. If the key is a hash, the generated key is the
  48 + # return value of url_for on that hash (without the protocol).
  49 + # All keys are prefixed with <tt>views/</tt> and uses
32 50 # ActiveSupport::Cache.expand_cache_key for the expansion.
33 51 def fragment_cache_key(key)
34 52 ActiveSupport::Cache.expand_cache_key(key.is_a?(Hash) ? url_for(key).split("://").last : key, :views)
35 53 end
36 54
37   - # Writes <tt>content</tt> to the location signified by <tt>key</tt> (see <tt>expire_fragment</tt> for acceptable formats)
  55 + # Writes <tt>content</tt> to the location signified by
  56 + # <tt>key</tt> (see <tt>expire_fragment</tt> for acceptable formats).
38 57 def write_fragment(key, content, options = nil)
39 58 return content unless cache_configured?
40 59
@@ -46,7 +65,8 @@ def write_fragment(key, content, options = nil)
46 65 content
47 66 end
48 67
49   - # Reads a cached fragment from the location signified by <tt>key</tt> (see <tt>expire_fragment</tt> for acceptable formats)
  68 + # Reads a cached fragment from the location signified by <tt>key</tt>
  69 + # (see <tt>expire_fragment</tt> for acceptable formats).
50 70 def read_fragment(key, options = nil)
51 71 return unless cache_configured?
52 72
@@ -57,7 +77,8 @@ def read_fragment(key, options = nil)
57 77 end
58 78 end
59 79
60   - # Check if a cached fragment from the location signified by <tt>key</tt> exists (see <tt>expire_fragment</tt> for acceptable formats)
  80 + # Check if a cached fragment from the location signified by
  81 + # <tt>key</tt> exists (see <tt>expire_fragment</tt> for acceptable formats)
61 82 def fragment_exist?(key, options = nil)
62 83 return unless cache_configured?
63 84 key = fragment_cache_key(key)
@@ -70,6 +91,7 @@ def fragment_exist?(key, options = nil)
70 91 # Removes fragments from the cache.
71 92 #
72 93 # +key+ can take one of three forms:
  94 + #
73 95 # * String - This would normally take the form of a path, like
74 96 # <tt>pages/45/notes</tt>.
75 97 # * Hash - Treated as an implicit call to +url_for+, like
22 actionpack/lib/action_view/helpers/cache_helper.rb
@@ -2,31 +2,29 @@ module ActionView
2 2 # = Action View Cache Helper
3 3 module Helpers
4 4 module CacheHelper
5   - # This helper to exposes a method for caching of view fragments.
6   - # See ActionController::Caching::Fragments for usage instructions.
  5 + # This helper exposes a method for caching fragments of a view
  6 + # rather than an entire action or page. This technique is useful
  7 + # caching pieces like menus, lists of newstopics, static HTML
  8 + # fragments, and so on. This method takes a block that contains
  9 + # the content you wish to cache.
7 10 #
8   - # A method for caching fragments of a view rather than an entire
9   - # action or page. This technique is useful caching pieces like
10   - # menus, lists of news topics, static HTML fragments, and so on.
11   - # This method takes a block that contains the content you wish
12   - # to cache. See ActionController::Caching::Fragments for more
13   - # information.
  11 + # See ActionController::Caching::Fragments for usage instructions.
14 12 #
15 13 # ==== Examples
16   - # If you wanted to cache a navigation menu, you could do the
17   - # following.
  14 + # If you want to cache a navigation menu, you can do following:
18 15 #
19 16 # <% cache do %>
20 17 # <%= render :partial => "menu" %>
21 18 # <% end %>
22 19 #
23   - # You can also cache static content...
  20 + # You can also cache static content:
24 21 #
25 22 # <% cache do %>
26 23 # <p>Hello users! Welcome to our website!</p>
27 24 # <% end %>
28 25 #
29   - # ...and static content mixed with RHTML content.
  26 + # Static content with embedded ruby content can be cached as
  27 + # well:
30 28 #
31 29 # <% cache do %>
32 30 # Topics:
6 railties/guides/source/2_2_release_notes.textile
Source Rendered
@@ -260,15 +260,15 @@ h4. Other Action Controller Changes
260 260 * Benchmarking numbers are now reported in milliseconds rather than tiny fractions of seconds
261 261 * Rails now supports HTTP-only cookies (and uses them for sessions), which help mitigate some cross-site scripting risks in newer browsers.
262 262 * +redirect_to+ now fully supports URI schemes (so, for example, you can redirect to a svn+ssh: URI).
263   -* +render+ now supports a +:js+ option to render plain vanilla javascript with the right mime type.
  263 +* +render+ now supports a +:js+ option to render plain vanilla JavaScript with the right mime type.
264 264 * Request forgery protection has been tightened up to apply to HTML-formatted content requests only.
265 265 * Polymorphic URLs behave more sensibly if a passed parameter is nil. For example, calling +polymorphic_path([@project, @date, @area])+ with a nil date will give you +project_area_path+.
266 266
267 267 h3. Action View
268 268
269 269 * +javascript_include_tag+ and +stylesheet_link_tag+ support a new +:recursive+ option to be used along with +:all+, so that you can load an entire tree of files with a single line of code.
270   -* The included Prototype javascript library has been upgraded to version 1.6.0.3.
271   -* +RJS#page.reload+ to reload the browser's current location via javascript
  270 +* The included Prototype JavaScript library has been upgraded to version 1.6.0.3.
  271 +* +RJS#page.reload+ to reload the browser's current location via JavaScript
272 272 * The +atom_feed+ helper now takes an +:instruct+ option to let you insert XML processing instructions.
273 273
274 274 h3. Action Mailer
2  railties/guides/source/2_3_release_notes.textile
Source Rendered
@@ -278,7 +278,7 @@ Mime::JS =~ "text/javascript" => true
278 278 Mime::JS =~ "application/javascript" => true
279 279 </ruby>
280 280
281   -The other change is that the framework now uses the +Mime::JS+ when checking for javascript in various spots, making it handle those alternatives cleanly.
  281 +The other change is that the framework now uses the +Mime::JS+ when checking for JavaScript in various spots, making it handle those alternatives cleanly.
282 282
283 283 * Lead Contributor: "Seth Fitzsimmons":http://www.workingwithrails.com/person/5510-seth-fitzsimmons
284 284
18 railties/guides/source/3_0_release_notes.textile
Source Rendered
@@ -357,15 +357,15 @@ Validations have been moved from Active Record into Active Model, providing an i
357 357
358 358 * There is now a <tt>validates :attribute, options_hash</tt> shortcut method that allows you to pass options for all the validates class methods, you can pass more than one option to a validate method.
359 359 * The +validates+ method has the following options:
360   - * <tt>:acceptance => Boolean</tt>.
361   - * <tt>:confirmation => Boolean</tt>.
362   - * <tt>:exclusion => { :in => Enumerable }</tt>.
363   - * <tt>:inclusion => { :in => Enumerable }</tt>.
364   - * <tt>:format => { :with => Regexp, :on => :create }</tt>.
365   - * <tt>:length => { :maximum => Fixnum }</tt>.
366   - * <tt>:numericality => Boolean</tt>.
367   - * <tt>:presence => Boolean</tt>.
368   - * <tt>:uniqueness => Boolean</tt>.
  360 +** <tt>:acceptance => Boolean</tt>.
  361 +** <tt>:confirmation => Boolean</tt>.
  362 +** <tt>:exclusion => { :in => Enumerable }</tt>.
  363 +** <tt>:inclusion => { :in => Enumerable }</tt>.
  364 +** <tt>:format => { :with => Regexp, :on => :create }</tt>.
  365 +** <tt>:length => { :maximum => Fixnum }</tt>.
  366 +** <tt>:numericality => Boolean</tt>.
  367 +** <tt>:presence => Boolean</tt>.
  368 +** <tt>:uniqueness => Boolean</tt>.
369 369
370 370 NOTE: All the Rails version 2.3 style validation methods are still supported in Rails 3.0, the new validates method is designed as an additional aid in your model validations, not a replacement for the existing API.
371 371
22 railties/guides/source/action_view_overview.textile
Source Rendered
@@ -231,7 +231,7 @@ input("post", "title") # =>
231 231
232 232 h4. AssetTagHelper
233 233
234   -This module provides methods for generating HTML that links views to assets such as images, javascripts, stylesheets, and feeds.
  234 +This module provides methods for generating HTML that links views to assets such as images, JavaScript files, stylesheets, and feeds.
235 235
236 236 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+:
237 237
@@ -242,7 +242,7 @@ image_tag("rails.png") # => <img src="http://assets.example.com/images/rails.png
242 242
243 243 h5. register_javascript_expansion
244 244
245   -Register one or more javascript files to be included when symbol is passed to javascript_include_tag. This method is typically intended to be called from plugin initialization to register javascript files that the plugin installed in public/javascripts.
  245 +Register one or more JavaScript files to be included when symbol is passed to javascript_include_tag. This method is typically intended to be called from plugin initialization to register JavaScript files that the plugin installed in +public/javascripts+.
246 246
247 247 <ruby>
248 248 ActionView::Helpers::AssetTagHelper.register_javascript_expansion :monkey => ["head", "body", "tail"]
@@ -278,7 +278,7 @@ auto_discovery_link_tag(:rss, "http://www.example.com/feed.rss", {:title => "RSS
278 278
279 279 h5. image_path
280 280
281   -Computes the path to an image asset in the public images directory. Full paths from the document root will be passed through. Used internally by +image_tag+ to build the image path.
  281 +Computes the path to an image asset in the +public/images+ directory. Full paths from the document root will be passed through. Used internally by +image_tag+ to build the image path.
282 282
283 283 <ruby>
284 284 image_path("edit.png") # => /images/edit.png
@@ -286,7 +286,7 @@ image_path("edit.png") # => /images/edit.png
286 286
287 287 h5. image_tag
288 288
289   -Returns an html image tag for the source. The source can be a full path or a file that exists in your public images directory.
  289 +Returns an html image tag for the source. The source can be a full path or a file that exists in your +public/images+ directory.
290 290
291 291 <ruby>
292 292 image_tag("icon.png") # => <img src="/images/icon.png" alt="Icon" />
@@ -294,26 +294,26 @@ image_tag("icon.png") # => <img src="/images/icon.png" alt="Icon" />
294 294
295 295 h5. javascript_include_tag
296 296
297   -Returns an html script tag for each of the sources provided. You can pass in the filename (+.js+ extension is optional) of javascript files that exist in your +public/javascripts+ directory for inclusion into the current page or you can pass the full path relative to your document root.
  297 +Returns an html script tag for each of the sources provided. You can pass in the filename (+.js+ extension is optional) of JavaScript files that exist in your +public/javascripts+ directory for inclusion into the current page or you can pass the full path relative to your document root.
298 298
299 299 <ruby>
300 300 javascript_include_tag "common" # =>
301 301 <script type="text/javascript" src="/javascripts/common.js"></script>
302 302 </ruby>
303 303
304   -To include the Prototype and Scriptaculous javascript libraries in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +public/javascripts+ directory, it will be included as well.
  304 +To include the Prototype and Scriptaculous JavaScript libraries in your application, pass +:defaults+ as the source. When using +:defaults+, if an +application.js+ file exists in your +public/javascripts+ directory, it will be included as well.
305 305
306 306 <ruby>
307 307 javascript_include_tag :defaults
308 308 </ruby>
309 309
310   -You can also include all javascripts in the javascripts directory using +:all+ as the source.
  310 +You can also include all JavaScript files in the +public/javascripts+ directory using +:all+ as the source.
311 311
312 312 <ruby>
313 313 javascript_include_tag :all
314 314 </ruby>
315 315
316   -You can also cache multiple javascripts into one file, which requires less HTTP connections to download and can better be compressed by gzip (leading to faster transfers). Caching will only happen if +ActionController::Base.perform_caching+ is set to true (which is the case by default for the Rails production environment, but not for the development environment).
  316 +You can also cache multiple JavaScript files into one file, which requires less HTTP connections to download and can better be compressed by gzip (leading to faster transfers). Caching will only happen if +ActionController::Base.perform_caching+ is set to true (which is the case by default for the Rails production environment, but not for the development environment).
317 317
318 318 <ruby>
319 319 javascript_include_tag :all, :cache => true # =>
@@ -322,7 +322,7 @@ javascript_include_tag :all, :cache => true # =>
322 322
323 323 h5. javascript_path
324 324
325   -Computes the path to a javascript asset in the +public/javascripts+ directory. If the source filename has no extension, +.js+ will be appended. Full paths from the document root will be passed through. Used internally by +javascript_include_tag+ to build the script path.
  325 +Computes the path to a JavaScript asset in the +public/javascripts+ directory. If the source filename has no extension, +.js+ will be appended. Full paths from the document root will be passed through. Used internally by +javascript_include_tag+ to build the script path.
326 326
327 327 <ruby>
328 328 javascript_path "common" # => /javascripts/common.js
@@ -352,7 +352,7 @@ stylesheet_link_tag :all, :cache => true
352 352
353 353 h5. stylesheet_path
354 354
355   -Computes the path to a stylesheet asset in the public stylesheets directory. If the source filename has no extension, .css will be appended. Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path.
  355 +Computes the path to a stylesheet asset in the +public/stylesheets+ directory. If the source filename has no extension, .css will be appended. Full paths from the document root will be passed through. Used internally by stylesheet_link_tag to build the stylesheet path.
356 356
357 357 <ruby>
358 358 stylesheet_path "application" # => /stylesheets/application.css
@@ -1076,7 +1076,7 @@ h4. JavaScriptHelper
1076 1076
1077 1077 Provides functionality for working with JavaScript in your views.
1078 1078
1079   -Rails includes the Prototype JavaScript framework and the Scriptaculous JavaScript controls and visual effects library. If you wish to use these libraries and their helpers, make sure +&lt;%= javascript_include_tag :defaults, :cache => true %&gt;+ is in the HEAD section of your page. This function will include the necessary JavaScript files Rails generated in the public/javascripts directory.
  1079 +Rails includes the Prototype JavaScript framework and the Scriptaculous JavaScript controls and visual effects library. If you wish to use these libraries and their helpers, make sure +&lt;%= javascript_include_tag :defaults, :cache => true %&gt;+ is in the HEAD section of your page. This function will include the necessary JavaScript files Rails generated in the +public/javascripts+ directory.
1080 1080
1081 1081 h5. button_to_function
1082 1082
107 railties/guides/source/active_record_querying.textile
Source Rendered
@@ -337,7 +337,7 @@ This code will generate SQL like this:
337 337 SELECT * FROM clients WHERE (clients.orders_count IN (1,3,5))
338 338 </sql>
339 339
340   -h4. Ordering
  340 +h3. Ordering
341 341
342 342 To retrieve records from the database in a specific order, you can use the +order+ method.
343 343
@@ -361,7 +361,7 @@ Or ordering by multiple fields:
361 361 Client.order("orders_count ASC, created_at DESC")
362 362 </ruby>
363 363
364   -h4. Selecting Specific Fields
  364 +h3. Selecting Specific Fields
365 365
366 366 By default, <tt>Model.find</tt> selects all the fields from the result set using +select *+.
367 367
@@ -397,7 +397,7 @@ You can also call SQL functions within the select option. For example, if you wo
397 397 Client.select("DISTINCT(name)")
398 398 </ruby>
399 399
400   -h4. Limit and Offset
  400 +h3. Limit and Offset
401 401
402 402 To apply +LIMIT+ to the SQL fired by the +Model.find+, you can specify the +LIMIT+ using +limit+ and +offset+ methods on the relation.
403 403
@@ -425,7 +425,7 @@ will return instead a maximum of 5 clients beginning with the 31st. The SQL look
425 425 SELECT * FROM clients LIMIT 5, 30
426 426 </sql>
427 427
428   -h4. Group
  428 +h3. Group
429 429
430 430 To apply a +GROUP BY+ clause to the SQL fired by the finder, you can specify the +group+ method on the find.
431 431
@@ -443,7 +443,7 @@ The SQL that would be executed would be something like this:
443 443 SELECT * FROM orders GROUP BY date(created_at)
444 444 </sql>
445 445
446   -h4. Having
  446 +h3. Having
447 447
448 448 SQL uses the +HAVING+ clause to specify conditions on the +GROUP BY+ fields. You can add the +HAVING+ clause to the SQL fired by the +Model.find+ by adding the +:having+ option to the find.
449 449
@@ -461,7 +461,7 @@ SELECT * FROM orders GROUP BY date(created_at) HAVING created_at > '2009-01-15'
461 461
462 462 This will return single order objects for each day, but only for the last month.
463 463
464   -h4. Readonly Objects
  464 +h3. Readonly Objects
465 465
466 466 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.
467 467
@@ -471,9 +471,9 @@ client.visits += 1
471 471 client.save
472 472 </ruby>
473 473
474   -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_.
  474 +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 _visits_.
475 475
476   -h4. Locking Records for Update
  476 +h3. Locking Records for Update
477 477
478 478 Locking is helpful for preventing race conditions when updating records in the database and ensuring atomic updates.
479 479
@@ -482,7 +482,7 @@ Active Record provides two locking mechanisms:
482 482 * Optimistic Locking
483 483 * Pessimistic Locking
484 484
485   -h5. Optimistic Locking
  485 +h4. Optimistic Locking
486 486
487 487 Optimistic locking allows multiple users to access the same record for edits, and assumes a minimum of conflicts with the data. It does this by checking whether another process has made changes to a record since it was opened. An +ActiveRecord::StaleObjectError+ exception is thrown if that has occurred and the update is ignored.
488 488
@@ -517,7 +517,7 @@ class Client < ActiveRecord::Base
517 517 end
518 518 </ruby>
519 519
520   -h5. Pessimistic Locking
  520 +h4. Pessimistic Locking
521 521
522 522 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.
523 523
@@ -721,6 +721,92 @@ h4. Specifying Conditions on Eager Loaded Associations
721 721
722 722 Even though Active Record lets you specify conditions on the eager loaded associations just like +joins+, the recommended way is to use "joins":#joining-tables instead.
723 723
  724 +h3. Scopes
  725 +
  726 +Scoping allows you to specify commonly-used ARel queries which can be referenced as method calls on the association objects or models. With these scopes, you can use every method previously covered such as +where+, +joins+ and +includes+. All scope methods will return an +ActiveRecord::Relation+ object which will allow for further methods (such as other scopes) to be called on it.
  727 +
  728 +To define a simple scope, we use the +scope+ method inside the class, passing the ARel query that we'd like run when this scope is called:
  729 +
  730 +<ruby>
  731 +class Post < ActiveRecord::Base
  732 + scope :published, where(:published => true)
  733 +end
  734 +</ruby>
  735 +
  736 +Just like before, these methods are also chainable:
  737 +
  738 +<ruby>
  739 +class Post < ActiveRecord::Base
  740 + scope :published, where(:published => true).joins(:category)
  741 +end
  742 +</ruby>
  743 +
  744 +Scopes are also chainable within scopes:
  745 +
  746 +<ruby>
  747 +class Post < ActiveRecord::Base
  748 + scope :published, where(:published => true)
  749 + scope :published_and_commented, published.and(self.arel_table[:comments_count].gt(0))
  750 +end
  751 +</ruby>
  752 +
  753 +To call this +published+ scope we can call it on either the class:
  754 +
  755 +<ruby>
  756 +Post.published => [published posts]
  757 +</ruby>
  758 +
  759 +Or on an association consisting of +Post+ objects:
  760 +
  761 +<ruby>
  762 +category = Category.first
  763 +category.posts.published => [published posts belonging to this category]
  764 +</ruby>
  765 +
  766 +h4. Working with times
  767 +
  768 +If you're working with dates or times within scopes, due to how they are evaluated, you will need to use a lambda so that the scope is evaluated every time.
  769 +
  770 +<ruby>
  771 +class Post < ActiveRecord::Base
  772 + scope :last_week, lambda { where("created_at < ?", Time.zone.now ) }
  773 +end
  774 +</ruby>
  775 +
  776 +Without the +lambda+, this +Time.zone.now+ will only be called once.
  777 +
  778 +h4. Passing in arguments
  779 +
  780 +When a +lambda+ is used for a +scope+, it can take arguments:
  781 +
  782 +<ruby>
  783 +class Post < ActiveRecord::Base
  784 + scope :1_week_before, lambda { |time| where("created_at < ?", time)
  785 +end
  786 +</ruby>
  787 +
  788 +This may then be called using this:
  789 +
  790 +<ruby>
  791 +Post.1_week_before(Time.zone.now)
  792 +</ruby>
  793 +
  794 +However, this is just duplicating the functionality that would be provided to you by a class method.
  795 +
  796 +<ruby>
  797 +class Post < ActiveRecord::Base
  798 + def self.1_week_before(time)
  799 + where("created_at < ?", time)
  800 + end
  801 +end
  802 +</ruby>
  803 +
  804 +Using a class method is the preferred way to accept arguments for scopes. These methods will still be accessible on the association objects:
  805 +
  806 +<ruby>
  807 +category.posts.1_week_before(time)
  808 +</ruby>
  809 +
724 810 h3. Dynamic Finders
725 811
726 812 For every field (also known as an attribute) you define in your table, Active Record provides a finder method. If you have a field called +first_name+ on your +Client+ model for example, you get +find_by_first_name+ and +find_all_by_first_name+ for free from Active Record. If you have a +locked+ field on the +Client+ model, you also get +find_by_locked+ and +find_all_by_locked+ methods.
@@ -882,6 +968,7 @@ For options, please see the parent section, "Calculations":#calculations.
882 968
883 969 h3. Changelog
884 970
  971 +* December 23 2010: Add documentation for the +scope+ method. "Ryan Bigg":http://ryanbigg.com
885 972 * April 7, 2010: Fixed document to validate XHTML 1.0 Strict. "Jaime Iniesta":http://jaimeiniesta.com
886 973 * February 3, 2010: Update to Rails 3 by "James Miller":credits.html#bensie
887 974 * February 7, 2009: Second version by "Pratik":credits.html#lifo
10 railties/guides/source/active_support_core_extensions.textile
Source Rendered
@@ -1568,7 +1568,7 @@ The method +tableize+ is +underscore+ followed by +pluralize+.
1568 1568 "InvoiceLine".tableize # => "invoice_lines"
1569 1569 </ruby>
1570 1570
1571   -As a rule of thumb, +tableize+ returns the table name that corresponds to a given model for simple cases. The actual implementation in Active Record is not straight +tableize+ indeed, because it also demodulizes de class name and checks a few options that may affect the returned string.
  1571 +As a rule of thumb, +tableize+ returns the table name that corresponds to a given model for simple cases. The actual implementation in Active Record is not straight +tableize+ indeed, because it also demodulizes the class name and checks a few options that may affect the returned string.
1572 1572
1573 1573 NOTE: Defined in +active_support/core_ext/string/inflections.rb+.
1574 1574
@@ -1868,7 +1868,7 @@ The sum of an empty collection is zero by default, but this is customizable:
1868 1868 [].sum(1) # => 1
1869 1869 </ruby>
1870 1870
1871   -If a block is given +sum+ becomes an iterator that yields the elements of the collection and sums the returned values:
  1871 +If a block is given, +sum+ becomes an iterator that yields the elements of the collection and sums the returned values:
1872 1872
1873 1873 <ruby>
1874 1874 (1..5).sum {|n| n * 2 } # => 30
@@ -1896,7 +1896,7 @@ h4. +each_with_object+
1896 1896 The +inject+ method offers iteration with an accumulator:
1897 1897
1898 1898 <ruby>
1899   -[2, 3, 4].inject(1) {|acc, i| product*i } # => 24
  1899 +[2, 3, 4].inject(1) {|product, i| product*i } # => 24
1900 1900 </ruby>
1901 1901
1902 1902 The block is expected to return the value for the accumulator in the next iteration, and this makes building mutable objects a bit cumbersome:
@@ -1942,7 +1942,7 @@ The method +many?+ is shorthand for +collection.size > 1+:
1942 1942 <% end %>
1943 1943 </erb>
1944 1944
1945   -If an optional block is given +many?+ only takes into account those elements that return true:
  1945 +If an optional block is given, +many?+ only takes into account those elements that return true:
1946 1946
1947 1947 <ruby>
1948 1948 @see_more = videos.many? {|video| video.category == params[:category]}
@@ -1952,7 +1952,7 @@ NOTE: Defined in +active_support/core_ext/enumerable.rb+.
1952 1952
1953 1953 h4. +exclude?+
1954 1954
1955   -The predicate +exclude?+ tests whether a given object does *not* belong to the collection. It is the negation of the builtin +include?+:
  1955 +The predicate +exclude?+ tests whether a given object does *not* belong to the collection. It is the negation of the built-in +include?+:
1956 1956
1957 1957 <ruby>
1958 1958 to_visit << node if visited.exclude?(node)
4 railties/guides/source/getting_started.textile
Source Rendered
@@ -184,7 +184,7 @@ In any case, Rails will create a folder in your working directory called <tt>blo
184 184 |doc/|In-depth documentation for your application.|
185 185 |lib/|Extended modules for your application (not covered in this guide).|
186 186 |log/|Application log files.|
187   -|public/|The only folder seen to the world as-is. This is where your images, javascript, stylesheets (CSS), and other static files go.|
  187 +|public/|The only folder seen to the world as-is. This is where your images, JavaScript files, stylesheets (CSS), and other static files go.|
188 188 |script/|Contains the rails script that starts your app and can contain other scripts you use to deploy or run your application.|
189 189 |test/|Unit tests, fixtures, and other test apparatus. These are covered in "Testing Rails Applications":testing.html|
190 190 |tmp/|Temporary files|
@@ -227,7 +227,7 @@ NOTE: In this guide we are using an SQLite3 database for data storage, because i
227 227
228 228 h5. Configuring a MySQL Database
229 229
230   -If you choose to use MySQL instead of the shipped Sqlite3 database, your +config/database.yml+ will look a little different. Here's the development section:
  230 +If you choose to use MySQL instead of the shipped SQLite3 database, your +config/database.yml+ will look a little different. Here's the development section:
231 231
232 232 <yaml>
233 233 development:
120 railties/guides/source/initialization.textile
Source Rendered
@@ -222,9 +222,17 @@ h4. +actionpack/lib/action_dispatch.rb+
222 222
223 223 Action Dispatch is the routing component of the Rails framework. It depends on Active Support, +actionpack/lib/action_pack.rb+ and +Rack+ being available. The first thing required here is +active_support+.
224 224
225   -h4. +active_support/lib/active_support.rb+
  225 +h4. +activesupport/lib/active_support.rb+
226 226
227   -This file begins with requiring +active_support/lib/active_support/dependencies/autoload.rb+ which redefines Ruby's +autoload+ method to have a little more extra behaviour especially in regards to eager autoloading. Eager autoloading is the loading of all required classes and will happen when the +config.cache_classes+ setting is +true+.
  227 +This file begins with requiring +active_support/lib/active_support/dependencies/autoload.rb+ which redefines Ruby's +autoload+ method to have a little more extra behaviour especially in regards to eager autoloading. Eager autoloading is the loading of all required classes and will happen when the +config.cache_classes+ setting is +true+.
  228 +
  229 +In this file there are a lot of lines such as this inside the +ActiveSupport+ module:
  230 +
  231 +<ruby>
  232 + autoload :Inflector
  233 +</ruby>
  234 +
  235 +Due to the overriding of the +autoload+ method, Ruby will know to look for this file at +activesupport/lib/active_support/inflector.rb+ when the +Inflector+ class is first referenced.
228 236
229 237 The +active_support/lib/active_support/version.rb+ that is also required here simply defines an +ActiveSupport::VERSION+ constant which defines a couple of constants inside this module, the main constant of this is +ActiveSupport::VERSION::STRING+ which returns the current version of ActiveSupport.
230 238
@@ -450,7 +458,11 @@ h4. +config/application.rb+
450 458
451 459 This file requires +config/boot.rb+, but only if it hasn't been required before, which would be the case in +rails server+ but *wouldn't* be the case with Passenger.
452 460
453   -Then the fun begins! The next line is:
  461 +Then the fun begins!
  462 +
  463 +h3. Loading Rails
  464 +
  465 +The next line in +config/application.rb+ is:
454 466
455 467 <ruby>
456 468 require 'rails/all'
@@ -599,10 +611,110 @@ This file is the next file required from +rails/configuration.rb+ is the file th
599 611
600 612 The next file required is +active_support/core_ext/hash/deep_dup+ which is covered in "Active Support Core Extensions guide":http://guides.rubyonrails.org/active_support_core_extensions.html#deep_dup
601 613
602   -The file after that is +rails/paths+
  614 +The file that is required next from is +rails/paths+
603 615
604 616 h4. +railties/lib/rails/paths.rb+
605 617
  618 +This file defines the +Rails::Paths+ module which allows paths to be configured for a Rails application or engine. Later on in this guide when we cover Rails configuration during the initialization process we'll see this used to set up some default paths for Rails and some of them will be configured to be eager loaded.
  619 +
  620 +h4. +railties/lib/rails/rack.rb+
  621 +
  622 +The final file to be loaded by +railties/lib/rails/configuration.rb+ is +rails/rack+ which defines some simple autoloads:
  623 +
  624 +<ruby>
  625 + module Rails
  626 + module Rack
  627 + autoload :Debugger, "rails/rack/debugger"
  628 + autoload :Logger, "rails/rack/logger"
  629 + autoload :LogTailer, "rails/rack/log_tailer"
  630 + autoload :Static, "rails/rack/static"
  631 + end
  632 + end
  633 +</ruby>
  634 +
  635 +Once this file is finished loading, then the +Rails::Configuration+ class is initialized. This completes the loading of +railties/lib/rails/configuration.rb+ and now we jump back to the loading of +railties/lib/rails/railtie.rb+, where the next file loaded is +active_support/inflector+.
  636 +
  637 +h4. +activesupport/lib/active_support/inflector.rb+
  638 +
  639 ++active_support/inflector.rb+ requires a series of file which are responsible for setting up the basics for knowing how to pluralize and singularize words. These files are:
  640 +
  641 +<ruby>
  642 + require 'active_support/inflector/inflections'
  643 + require 'active_support/inflector/transliterate'
  644 + require 'active_support/inflector/methods'
  645 +
  646 + require 'active_support/inflections'
  647 + require 'active_support/core_ext/string/inflections'
  648 +</ruby>
  649 +
  650 +h4. +activesupport/lib/active_support/inflector/inflections.rb+
  651 +
  652 +This file references the +ActiveSupport::Inflector+ constant which isn't loaded by this point. But there were autoloads set up in +activesupport/lib/active_support.rb+ which will load the file which loads this constant and so then it will be defined. Then this file defines pluralization and singularization rules for words in Rails. This is how Rails knows how to pluralize "tomato" to "tomatoes".
  653 +
  654 +h4. +activesupport/lib/active_support/inflector/transliterate.rb+
  655 +
  656 +In this file is where the "+transliterate+":http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-transliterate and +parameterize+:http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html#method-i-parameterize methods are defined. The documentation for both of these methods is very much worth reading.
  657 +
  658 +h4. +activesupport/lib/active_support/inflector/methods.rb+
  659 +
  660 +The +methods.rb+ file is responsible for defining methods such as +camelize+, +underscore+ and +dasherize+ as well as a slew of others. The "+ActiveSupport::Inflector+ documentation":http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html covers them all pretty decently.
  661 +
  662 +h4. Back to +railties/lib/rails/railtie.rb+
  663 +
  664 +Once the inflector files have been loaded, the +Rails::Railtie+ class is defined. This class includes a module called +Initializable+, which is actually +Rails::Initializable+ and is automatically loaded at this point.
  665 +
  666 +h4. +railties/lib/rails/initializable.rb+
  667 +
  668 +When the module from this file (+Rails::Initializable+) is included, it extends the class it's included into with the +ClassMethods+ module inside of it. This module defines the +initializer+ method which is used to define initializers throughout all of the railties. This file completes the loading of +railties/lib/rails/railtie.rb+. Now we go back to +rails/engine.rb+.
  669 +
  670 +h4. +railties/lib/rails/engine.rb+
  671 +
  672 +The next file required in +rails/engine.rb+ is +active_support/core_ext/module/delegation+ which is documented in the "Active Support Core Extensions Guide":http://guides.rubyonrails.org/active_support_core_extensions.html#method-delegation.
  673 +
  674 +The next two files after this are Ruby standard library files: +pathname+ and +rbconfig+. The file after these is +rails/engine/railties+.
  675 +
  676 +h4. +railties/lib/rails/engine/railties.rb+
  677 +
  678 +This file defines the +Rails::Engine::Railties+ class which provides the +engines+ and +railties+ methods which are used later on for defining rake tasks and other functionality for engines and railties.
  679 +
  680 +h4. Back to +railties/lib/rails/engine.rb+
  681 +
  682 +Once +rails/engine/railties.rb+ has finished loading the +Rails::Engine+ class gets its basic functionality defined, such as the +inherited+ method which will be called when this class is inherited from.
  683 +
  684 +Once this file has finished loading we jump back to +railties/lib/rails/plugin.rb+
  685 +
  686 +h4. Back to +railties/lib/rails/plugin.rb+
  687 +
  688 +The next file required in this is a core extension from Active Support called +array/conversions+ which is covered in "this section":http://guides.rubyonrails.org/active_support_core_extensions.html#array-conversions of the Active Support Core Extensions Guide.
  689 +
  690 +Once that file has finished loading, the +Rails::Plugin+ class is defined.
  691 +
  692 +h4. Back to +railties/lib/rails/application.rb+
  693 +
  694 +Jumping back to +rails/application.rb+ now. This file defines the +Rails::Application+ class where the application's class inherits from. This class (and its superclasses) define the basic behaviour on the application's constant such as the +config+ method used for configuring the application.
  695 +
  696 +Once this file's done then we go back to the +railties/lib/rails.rb+ file, which next requires +rails/version+.
  697 +
  698 +h4. +railties/lib/rails/version.rb+
  699 +
  700 +Much like +active_support/version+, this file defines the +VERSION+ constant which has a +STRING+ constant on it which returns the current version of Rails.
  701 +
  702 +h4. +activesupport/lib/active_support/railtie.rb+
  703 +
  704 +This file requires +active_support+ and +rails+ which have already been required so these two lines are effectively ignored. The third require in this file is to +active_support/railtie+.
  705 +
  706 +h4. +activesupport/lib/active_support/i18n_railtie.rb+
  707 +
  708 +This file is the first file that sets up configuration with these lines inside the class:
  709 +
  710 +<ruby>
  711 + class Railtie < Rails::Railtie
  712 + config.i18n = ActiveSupport::OrderedOptions.new
  713 + config.i18n.railties_load_path = []
  714 + config.i18n.load_path = []
  715 + config.i18n.fallbacks = ActiveSupport::OrderedOptions.new
  716 +</ruby>
  717 +
606 718
607 719
608 720
2  railties/guides/source/layouts_and_rendering.textile
Source Rendered
@@ -681,7 +681,7 @@ There are three tag options available for +auto_discovery_link_tag+:
681 681 * +:type+ specifies an explicit MIME type. Rails will generate an appropriate MIME type automatically.
682 682 * +:title+ specifies the title of the link
683 683
684   -h5. Linking to Javascript Files with +javascript_include_tag+
  684 +h5. Linking to JavaScript Files with +javascript_include_tag+
685 685
686 686 The +javascript_include_tag+ helper returns an HTML +script+ tag for each source provided. Rails looks in +public/javascripts+ for these files by default, but you can specify a full path relative to the document root, or a URL, if you prefer. For example, to include +public/javascripts/main.js+:
687 687

0 comments on commit 3822673

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