Updated with Conditional GET section lifted from Ryan's posts on the topic

1 files changed, 58 insertions, 0 deletions

diff --git a/railties/doc/guides/source/caching_with_rails.txt b/railties/doc/guides/source/caching_with_rails.txt
index e29156d4e7..7cef6bf060 100644
--- a/railties/doc/guides/source/caching_with_rails.txt
+++ b/railties/doc/guides/source/caching_with_rails.txt
@@ -358,6 +358,64 @@ ActionController::Base.cache_store = MyOwnStore.new("parameter")
 ActionController::Base.cache_store in your Rails::Initializer.run block in
 environment.rb+
 
+== Conditional GET support
+
+Conditional GETs are a facility of the HTTP spec that provide a way for web
+servers to tell browsers that the response to a GET request hasn’t changed
+since the last request and can be safely pulled from the browser cache.
+
+They work by using the HTTP_IF_NONE_MATCH and HTTP_IF_MODIFIED_SINCE headers to
+pass back and forth both a unique content identifier and the timestamp of when
+the content was last changed. If the browser makes a request where the content
+identifier (etag) or last modified since timestamp matches the server’s version
+then the server only needs to send back an empty response with a not modified
+status.
+
+It is the server’s (i.e. our) responsibility to look for a last modified
+timestamp and the if-none-match header and determine whether or not to send
+back the full response. With conditional-get support in rails this is a pretty
+easy task:
+
+[source, ruby]
+-----------------------------------------------------
+class ProductsController < ApplicationController
+
+  def show
+    @product = Product.find(params[:id])
+
+    # If the request is stale according to the given timestamp and etag value
+    # (i.e. it needs to be processed again) then execute this block
+    if stale?(:last_modified => @product.updated_at.utc, :etag => @product)
+      respond_to do |wants|
+        # ... normal response processing
+      end
+    end
+
+    # If the request is fresh (i.e. it's not modified) then you don't need to do
+    # anything. The default render checks for this using the parameters
+    # used in the previous call to stale? and will automatically send a
+    # :not_modified.  So that's it, you're done.
+end
+-----------------------------------------------------
+
+If you don’t have any special response processing and are using the default
+rendering mechanism (i.e. you’re not using respond_to or calling render
+yourself) then you’ve got an easy helper in fresh_when:
+
+[source, ruby]
+-----------------------------------------------------
+class ProductsController < ApplicationController
+
+  # This will automatically send back a :not_modified if the request is fresh,
+  # and will render the default template (product.*) if it's stale.
+
+  def show
+    @product = Product.find(params[:id])
+    fresh_when :last_modified => @product.published_at.utc, :etag => @article
+  end
+end
+-----------------------------------------------------
+
 == Advanced Caching
 
 Along with the built-in mechanisms outlined above, a number of excellent