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

7 files changed, 451 insertions, 18 deletions

diff --git a/railties/doc/guides/activerecord/association_basics.txt b/railties/doc/guides/activerecord/association_basics.txt
index 704971d0e8..58c4738a49 100644
--- a/railties/doc/guides/activerecord/association_basics.txt
+++ b/railties/doc/guides/activerecord/association_basics.txt
@@ -104,10 +104,11 @@ end
 === The +has_many+ Association
 
 A +has_many+ association indicates a one-to-many connection with another model. You'll often find this association on the "other side" of a +belongs_to+ association. This association indicates that each instance of the model has zero or more instances of another model. For example, in an application containing customers and orders, the customer model could be declared like this:
+
 [source, ruby]
 -------------------------------------------------------
 class Customer < ActiveRecord::Base
-  has_many :customers
+  has_many :orders
 end
 -------------------------------------------------------
 
diff --git a/railties/doc/guides/activerecord/finders.txt b/railties/doc/guides/activerecord/finders.txt
new file mode 100644
index 0000000000..9f3abb210a
--- /dev/null
+++ b/railties/doc/guides/activerecord/finders.txt
@@ -0,0 +1,54 @@
+Rails Finders
+=======================
+First Draft
+Ryan Bigg <radarlistener@gmail.com>
+
+== What is this guide about? ==
+This guide is all about the `find` method defined in ActiveRecord::Base, and associated goodness such as named scopes.
+
+== In the beginning... ==
+
+In the beginning there was SQL. SQL looked like this:
+
+[source,SQL]
+SELECT * FROM forums
+SELECT * FROM forums WHERE id = '1'
+SELECT * FROM forums LIMIT 0,1
+SELECT * FROM forums ORDER BY id DESC LIMIT 0,1
+
+In Rails you don't have to type SQL, unlike other languages, because ActiveRecord is there to help you find your records. When you define a model like so,
+
+[source,Ruby on Rails]
+class Forum < ActiveRecord::Base
+
+end
+[/code]
+
+== First, Last and All == 
+
+you're telling Ruby to create a new class called `Forum` and that should inherit from ActiveRecord::Base. ActiveRecord::Base has methods defined on it to make interacting with your database and the tables within it much, much easier. For example if you wanted to find the first forum you would simply type `Forum.find(:first)` and that would find the first forum created in your database, the SQL equivalent of typing `SELECT * FROM forums LIMIT 0,1`. Alternatively, you could use the pre-defined named scope first, calling `Forum.first` instead. `first` has two similiar methods, `all` and `last`, which will find all objects in that model's table, and the last object in that model's table respectively. These can be used exactly like first, `Forum.all` is an alias to `Forum.find(:all)` and `Forum.last` is an alias to `Forum.find(:last)`. 
+
+`Forum.first` and `Forum.last` will both return a single object, where as `Forum.find(:all)` will return an array of Forum objects.
+
+== Conditions == 
+
+If you'd like to add conditions to your find, you could just specify them in there, just like `Forum.find(:first, :conditions => "viewable_by = '2'")`. Now what if that number could vary, say as a parameter from somewhere, or perhaps from the user's level status somewhere? The find then becomes something like `Forum.find(:first, :conditions => ["viewable_by = ?", params[:level]])`. ActiveRecord will go through the first element in the conditions option and any additional elements will replace the question marks (?) in the first element. If you want to specify two conditions, you can do it like `Forum.find(:first, :conditions => ["viewable_by = ? AND locked = ?", params[:level], params[:locked]])`.
+
+
+== Ordering == 
+
+If you're getting a set of records and want to force an order, you can use `Forum.find(:all, :order => "created_at")` which by default will sort the records by ascending order. If you'd like to order it in descending order, just tell it to do that using `Forum.find(:all, :order => "created_at desc")
+
+== Selecting Certain Fields ==
+
+To select certain fields, you can use the select option like this: `Forum.find(:first, :select => "viewable_by, locked")`. This select option does not use an array of fields, but rather requires you to type SQL-like code. The above code will execute `SELECT viewable_by, locked FROM forums LIMIT 0,1` on your database. 
+
+== Includes vs Joins == 
+
+== Named Scopes ==
+
+== Finding on Associations ==
+
+== Making It All Work Together ==
+
+You can chain these options together in no particular order as ActiveRecord will write the correct SQL for you. For example you could do this: `Forum.find(:all, :order => "created_at DESC", :select => "viewable_by, created_at", :conditions => ["viewable_by = ?", params[:level]], :limit => 10), which should execute a query like `SELECT viewable_by, created_at FROM forums WHERE ORDER BY created_at DESC LIMIT 0,10` if you really wanted it.
diff --git a/railties/doc/guides/authors.txt b/railties/doc/guides/authors.txt
index 39307a08e9..132121ed3c 100644
--- a/railties/doc/guides/authors.txt
+++ b/railties/doc/guides/authors.txt
@@ -13,4 +13,12 @@ He is based in Cambridge (UK) and when not consuming fine ales he blogs at http:
 ***********************************************************
 Mike Gunderloy is an independent consultant who brings 25 years of experience in a variety of languages to bear on his current
 work with Rails. His near-daily links and other blogging can be found at http://afreshcup.com[A Fresh Cup].
