Skip to content
This repository
Browse code

Enhance documentation coverage for fragment caching. Closes #7315 [bs…

…cofield]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@8307 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
  • Loading branch information...
commit 9ffb6328ea97eb7f5cffb13f902b59122a499575 1 parent ee6b607
authored December 05, 2007
4  actionpack/CHANGELOG
... ...
@@ -1,5 +1,9 @@
1 1
 *SVN*
2 2
 
  3
+* Enhance documentation coverage for fragment caching. Closes #7315 [bscofield]
  4
+
  5
+* Fix typo in number helper docs. Closes #7582 [josh]
  6
+
3 7
 * Add many examples to PrototypeHelper documentation. Closes #7656 [jeremymcanally]
4 8
 
5 9
 * Add many examples to assertion documentation. Closes #7803 [jeremymcanally]
37  actionpack/lib/action_controller/caching.rb
@@ -307,25 +307,28 @@ def extract_extension(file_path)
307 307
     #     <%= render :partial => "topic", :collection => Topic.find(:all) %>
308 308
     #   <% end %>
309 309
     #
310  
-    # This cache will bind to the name of action that called it. So you would be able to invalidate it using
311  
-    # <tt>expire_fragment(:controller => "topics", :action => "list")</tt> -- if that was the controller/action used. This is not too helpful
312  
-    # if you need to cache multiple fragments per action or if the action itself is cached using <tt>caches_action</tt>. So instead we should
313  
-    # qualify the name of the action used with something like:
  310
+    # 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 
  311
+    # be able to invalidate it using <tt>expire_fragment(:controller => "topics", :action => "list")</tt>. 
  312
+    # 
  313
+    # This default behavior is of limited use if you need to cache multiple fragments per action or if the action itself is cached using 
  314
+    # <tt>caches_action</tt>, so we also have the option to qualify the name of the cached fragment with something like:
314 315
     #
315 316
     #   <% cache(:action => "list", :action_suffix => "all_topics") do %>
316 317
     #
317  
-    # That would result in a name such as "/topics/list/all_topics", which wouldn't conflict with any action cache and neither with another
318  
-    # fragment using a different suffix. Note that the URL doesn't have to really exist or be callable. We're just using the url_for system
319  
-    # to generate unique cache names that we can refer to later for expirations. The expiration call for this example would be
320  
-    # <tt>expire_fragment(:controller => "topics", :action => "list", :action_suffix => "all_topics")</tt>.
  318
+    # That would result in a name such as "/topics/list/all_topics", avoiding conflicts with the action cache and with any fragments that use a 
  319
+    # 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 
  320
+    # cache names that we can refer to when we need to expire the cache. 
  321
+    # 
  322
+    # The expiration call for this example is:
  323
+    # 
  324
+    #   expire_fragment(:controller => "topics", :action => "list", :action_suffix => "all_topics")
321 325
     #
322 326
     # == Fragment stores
323 327
     #
324  
-    # In order to use the fragment caching, you need to designate where the caches should be stored. This is done by assigning a fragment store
325  
-    # of which there are four different kinds:
  328
+    # By default, cached fragments are stored in memory. The available store options are:
326 329
     #
327  
-    # * FileStore: Keeps the fragments on disk in the +cache_path+, which works well for all types of environments and shares the fragments for
328  
-    #   all the web server processes running off the same application directory.
  330
+    # * FileStore: Keeps the fragments on disk in the +cache_path+, which works well for all types of environments and allows all 
  331
+    #   processes running from the same application directory to access the cached content.
329 332
     # * MemoryStore: Keeps the fragments in memory, which is fine for WEBrick and for FCGI (if you don't care that each FCGI process holds its
330 333
     #   own fragment store). It's not suitable for CGI as the process is thrown away at the end of each request. It can potentially also take
331 334
     #   up a lot of memory since each process keeps all the caches in memory.
@@ -347,6 +350,7 @@ def self.included(base) #:nodoc:
347 350
           @@fragment_cache_store = MemoryStore.new
348 351
           cattr_reader :fragment_cache_store
349 352
 
  353
+          # Defines the storage option for cached fragments
350 354
           def self.fragment_cache_store=(store_option)
351 355
             store, *parameters = *([ store_option ].flatten)
352 356
             @@fragment_cache_store = if store.is_a?(Symbol)
@@ -360,6 +364,9 @@ def self.fragment_cache_store=(store_option)
360 364
         end
361 365
       end
362 366
 
  367
+      # Given a name (as described in <tt>expire_fragment</tt>), returns a key suitable for use in reading, 
  368
+      # writing, or expiring a cached fragment. If the name is a hash, the generated name is the return
  369
+      # value of url_for on that hash (without the protocol).
363 370
       def fragment_cache_key(name)
364 371
         name.is_a?(Hash) ? url_for(name).split("://").last : name
365 372
       end
@@ -379,6 +386,7 @@ def cache_erb_fragment(block, name = {}, options = nil)
379 386
         end
380 387
       end
381 388
 
  389
+      # Writes <tt>content</tt> to the location signified by <tt>name</tt> (see <tt>expire_fragment</tt> for acceptable formats)
382 390
       def write_fragment(name, content, options = nil)
383 391
         return unless perform_caching
384 392
 
@@ -389,6 +397,7 @@ def write_fragment(name, content, options = nil)
389 397
         content
390 398
       end
391 399
 
  400
+      # Reads a cached fragment from the location signified by <tt>name</tt> (see <tt>expire_fragment</tt> for acceptable formats)
392 401
       def read_fragment(name, options = nil)
393 402
         return unless perform_caching
394 403
 
@@ -405,8 +414,8 @@ def read_fragment(name, options = nil)
405 414
       #     %r{pages/\d*/notes}
406 415
       #   Ensure you do not specify start and finish in the regex (^$) because
407 416
       #   the actual filename matched looks like ./cache/filename/path.cache
408  
-      #   Regexp expiration is not supported on caches which can't iterate over
409  
-      #   all keys, such as memcached.
  417
+      #   Regexp expiration is only supported on caches that can iterate over
  418
+      #   all keys (unlike memcached).
410 419
       def expire_fragment(name, options = nil)
411 420
         return unless perform_caching
412 421
 
2  actionpack/lib/action_view/helpers/number_helper.rb
... ...
@@ -1,6 +1,6 @@
1 1
 module ActionView
2 2
   module Helpers #:nodoc:
3  
-    # Provides methods for converting a numbers into formatted strings.
  3
+    # Provides methods for converting numbers into formatted strings.
4 4
     # Methods are provided for phone numbers, currency, percentage,
5 5
     # precision, positional notation, and file size.
6 6
     module NumberHelper

0 notes on commit 9ffb632

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