From 9655d6205f8a1cfe99114ad26b490f3e59028da6 Mon Sep 17 00:00:00 2001 From: Mike Gunderloy Date: Wed, 12 Nov 2008 08:29:18 -0600 Subject: Regenerate Guides HTML --- railties/doc/guides/html/2_2_release_notes.html | 24 +++++++- .../doc/guides/html/actioncontroller_basics.html | 8 +-- railties/doc/guides/html/caching_with_rails.html | 72 ++++++++++++---------- railties/doc/guides/html/routing_outside_in.html | 38 ++++++++++++ 4 files changed, 102 insertions(+), 40 deletions(-) (limited to 'railties/doc') diff --git a/railties/doc/guides/html/2_2_release_notes.html b/railties/doc/guides/html/2_2_release_notes.html index 59e862a3cb..e79f7ec511 100644 --- a/railties/doc/guides/html/2_2_release_notes.html +++ b/railties/doc/guides/html/2_2_release_notes.html @@ -243,6 +243,8 @@ ul#navMain {
  • Method Arrays for Member or Collection Routes
  • +
  • Resources With Specific Actions
  • +
  • Other Action Controller Changes
  • @@ -698,7 +700,7 @@ Counter cache columns (for associations declared with :counter_cache ⇒

    6. Action Controller

    -

    On the controller side, there are a couple of changes that will help tidy up your routes.

    +

    On the controller side, there are several changes that will help tidy up your routes. There are also some internal changes in the routing engine to lower memory usage on complex applications.

    6.1. Shallow Route Nesting

    Shallow route nesting provides a solution to the well-known difficulty of using deeply-nested resources. With shallow nesting, you need only supply enough information to uniquely identify the resource that you want to work with.

    @@ -761,8 +763,24 @@ Lead Contributor: Brennan Dunn

    -

    Action Controller now offers good support for HTTP conditional GET requests, as well as some other additions.

    -

    6.3. Other Action Controller Changes

    +

    6.3. Resources With Specific Actions

    +

    By default, when you use map.resources to create a route, Rails generates routes for seven default actions (index, show, create, new, edit, update, and destroy). But each of these routes takes up memory in your application, and causes Rails to generate additional routing logic. Now you can use the :only and :except options to fine-tune the routes that Rails will generate for resources. You can supply a single action, an array of actions, or the special :all or :none options. These options are inherited by nested resources.

    +
    +
    +
    map.resources :photos, :only => [:index, :show]
    +map.resources :products, :except => :destroy
    +
    +
    +

    6.4. Other Action Controller Changes

    • diff --git a/railties/doc/guides/html/actioncontroller_basics.html b/railties/doc/guides/html/actioncontroller_basics.html index 19d7e9e502..66563bf1a3 100644 --- a/railties/doc/guides/html/actioncontroller_basics.html +++ b/railties/doc/guides/html/actioncontroller_basics.html @@ -925,7 +925,7 @@ http://www.gnu.org/software/src-highlite -->

      In every controller there are two accessor methods pointing to the request and the response objects associated with the request cycle that is currently in execution. The request method contains an instance of AbstractRequest and the response method returns a response object representing what is going to be sent back to the client.

      9.1. The request Object

      -

      The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the API documentation. Among the properties that you can access on this object:

      +

      The request object contains a lot of useful information about the request coming in from the client. To get a full list of the available methods, refer to the API documentation. Among the properties that you can access on this object are:

      • @@ -1039,7 +1039,7 @@ http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite -->

        class AdminController < ApplicationController
         
        -  USERNAME, PASSWORD = "humbaba", "f59a4805511bf4bb61978445a5380c6c"
        +  USERNAME, PASSWORD = "humbaba", "5baa61e4c9b93f3f0682250b6cf8331b7ee68fd8"
         
           before_filter :authenticate
         
        @@ -1047,7 +1047,7 @@ private
         
           def authenticate
             authenticate_or_request_with_http_basic do |username, password|
        -      username == USERNAME && Digest::MD5.hexdigest(password) == PASSWORD
        +      username == USERNAME && Digest::SHA1.hexdigest(password) == PASSWORD
             end
           end
         
        @@ -1104,7 +1104,7 @@ http://www.gnu.org/software/src-highlite -->
         
         end
         
      -

      This will read and stream the file 4Kb at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the stream option or adjust the block size with the buffer_size option.

      +

      This will read and stream the file 4Kb at the time, avoiding loading the entire file into memory at once. You can turn off streaming with the :stream option or adjust the block size with the :buffer_size option.

      diff --git a/railties/doc/guides/html/caching_with_rails.html b/railties/doc/guides/html/caching_with_rails.html index df30c46c35..7aa5999e1a 100644 --- a/railties/doc/guides/html/caching_with_rails.html +++ b/railties/doc/guides/html/caching_with_rails.html @@ -235,48 +235,54 @@ need to return to those hungry web clients in the shortest time possible.

      This is an introduction to the three types of caching techniques that Rails provides by default without the use of any third party plugins.

      -

      To get started make sure Base.perform_caching is set to true for your -environment.

      +

      To get started make sure config.action_controller.perform_caching is set +to true for your environment. This flag is normally set in the +corresponding config/environments/*.rb and caching is disabled by default +there for development and test, and enabled for production.

      -
      Base.perform_caching = true
      +
      config.action_controller.perform_caching = true
       

      1.1. Page Caching

      Page caching is a Rails mechanism which allows the request for a generated page to be fulfilled by the webserver, without ever having to go through the -Rails stack at all. Obviously, this is super fast. Unfortunately, it can't be +Rails stack at all. Obviously, this is super-fast. Unfortunately, it can't be applied to every situation (such as pages that need authentication) and since the webserver is literally just serving a file from the filesystem, cache expiration is an issue that needs to be dealt with.

      So, how do you enable this super-fast cache behavior? Simple, let's say you -have a controller called ProductController and a list action that lists all +have a controller called ProductsController and a list action that lists all the products

      -
      class ProductController < ActionController
      +
      class ProductsController < ActionController
       
      -  cache_page :list
      +  caches_page :index
       
      -  def list; end
      +  def index; end
       
       end
       
      -

      The first time anyone requestsion products/list, Rails will generate a file -called list.html and the webserver will then look for that file before it -passes the next request for products/list to your Rails application.

      +

      The first time anyone requests products/index, Rails will generate a file +called index.html and the webserver will then look for that file before it +passes the next request for products/index to your Rails application.

      By default, the page cache directory is set to Rails.public_path (which is -usually set to RAILS_ROOT + "/public") and this can be configured by changing -the configuration setting Base.cache_public_directory

      -

      The page caching mechanism will automatically add a .html exxtension to +usually set to RAILS_ROOT + "/public") and this can be configured by +changing the configuration setting ActionController::Base.page_cache_directory. Changing the +default from /public helps avoid naming conflicts, since you may want to +put other static html in /public, but changing this will require web +server reconfiguration to let the web server know where to serve the +cached files from.

      +

      The Page Caching mechanism will automatically add a .html exxtension to requests for pages that do not have an extension to make it easy for the webserver to find those pages and this can be configured by changing the -configuration setting Base.page_cache_extension

      +configuration setting ActionController::Base.page_cache_extension.

      In order to expire this page when a new product is added we could extend our example controler like this:

      @@ -284,9 +290,9 @@ example controler like this:

      by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -
      class ProductController < ActionController
      +
      class ProductsController < ActionController
       
      -  cache_page :list
      +  caches_page :list
       
         def list; end
       
      @@ -299,11 +305,11 @@ http://www.gnu.org/software/src-highlite -->
       

      If you want a more complicated expiration scheme, you can use cache sweepers to expire cached objects when things change. This is covered in the section on Sweepers.

      1.2. Action Caching

      -

      One of the issues with page caching is that you cannot use it for pages that +

      One of the issues with Page Caching is that you cannot use it for pages that require to restrict access somehow. This is where Action Caching comes in. Action Caching works like Page Caching except for the fact that the incoming web request does go from the webserver to the Rails stack and Action Pack so -that before_filters can be run on it before the cache is served, so that +that before filters can be run on it before the cache is served, so that authentication and other restrictions can be used while still serving the result of the output from a cached copy.

      Clearing the cache works in the exact same way as with Page Caching.

      @@ -314,10 +320,10 @@ object, but still cache those pages:

      by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -
      class ProductController < ActionController
      +
      class ProductsController < ActionController
       
         before_filter :authenticate, :only => [ :edit, :create ]
      -  cache_page :list
      +  caches_page :list
         caches_action :edit
       
         def list; end
      @@ -336,7 +342,7 @@ action should be cached. Also, you can use :layout ⇒ false to cache withou
       layout so that dynamic information in the layout such as logged in user info
       or the number of items in the cart can be left uncached. This feature is
       available as of Rails 2.2.

      -

      [More: more examples? Walk-through of action caching from request to response? +

      [More: more examples? Walk-through of Action Caching from request to response? Description of Rake tasks to clear cached files? Show example of subdomain caching? Talk about :cache_path, :if and assing blocks/Procs to expire_action?]

      @@ -346,13 +352,13 @@ a page or action and serving it out to the world. Unfortunately, dynamic web applications usually build pages with a variety of components not all of which have the same caching characteristics. In order to address such a dynamically created page where different parts of the page need to be cached and expired -differently Rails provides a mechanism called Fragment caching.

      -

      Fragment caching allows a fragment of view logic to be wrapped in a cache +differently Rails provides a mechanism called Fragment Caching.

      +

      Fragment Caching allows a fragment of view logic to be wrapped in a cache block and served out of the cache store when the next request comes in.

      -

      As an example, if you wanted to show all the orders placed on your website in -real time and didn't want to cache that part of the page, but did want to -cache the part of the page which lists all products available, you could use -this piece of code:

      +

      As an example, if you wanted to show all the orders placed on your website +in real time and didn't want to cache that part of the page, but did want +to cache the part of the page which lists all products available, you +could use this piece of code:

      The cache block in our example will bind to the action that called it and is written out to the same place as the Action Cache, which means that if you -want to cache multiple fragments per action, you should provide an action_path to the cache call:

      +want to cache multiple fragments per action, you should provide an action_suffix to the cache call:

      -
      class ProductController < ActionController
      +
      class ProductsController < ActionController
       
         before_filter :authenticate, :only => [ :edit, :create ]
      -  cache_page :list
      +  caches_page :list
         caches_action :edit
         cache_sweeper :store_sweeper, :only => [ :create ]
       
      @@ -468,10 +474,10 @@ database again.

      by Lorenzo Bettini http://www.lorenzobettini.it http://www.gnu.org/software/src-highlite --> -
      class ProductController < ActionController
      +
      class ProductsController < ActionController
       
         before_filter :authenticate, :only => [ :edit, :create ]
      -  cache_page :list
      +  caches_page :list
         caches_action :edit
         cache_sweeper :store_sweeper, :only => [ :create ]
       
      diff --git a/railties/doc/guides/html/routing_outside_in.html b/railties/doc/guides/html/routing_outside_in.html
      index bf9992ff4e..8add4e7789 100644
      --- a/railties/doc/guides/html/routing_outside_in.html
      +++ b/railties/doc/guides/html/routing_outside_in.html
      @@ -925,6 +925,16 @@ cellspacing="0" cellpadding="4">
       :name_prefix
       

      +
    • +

      +:only +

      +
    • +
    • +

      +:except +

      +
    • You can also add additional routes via the :member and :collection options, which are discussed later in this guide.

      3.6.1. Using :controller

      @@ -1419,6 +1429,34 @@ map.resources :
      You can also use :name_prefix with non-RESTful routes.
      +

      3.7.8. Using :only and :except

      +

      By default, Rails creates routes for all seven of the default actions (index, show, new, create, edit, update, and destroy) for every RESTful route in your application. You can use the :only and :except options to fine-tune this behavior. The :only option specifies that only certain routes should be generated:

      +
      +
      +
      map.resources :photos, :only => [:index, :show]
      +
      +

      With this declaration, a GET request to /photos would succeed, but a POST request to /photos (which would ordinarily be routed to the create action) will fail.

      +

      The :except option specifies a route or list of routes that should not be generated:

      +
      +
      +
      map.resources :photos, :except => :destroy
      +
      +

      In this case, all of the normal routes except the route for destroy (a DELETE request to /photos/id) will be generated.

      +

      In addition to an action or a list of actions, you can also supply the special symbols :all or :none to the :only and :accept options.

      +
      + + + +
      +Tip +If your application has many RESTful routes, using :only and :accept to generate only the routes that you actually need can cut down on memory use and speed up the routing process.
      +

      3.8. Nested Resources

      It's common to have resources that are logically children of other resources. For example, suppose your application includes these models:

      -- cgit v1.2.3