+***********************************************************
+
+.Emilio Tagua
+[[miloops]]
+***********************************************************
+Emilio Tagua -- a.k.a. miloops -- is an Argentinian entrepreneur, developer, open source contributor and Rails evangelist.
+Cofounder of http://www.eventioz.com[Eventioz]. He has been using Rails since 2006 and contributing since early 2008.
+Can be found at gmail, twitter, freenode, everywhere as miloops.
 ***********************************************************
\ No newline at end of file
diff --git a/railties/doc/guides/caching/caching_with_rails.txt b/railties/doc/guides/caching/caching_with_rails.txt
new file mode 100644
index 0000000000..54b7445f88
--- /dev/null
+++ b/railties/doc/guides/caching/caching_with_rails.txt
@@ -0,0 +1,350 @@
+Caching with Rails: An overview
+===============================
+
+Everyone caches. This guide will teach you what you need to know about
+avoiding that expensive round-trip to your database and returning what you
+need to return to those hungry web clients in the shortest time possible.
+
+Specifically, this guide is split into two parts:
+
+- Basic Caching
+- Advanced Caching
+
+- Basic Caching
+  * Page Caching
+  * Action Caching
+  * Fragment Caching
+  * Cache Sweeping
+  * SQL Caching
+  * Cache stores
+
+- Advanced Caching
+  * Fragment Caching with interlock and memcached
+  * Model Caching with cache_fu and memcached
+  * Things you wish you didn't know
+
+== Basic Caching
+
+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.
+
+[source, ruby]
+-----------------------------------------------------
+Base.perform_caching = true
+-----------------------------------------------------
+
+=== 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
+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
+the products
+
+[source, ruby]
+-----------------------------------------------------
+class ProductController < ActionController
+
+  caches_page :list
+
+  def list; 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.
+
+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
+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
+
+In order to expire this page when a new product is added we could extend our
+example controler like this:
+
+[source, ruby]
+-----------------------------------------------------
+class ProductController < ActionController
+
+  caches_page :list
+
+  def list; end
+
+  def create
+    expires_page :action => :list
+  end
+
+end
+-----------------------------------------------------
+
+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.
+
+[More: caching paginated results? more examples? Walk-through of page caching?]
+
+=== Action Caching
+
+The issue 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
+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.
+
+Let's say you only wanted authenticated users to edit or create a Product
+object, but still cache those pages: 
+
+[source, ruby]
+-----------------------------------------------------
+class ProductController < ActionController
+
+  before_filter :authenticate, :only => [ :edit, :create ]
+  caches_page :list
+  caches_action :edit
+
+  def list; end
+
+  def create
+    expires_page :action => :list
+    expire_action :action => :edit
+  end
+
+  def edit; end
+
+end
+-----------------------------------------------------
+
+[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?]
+
+=== Fragment Caching
+
+Life would be perfect if we could get away with caching the entire contents of
+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
+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:
+
+[source, ruby]
+-----------------------------------------------------
+<% Order.find_recent.each do |o| %>
+  <%= o.buyer.name %> bought <% o.product.name %>
+<% end %>
+  
+<% cache do %>
+  All available products: 
+  <% Product.find(:all).each do |p| %>
+    <%= link_to p.name, product_url(p) %>
+  <% end %>
+<% end %>
+-----------------------------------------------------
+
+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:
+
+[source, ruby]
+-----------------------------------------------------
+<% cache(:action => 'recent', :action_suffix => 'all_products') do %>
+  All available products: 
+-----------------------------------------------------
+
+and you can expire it using the expire_fragment method, like so:
+
+[source, ruby]
+-----------------------------------------------------
+expire_fragment(:controller => 'producst', :action => 'recent', :action_suffix => 'all_products)
+-----------------------------------------------------
+
+[More: more examples? description of fragment keys and expiration, etc? pagination?]
+
+=== Sweepers
+
+Cache sweeping is a mechanism which allows you to get around having a ton of
+expire_{page,action,fragment) calls in your code by moving all the work
+required to expire cached content into an asynchronous process that watches
+for changes to your models and implements callbacks to expire cached content.
+
+Continuing with our Product controller example, we could rewrite it with a
+sweeper such as the following:
+
+[source, ruby]
+-----------------------------------------------------
+class StoreSweeper < ActionController::Caching::Sweeper
+  observe Product # This sweeper is going to keep an eye on the Post model
+
+  # If our sweeper detects that a Post was created call this
+  def after_create(product)
+          expire_cache_for(product)
+  end
+  
+  # If our sweeper detects that a Post was updated call this
+  def after_update(product)
+          expire_cache_for(product)
+  end
+  
+  # If our sweeper detects that a Post was deleted call this
+  def after_destroy(product)
+          expire_cache_for(product)
+  end
+          
+  private
+  def expire_cache_for(record)
+    # Expire the list page now that we added a new product
+    expire_page(:controller => '#{record}', :action => 'list')
+    
+    # Expire a fragment 
+    expire_fragment(:controller => '#{record}', :action => 'recent', :action_suffix => 'all_products')
+  end
+end
+-----------------------------------------------------
+
+Then we add it to our controller to tell it to call the sweeper when certain
+actions are called. So, if we wanted to expire the cached content for the list
+and edit actions when the create action was called, we could do the following:
+
+[source, ruby]
+-----------------------------------------------------
+class ProductController < ActionController
+
+  before_filter :authenticate, :only => [ :edit, :create ]
+  caches_page :list
+  caches_action :edit
+  cache_sweeper :store_sweeper, :only => [ :create ]
+
+  def list; end
+
+  def create
+    expires_page :action => :list
+    expire_action :action => :edit
+  end
+
+  def edit; end
+
+end
+-----------------------------------------------------
+
+[More: more examples? better sweepers?]
+
+=== SQL Caching
+
+Query caching is a Rails feature that caches the result set returned by each
+query so that if Rails encounters the same query again for that request, it
+will used the cached result set as opposed to running the query against the
+database again.
+
+For example:
+
+[source, ruby]
+-----------------------------------------------------
+class ProductController < ActionController
+
+  before_filter :authenticate, :only => [ :edit, :create ]
+  caches_page :list
+  caches_action :edit
+  cache_sweeper :store_sweeper, :only => [ :create ]
+
+  def list
+    # Run a find query
+    Product.find(:all)
+
+    ...
+
+    # Run the same query again
+    Product.find(:all)
+  end
+
+  def create
+    expires_page :action => :list
+    expire_action :action => :edit
+  end
+
+  def edit; end
+
+end
+-----------------------------------------------------
+
+In the 'list' action above, the result set returned by the first
+Product.find(:all) will be cached and will be used to avoid querying the
+database again the second time that finder is called.
+
+Query caches are created at the start of an action and destroyed at the end of
+that action and thus persist only for the duration of the action.
+
+=== Cache stores
+
+Rails provides different stores for the cached data for action and fragment
+caches. Page caches are always stored on disk.
+
+The cache stores provided include:
+
+1) Memory store: Cached data is stored in the memory allocated to the Rails
+                 process
+[source, ruby]
+-----------------------------------------------------
+ActionController::Base.cache_store = :memory_store
+-----------------------------------------------------
+
+2) File store: Cached data is stored on the disk, this is the default store
+               and the default path for this store is: /tmp/cache
+
+[source, ruby]
+-----------------------------------------------------
+ActionController::Base.cache_store = :file_store, "/path/to/cache/directory"
+-----------------------------------------------------
+
+3) DRb store: Cached data is stored in a separate DRb process that all servers
+communicate with
+
+[source, ruby]
+-----------------------------------------------------
+ActionController::Base.cache_store = :drb_store, "druby://localhost:9192"
+-----------------------------------------------------
+
+4) MemCached store: Cached data is stored using a high-speed caching server
+called memcached
+
+[source, ruby]
+-----------------------------------------------------
+ActionController::Base.cache_store = :mem_cache_store, "localhost"
+-----------------------------------------------------
+
+5) Custom store: You can define your own cache store (new in Rails 2.1)
+
+[source, ruby]
+-----------------------------------------------------
+ActionController::Base.cache_store = MyOwnStore.new("parameter")
+-----------------------------------------------------
+
+== Advanced Caching
+
+=== memcached and cache_fu
+=== memcached and interlock
diff --git a/railties/doc/guides/debugging/debugging_rails_applications.txt b/railties/doc/guides/debugging/debugging_rails_applications.txt
index eb1135d094..37d4dd19d6 100644
--- a/railties/doc/guides/debugging/debugging_rails_applications.txt
+++ b/railties/doc/guides/debugging/debugging_rails_applications.txt
@@ -1,4 +1,4 @@
-Debugging Rails applications
+Debugging Rails Applications
 ============================
 
 This guide covers how to debug Ruby on Rails applications. By referring to this guide, you will be able to:
@@ -8,7 +8,13 @@ This guide covers how to debug Ruby on Rails applications. By referring to this
 * Learn the different ways of debugging
 * Analyze the stack trace
 
-== View helpers for debugging
+== View Helpers for Debugging
+
+One common task is to inspect the contents of a variable. In Rails, you can do this with three methods:
+
+* `debug`
+* `to_yaml`
+* `inspect`
 
 === debug
 
@@ -40,8 +46,7 @@ attributes_cache: {}
 Title: Rails debugging guide
 ----------------------------------------------------------------------------
 
-
-=== do it yourself
+=== to_yaml
 
 Displaying an instance variable, or any other object or method, in yaml format can be achieved this way:
 
@@ -72,6 +77,8 @@ attributes_cache: {}
 Title: Rails debugging guide
 ----------------------------------------------------------------------------
 
+=== inspect
+
 Another useful method for displaying object values is `inspect`, especially when working with arrays or hashes, it will print the object value as a string, for example:
 
 [source, html]
@@ -91,13 +98,13 @@ Will be rendered as follows:
 Title: Rails debugging guide
 ----------------------------------------------------------------------------
 
-== The logger
+== The Logger
 
 === What is it?
 
-Rails makes use of ruby’s standard `logger`, `Log4r`, or another logger that provides a similar interface can also be substituted if you wish.
+Rails makes use of ruby's standard `logger` to write log information. You can also substitute another logger such as `Log4R` if you wish.
 
-If you want to change the logger you can specify it in your `environment.rb` or any environment file.
+If you want to change the logger you can specify it in your +environment.rb+ or any environment file.
 
 [source, ruby]
 ----------------------------------------------------------------------------
@@ -114,9 +121,9 @@ config.logger = Log4r::Logger.new("Application Log")
 ----------------------------------------------------------------------------
 
 [TIP]
-By default, each log is created under `RAILS_ROOT/log/` and the log file name is `environment_name.log`.
+By default, each log is created under `RAILS_ROOT/log/` and the log file name is +environment_name.log+.
 
-=== Log levels
+=== Log Levels
 
 When something is logged it's printed into the corresponding log if the message log level is equal or higher than the configured log level. If you want to know the current log level just call `ActiveRecord::Base.logger.level` method.
 
@@ -133,7 +140,7 @@ This is useful when you want to log under development or staging, but you don't
 [TIP]
 Rails default log level is +info+ in production mode and +debug+ in development and test mode.
 
-=== Sending messages
+=== Sending Messages
 
 To write in the current log use the `logger.(debug|info|warn|error|fatal)` method from within a controller, model or mailer:
 
@@ -236,7 +243,7 @@ In development mode, you can dynamically `require \'ruby-debug\'` instead of res
 
 In order to use Rails debugging you'll need to be running either *WEBrick* or *Mongrel*. For the moment, no alternative servers are supported.
 
-=== The shell
+=== The Shell
 
 As soon as your application calls the `debugger` method, the debugger will be started in a debugger shell inside the terminal window you've fired up your application server and you will be placed in the ruby-debug's prompt `(rdb:n)`. The _n_ is the thread number.
 
@@ -305,7 +312,7 @@ If we do it again, this time using just `l`, the next ten lines of the file will
 
 And so on until the end of the current file, when the end of file is reached, it will start again from the beginning of the file and continue again up to the end, acting as a circular buffer.
 
-=== The context
+=== The Context
 When we start debugging your application, we will be placed in different contexts as you go through the different parts of the stack.
 
 A context will be created when a stopping point or an event is reached. It has information about the suspended program which enable a debugger to inspect the frame stack, evaluate variables from the perspective of the debugged program, and contains information about the place the debugged program is stopped.
@@ -349,7 +356,7 @@ The debugger can list, stop, resume and switch between running threads, the comm
 
 This command is very helpful, among other occasions, when you are debugging concurrent threads and need to verify that there are no race conditions in your code.
 
-=== Inspecting variables
+=== Inspecting Variables
 
 Any expression can be evaluated in the current context, just type it!
 
@@ -422,7 +429,7 @@ We can use also `display` to start watching variables, this is a good way of tra
 
 The variables inside the displaying list will be printed with their values after we move in the stack. To stop displaying a variable use `undisplay _n_` where _n_ is the variable number (1 in the last example).
 
-=== Step by step
+=== Step by Step
 
 Now you should know where you are in the running trace and be able to print the available variables. But lets continue and move on with the application execution.
 
@@ -601,4 +608,10 @@ set listsize 25
 * link:http://railscasts.com/episodes/56-the-logger[Ryan Bate's logger screencast]
 * link:http://bashdb.sourceforge.net/ruby-debug.html[Debugging with ruby-debug]
 * link:http://cheat.errtheblog.com/s/rdebug/[ruby-debug cheat sheet]
-* link:http://wiki.rubyonrails.org/rails/pages/HowtoConfigureLogging[Ruby on Rails Wiki: How to Configure Logging]
\ No newline at end of file
+* link:http://wiki.rubyonrails.org/rails/pages/HowtoConfigureLogging[Ruby on Rails Wiki: How to Configure Logging]
+
+== Changelog ==
+
+http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/5[Lighthouse ticket]
+
+* September 16, 2008: initial version by link:../authors.html#miloops[Emilio Tagua]
\ No newline at end of file
diff --git a/railties/doc/guides/index.txt b/railties/doc/guides/index.txt
index 87d6804ead..45002f874a 100644
--- a/railties/doc/guides/index.txt
+++ b/railties/doc/guides/index.txt
@@ -1,6 +1,8 @@
 Ruby on Rails guides
 ====================
 
+WARNING: This page is the result of ongoing http://hackfest.rubyonrails.org/guide[Rails Guides hackfest] and a work in progress.
+
 .link:getting_started_with_rails/getting_started_with_rails.html[Getting Started with Rails]
 ***********************************************************
 TODO: Insert some description here.
@@ -28,7 +30,7 @@ in Rails. It covers everything from ``What is a test?'' to the testing APIs.
 Enjoy.
 ***********************************************************
 
-.link:securing_rails_applications/securing_rails_applications.html[Securing Rails Applications]
+.link:securing_rails_applications/security.html[Securing Rails Applications]
 ***********************************************************
 This manual describes common security problems in web applications and how to
 avoid them with Rails.
@@ -51,3 +53,8 @@ of your code.
 ***********************************************************
 TODO: Insert some description here.
 ***********************************************************
+
+.link:caching/caching_with_rails.html[Rails Caching]
+***********************************************************
+TODO: Insert some description here.
+***********************************************************
\ No newline at end of file
diff --git a/railties/doc/guides/routing/routing_outside_in.txt b/railties/doc/guides/routing/routing_outside_in.txt
index 415ab92f34..2e48ca59b7 100644
--- a/railties/doc/guides/routing/routing_outside_in.txt
+++ b/railties/doc/guides/routing/routing_outside_in.txt
@@ -750,7 +750,7 @@ map.index :controller => "pages", :action => "main"
 map.root :index
 -------------------------------------------------------
 
-Because of the top-down processing of the file, the named route must be specified _before_ the call to +map.route+.
+Because of the top-down processing of the file, the named route must be specified _before_ the call to +map.root+.
 
 === Connecting the Empty String