kotovalexarian-likes-github/rails--rails
1
0
Fork 0
mirror of https://github.com/rails/rails.git synced 2022-11-09 12:12:34 -05:00
Code Releases Activity

Rearrange guides

Browse source
This commit is contained in:
Pratik Naik 2008-10-21 15:58:29 +01:00
parent fa09de351c
commit 5265a8cd40
112 changed files with 19085 additions and 286 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitignore vendored
View file

@ -5,7 +5,6 @@ activerecord/doc
actionpack/doc
actionmailer/doc
activesupport/doc
railties/doc
activeresource/pkg
activerecord/pkg
actionpack/pkg

79
railties/Rakefile
View file

@ -272,58 +272,41 @@ Rake::RDocTask.new { |rdoc|
rdoc.rdoc_files.include('lib/commands/**/*.rb')
}
# In this array, one defines the guides for which HTML output should be
# generated. Specify the folder names of the guides. If the .txt filename
# doesn't equal its folder name, then specify a hash: { 'folder_name' => 'basename' }
guides = [
'getting_started_with_rails',
# 'testing_rails_applications',
'creating_plugins',
'actioncontroller',
'migrations',
{ 'securing_rails_applications' => 'security' },
{ 'routing' => 'routing_outside_in' },
{ 'forms' =>'form_helpers' },
{ 'activerecord' => 'association_basics' },
{ 'activerecord' => 'finders' },
{ 'debugging' => 'debugging_rails_applications' },
{ 'caching' => 'caching_with_rails' },
{ 'benchmarking_and_profiling' => 'index' },
{ 'actionview' => 'layouts_and_rendering' }
]
desc "Generate guides for the framework"
task :guides do
require 'mizuho/generator'
guides_html_files = [] # autogenerated from the 'guides' variable.
guides.each do |entry|
if entry.is_a?(Hash)
guide_folder = entry.keys.first
guide_name = entry.values.first
else
guide_folder = entry
guide_name = entry
end
input = "doc/guides/#{guide_folder}/#{guide_name}.txt"
output = "doc/guides/#{guide_folder}/#{guide_name}.html"
guides_html_files << output
task output => Dir["doc/guides/#{guide_folder}/*.txt"] do
ENV['MANUALSONRAILS_INDEX_URL'] = '../index.html'
ENV.delete('MANUALSONRAILS_TOC')
sh "mizuho", input, "--template", "manualsonrails", "--icons-dir", "../icons"
source = "doc/guides/source/"
html = "doc/guides/html/"
ignore = ['icons', 'images']
ignore << 'active_record_basics.txt'
indexless = ['index.txt', 'authors.txt']
Dir.entries(source)[2..-1].each do |entry|
next if ignore.include?(entry)
if File.directory?(File.join(source, entry))
input = File.join(source, entry, 'index.txt')
output = File.join(html, "#{entry}.html")
else
input = File.join(source, entry)
output = File.join(html, entry).sub(/\.txt$/, '')
end
begin
puts "GENERATING => #{output}"
ENV['MANUALSONRAILS_TOC'] = 'no' if indexless.include?(entry)
Mizuho::Generator.new(input, output, 'manualsonrails', nil, File.expand_path(File.join(source, 'icons'))).start
rescue Mizuho::GenerationError
STDERR.puts "*** ERROR"
exit 2
ensure
ENV.delete('MANUALSONRAILS_TOC')
end
end
end
['index', 'authors'].each do |guide|
task "doc/guides/#{guide}.html" => "doc/guides/#{guide}.txt" do
ENV.delete('MANUALSONRAILS_INDEX_URL')
ENV['MANUALSONRAILS_TOC'] = 'no'
sh "mizuho", "doc/guides/#{guide}.txt", "--template", "manualsonrails", "--icons-dir", "icons"
end
end
desc "Generate HTML output for the guides"
task :generate_guides => guides_html_files
task :generate_guides => 'doc/guides/index.html'
task :generate_guides => 'doc/guides/authors.html'
# Generate GEM ----------------------------------------------------------------------------
task :copy_gem_environment do

91
railties/doc/guides/actionview/helpers.markdown
View file

@ -1,91 +0,0 @@
Helpers
====================
Helper Basics
------------------------
Helpers allow you to encapsulate rendering tasks as reusable functions. Helpers are modules, not classes, so their methods execute in the context in which they are called. They get included in a controller (typically the ApplicationController) using the helper function, like so
Class ApplicationController < ActionController::Base
…
helper :menu
def …
end
end
In this way, methods in the menu helper are made available to any view or partial in your application. These methods can accept parameters, for example controller instance variables (eg; records or record collections gathered by you current controller), items from the view or partial’s locals[] hash or items from the params[] hash. You may wish to pass your controller instance variables and items from the params[] hash to the locals hash before rendering (See the section on partials). Helper methods can also accept an executable block of code.
It is important to remember, though, that helpers are for rendering, and that they become available once a controller method has returned, while Rails is engaged in rendering the contents generated by a controller method. This means that helper methods are not available from within the methods of your controllers.
Helpers can accomplish a variety of tasks, from formatting a complex tag for embedding content for a browser plugin (eg; Flash), to assembling a menu of options appropriate for the current context of your application, to generating sections of forms that get assembled on-the-fly.
Helpers are organized around rendering tasks, so it is not necessary (nor necessarily desirable) to organize them around your application’s controllers or models. In fact, one of the benefits of helpers is that they are not connected via a rendering pipeline to specific controllers, like views and partials are. They can and should handle more generalized tasks.
Here is a very simple, pseudo-example:
module MenuHelper
def menu(records, menu_options={})
item_options = menu_options.merge({<some stuff>})
items = records.collect |record| do
menu_item(record, options)
end
content_tag(“ul”, items, options)
end
def menu_item(record, item_options={}))
action = item_options[:action]
action ||= “show”
content_tag(“li”, link_to(record.title, :action => action, item_options)
end
end
This helper will require that records passed into it have certain fields (notably :title). The helper could be written to use this as a default, allowing the field to be overwritten by an element of item_options.
Look at the Rails API for examples of helpers included in Rails, eg; [`ActionView::Helpers::ActiveRecordHelper`](http://api.rubyonrails.org/classes/ActionView/Helpers/ActiveRecordHelper.html).
Passing Blocks to Helper Methods
------------------------
We mentioned before that blocks can be passed to helper methods. This allows for an interesting wrinkle: a block passed to a helper method can cause it to render a partial, which can then be wrapped by the helper method’s output. This can make your helper method much more reusable. It doesn’t need to know anything about the internals about what it is rendering, it just contextualizes it for the page. You can also use the helper to modify the locals hash for the partial, based on some configuration information unique to the current controller. You could implement a flexible themes system in this way.
Partials vs. Helpers?
------------------------
In general, the choice between using a partial vs. using a helper depends on the amount of flexibility you need. If the task is more about reacting to conditions than performing actual rendering, you may likely want a helper method. If you want to be able to call it from a variety of views, again, you may want to use a helper method. You can expect to extract helper methods out of code in views and partials during refactoring.
Tutorial -- Calling a Helper [UNFINISHED]
------------------------
1. Create a Rails application using `rails helper_test`
Notice the code:
class ApplicationController < ActionController::Base
helper :all # include all helpers, all the time
For this tutorial, we'll keep this code, but you will likely want to exert more control over loading your helpers.
2. Configure a database of your choice for the app.
3. Inside of the `/app/helpers/` directory, create a new file called, `menu_helper.rb`. Write this in the file:
module MenuHelpers
def menu(records, item_proc=nil)
items = records.collect{ |record|
menu_item(record, item_proc)
}
content_tag("ul", items)
end
def menu_item(record, item_proc=nil)
item_url = item_proc.call(record)
item_url ||= { :action => :show }
content_tag("li", link_to(record.name, item_url))
end
end
4. Create a scaffold for some object in your app, using `./script/generate scaffold widgets`.
5. Create a database table for your widgets, with at least the fields `name` and `id`. Create a few widgets.
6. Call the menu command twice from `index.html.erb`, once using the default action, and once supplying a Proc to generate urls.

90
railties/doc/guides/actionview/partials.markdown
View file

@ -1,90 +0,0 @@
A Guide to Using Partials
===============================
This guide elaborates on the use and function of partials in Ruby on Rails. As your Rails application grows, your view templates can start to contain a lot of duplicate view code. To manage and reduce this complexity, you can by abstract view template code into partials. Partials are reusable snippets of eRB template code stored in separate files with an underscore ('_') prefix.
Partials can be located anywhere in the `app/views` directory. File extensions for partials work just like other template files, they bear an extension that denotes what kind of code they generate. For example, `_animal.html.erb` and `_animal.xml.erb` are valid filenames for partials.
Partials can be inserted in eRB template code by calling the `render` method with the `:partial` option. For example:
<%= render :partial => 'foo' %>
This inserts the result of evaluating the template `_foo.html.erb` into the parent template file at this location. Note that `render` assumes that the partial will be in the same directory as the calling parent template and have the same file extension. Partials can be located anywhere within the `app/views` directory. To use a partial located in a different directory then it the parent, add a '/' before it:
<%= render :partial => '/common/foo' %>
Loads the partial file from the `app/views/common/_foo.html.erb` directory.
Abstracting views into partials can be approached in a number of different ways, depending on the situation. Sometimes, the code that you are abstracting is a specialized view of an object or a collection of objects. Other times, you can look at partials as a reusable subroutine. We'll explore each of these approaches and when to use them as well as the syntax for calling them.
Partials as a View Subroutine
-----------------------------
Using the `:locals` option, you can pass a hash of values which will be treated as local variables within the partial template.
<%= render :partial => "person", :locals => { :name => "david" } %>
The variable `name` contains the value `"david"` within the `_person.html.erb` template. Passing variables in this way allows you to create modular, reusable template files. Note that if you want to make local variables that are optional in some use cases, you will have to set them to a sentinel value such as `nil` when they have not been passed. So, in the example above, if the `name` variable is optional in some use cases, you must set:
<% name ||= nil -%>
So that you can later check:
<% if name -%>
<p>Hello, <%= name %>!</p>
<% end -%>
Otherwise, the if statement will throw an error at runtime.
Another thing to be aware of is that instance variables that are visible to the parent view template are visible to the partial. So you might be tempted to do this:
<%= render :partial => "person" %>
And then within the partial:
<% if @name -%>
<p>Hello, <%= @name %>!</p>
<% end -%>
The potential snag here is that if multiple templates start to rely on this partial, you will need to maintain an instance variable with the same name across all of these templates and controllers. This approach can quickly become brittle if overused.
Partials as a View of an Object
--------------------------------
Another way to look at partials is to view them as mini-views of a particular object or instance variable. Use the `:object` option to pass an object assigns that object to an instance variable named after the partial itself. For example:
# Renders the partial, making @new_person available through
# the local variable 'person'
render :partial => "person", :object => @new_person
If the instance variable `name` in the parent template matches the name of the partial, you can use a shortcut:
render :partial => "person"
Now the value that was in `@person` in the parent template is accessible as `person` in the partial.
Partials as a View of a Collection
-----------------------------------
Often it is the case that you need to display not just a single object, but a collection of objects. Rather than having to constantly nest the same partial within the same iterator code, Rails provides a syntactical shortcut using the `:collection` option:
# Renders a collection of the same partial by making each element
# of @winners available through the local variable "person" as it
# builds the complete response.
render :partial => "person", :collection => @winners
This calls the `_person.html.erb` partial for each person in the `@winners` collection. This also creates a local variable within the partial called `partial_counter` which contains the index of the current value. So for example:
<%= partial_counter %>) <%= person -%>
Where `@winners` contains three people, produces the following output:
1) Bill
2) Jeff
3) Nick
One last detail, you can place an arbitrary snippet of code in between the objects using the `:spacer_template` option.
# Renders the same collection of partials, but also renders the
# person_divider partial between each person partial.
render :partial => "person", :collection => @winners, :spacer_template => "person_divider"

56
railties/doc/guides/activerecord/basics.markdown
View file

@ -1,56 +0,0 @@
Active Record Basics
====================
The ActiveRecord Pattern
------------------------
Active Record (the library) conforms to the active record design pattern. The active record pattern is a design pattern often found in applications that use relational database. The name comes from by Martin Fowler's book *Patterns of Enterprise Application Architecture*, in which he describes an active record object as:
> An object that wraps a row in a database table or view, encapsulates the database access, and adds domain logic on that data.
So, an object that follows the active record pattern encapsulates both data and behavior; in other words, they are responsible for saving and loading to the database and also for any domain logic that acts on the data. The data structure of the Active Record should exactly match that of the database: one field in the class for each column in the table.
The Active Record class typically has methods that do the following:
* Construct an instances of an Active Record class from a SQL result
* Construct a new class instance for insertion into the table
* Get and set column values
* Wrap business logic where appropriate
* Update existing objects and update the related rows in the database
Mapping Your Database
---------------------
### Plural tables, singular classes ###
### Schema lives in the database ###
Creating Records
----------------
### Using save ###
### Using create ###
Retrieving Existing Rows
------------------------
### Using find ###
### Using find_by_* ###
Editing and Updating Rows
-------------------------
### Editing an instance
### Using update_all/update_attributes ###
Deleting Data
-------------
### Destroying a record ###
### Deleting a record ###

1125
railties/doc/guides/html/actioncontroller_basics.html.html Normal file
View file

File diff suppressed because it is too large Load diff

2577
railties/doc/guides/html/association_basics.html Normal file
View file

File diff suppressed because it is too large Load diff

227
railties/doc/guides/html/authors.html Normal file
View file

@ -0,0 +1,227 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>About the Authors</title>
<!--[if lt IE 8]>
<script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
<![endif]-->
<link href="http://manuals.rubyonrails.org/stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
<style type="text/css">
div#container {
max-width: 900px;
padding-bottom: 3em;
}
div#content {
margin-left: 200px;
}
div#container.notoc {
max-width: 600px;
}
.notoc div#content {
margin-left: 0;
}
pre {
line-height: 1.4em;
}
#content p tt {
background: #eeeeee;
border: solid 1px #cccccc;
padding: 3px;
}
dt {
font-weight: bold;
}
#content dt tt {
font-size: 10pt;
}
dd {
margin-left: 3em;
}
#content dt tt, #content pre tt {
background: none;
padding: 0;
border: 0;
}
#content .olist ol {
margin-left: 2em;
}
#header {
position: relative;
max-width: 840px;
margin-left: auto;
margin-right: auto;
}
#header.notoc {
max-width: 580px;
}
#logo {
position: absolute;
left: 10px;
top: 10px;
width: 110px;
height: 140px;
}
div#header h1#site_title {
background: url('http://web.rubyonrails.com/images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
position: absolute;
width: 392px;
height: 55px;
left: 145px;
top: 20px;
margin: 0;
padding: 0;
}
#site_title span {
display: none;
}
#site_title_tagline {
display: none;
}
ul#navMain {
position: absolute;
margin: 0;
padding: 0;
top: 97px;
left: 145px;
}
.left-floaty, .right-floaty {
padding: 15px;
}
.admonitionblock,
.tableblock {
margin-left: 1em;
margin-right: 1em;
margin-top: 0.25em;
margin-bottom: 1em;
}
.admonitionblock .icon {
padding-right: 8px;
}
.admonitionblock .content {
border: solid 1px #ffda78;
background: #fffebd;
padding: 10px;
padding-top: 8px;
padding-bottom: 8px;
}
.admonitionblock .title {
font-size: 140%;
margin-bottom: 0.5em;
}
.tableblock table {
border: solid 1px #aaaaff;
background: #f0f0ff;
}
.tableblock th {
background: #e0e0e0;
}
.tableblock th,
.tableblock td {
padding: 3px;
padding-left: 5px;
padding-right: 5px;
}
.sidebarblock {
margin-top: 0.25em;
margin: 1em;
border: solid 1px #ccccbb;
padding: 8px;
background: #ffffe0;
}
.sidebarblock .sidebar-title {
font-size: 140%;
font-weight: 600;
margin-bottom: 0.3em;
}
.sidebarblock .sidebar-content > .para:last-child > p {
margin-bottom: 0;
}
.sidebarblock .sidebar-title a {
text-decoration: none;
}
.sidebarblock .sidebar-title a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div id="header" class="notoc">
<div id="logo">
<a href="http://www.rubyonrails.org/" title="Ruby on Rails"><img src="http://web.rubyonrails.com/images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
</div>
<h1 id="site_title"><span>Ruby on Rails</span></h1>
<h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
<ul id="navMain">
<li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
<li><a class="manuals" href="http://manuals.rubyonrails.org/" title="Manuals Index">Manuals Index</a></li>
</ul>
</div>
<div id="container" class="notoc">
<div id="content">
<h1>About the Authors</h1>
<div id="preamble">
<div class="sectionbody">
<div class="sidebarblock" id="fcheung">
<div class="sidebar-content">
<div class="sidebar-title">Frederick Cheung</div>
<div class="para"><p>Frederick Cheung is Chief Wizard at Texperts where he has been using Rails since 2006.
He is based in Cambridge (UK) and when not consuming fine ales he blogs at <a href="http://www.spacevatican.org">spacevatican.org</a>.</p></div>
</div></div>
<div class="sidebarblock" id="mgunderloy">
<div class="sidebar-content">
<div class="sidebar-title">Mike Gunderloy</div>
<div class="para"><p>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 <a href="http://afreshcup.com">A Fresh Cup</a>.</p></div>
</div></div>
<div class="sidebarblock" id="miloops">
<div class="sidebar-content">
<div class="sidebar-title">Emilio Tagua</div>
<div class="para"><p>Emilio Tagua &#8212; a.k.a. miloops &#8212; is an Argentinian entrepreneur, developer, open source contributor and Rails evangelist.
Cofounder of <a href="http://www.eventioz.com">Eventioz</a>. He has been using Rails since 2006 and contributing since early 2008.
Can be found at gmail, twitter, freenode, everywhere as miloops.</p></div>
</div></div>
</div>
</div>
</div>
</div>
</body>
</html>

1015
railties/doc/guides/html/benchmarking_and_profiling.html.html Normal file
View file

File diff suppressed because it is too large Load diff

577
railties/doc/guides/html/caching_with_rails.html Normal file
View file

@ -0,0 +1,577 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Caching with Rails: An overview</title>
<!--[if lt IE 8]>
<script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
<![endif]-->
<link href="http://manuals.rubyonrails.org/stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
<style type="text/css">
div#container {
max-width: 900px;
padding-bottom: 3em;
}
div#content {
margin-left: 200px;
}
div#container.notoc {
max-width: 600px;
}
.notoc div#content {
margin-left: 0;
}
pre {
line-height: 1.4em;
}
#content p tt {
background: #eeeeee;
border: solid 1px #cccccc;
padding: 3px;
}
dt {
font-weight: bold;
}
#content dt tt {
font-size: 10pt;
}
dd {
margin-left: 3em;
}
#content dt tt, #content pre tt {
background: none;
padding: 0;
border: 0;
}
#content .olist ol {
margin-left: 2em;
}
#header {
position: relative;
max-width: 840px;
margin-left: auto;
margin-right: auto;
}
#header.notoc {
max-width: 580px;
}
#logo {
position: absolute;
left: 10px;
top: 10px;
width: 110px;
height: 140px;
}
div#header h1#site_title {
background: url('http://web.rubyonrails.com/images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
position: absolute;
width: 392px;
height: 55px;
left: 145px;
top: 20px;
margin: 0;
padding: 0;
}
#site_title span {
display: none;
}
#site_title_tagline {
display: none;
}
ul#navMain {
position: absolute;
margin: 0;
padding: 0;
top: 97px;
left: 145px;
}
.left-floaty, .right-floaty {
padding: 15px;
}
.admonitionblock,
.tableblock {
margin-left: 1em;
margin-right: 1em;
margin-top: 0.25em;
margin-bottom: 1em;
}
.admonitionblock .icon {
padding-right: 8px;
}
.admonitionblock .content {
border: solid 1px #ffda78;
background: #fffebd;
padding: 10px;
padding-top: 8px;
padding-bottom: 8px;
}
.admonitionblock .title {
font-size: 140%;
margin-bottom: 0.5em;
}
.tableblock table {
border: solid 1px #aaaaff;
background: #f0f0ff;
}
.tableblock th {
background: #e0e0e0;
}
.tableblock th,
.tableblock td {
padding: 3px;
padding-left: 5px;
padding-right: 5px;
}
.sidebarblock {
margin-top: 0.25em;
margin: 1em;
border: solid 1px #ccccbb;
padding: 8px;
background: #ffffe0;
}
.sidebarblock .sidebar-title {
font-size: 140%;
font-weight: 600;
margin-bottom: 0.3em;
}
.sidebarblock .sidebar-content > .para:last-child > p {
margin-bottom: 0;
}
.sidebarblock .sidebar-title a {
text-decoration: none;
}
.sidebarblock .sidebar-title a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div id="header" >
<div id="logo">
<a href="http://www.rubyonrails.org/" title="Ruby on Rails"><img src="http://web.rubyonrails.com/images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
</div>
<h1 id="site_title"><span>Ruby on Rails</span></h1>
<h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
<ul id="navMain">
<li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
<li><a class="manuals" href="http://manuals.rubyonrails.org/" title="Manuals Index">Manuals Index</a></li>
</ul>
</div>
<div id="container">
<div id="sidebar">
<h2>Chapters</h2>
<ol>
<li>
<a href="#_basic_caching">Basic Caching</a>
<ul>
<li><a href="#_page_caching">Page Caching</a></li>
<li><a href="#_action_caching">Action Caching</a></li>
<li><a href="#_fragment_caching">Fragment Caching</a></li>
<li><a href="#_sweepers">Sweepers</a></li>
<li><a href="#_sql_caching">SQL Caching</a></li>
<li><a href="#_cache_stores">Cache stores</a></li>
</ul>
</li>
<li>
<a href="#_advanced_caching">Advanced Caching</a>
</li>
</ol>
</div>
<div id="content">
<h1>Caching with Rails: An overview</h1>
<div id="preamble">
<div class="sectionbody">
<div class="para"><p>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.</p></div>
</div>
</div>
<h2 id="_basic_caching">1. Basic Caching</h2>
<div class="sectionbody">
<div class="para"><p>This is an introduction to the three types of caching techniques that Rails
provides by default without the use of any third party plugins.</p></div>
<div class="para"><p>To get started make sure Base.perform_caching is set to true for your
environment.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Base<span style="color: #990000">.</span>perform_caching <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
</tt></pre></div></div>
<h3 id="_page_caching">1.1. Page Caching</h3>
<div class="para"><p>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.</p></div>
<div class="para"><p>So, how do you enable this super-fast cache behavior? Simple, let's say you
have a controller called ProductController and a <em>list</em> action that lists all
the products</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
cache_page <span style="color: #990000">:</span>list
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>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.</p></div>
<div class="para"><p>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</p></div>
<div class="para"><p>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</p></div>
<div class="para"><p>In order to expire this page when a new product is added we could extend our
example controler like this:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
cache_page <span style="color: #990000">:</span>list
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
expire_page <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>list
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>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.</p></div>
<h3 id="_action_caching">1.2. Action Caching</h3>
<div class="para"><p>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
authentication and other restrictions can be used while still serving the
result of the output from a cached copy.</p></div>
<div class="para"><p>Clearing the cache works in the exact same way as with Page Caching.</p></div>
<div class="para"><p>Let's say you only wanted authenticated users to edit or create a Product
object, but still cache those pages:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
before_filter <span style="color: #990000">:</span>authenticate<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>edit<span style="color: #990000">,</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
cache_page <span style="color: #990000">:</span>list
caches_action <span style="color: #990000">:</span>edit
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
expire_page <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>list
expire_action <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>edit
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> edit<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>And you can also use :if (or :unless) to pass a Proc that specifies when the
action should be cached. Also, you can use :layout &#8658; false to cache without
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.</p></div>
<div class="para"><p>[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?]</p></div>
<h3 id="_fragment_caching">1.3. Fragment Caching</h3>
<div class="para"><p>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.</p></div>
<div class="para"><p>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.</p></div>
<div class="para"><p>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:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000">&lt;% Order.find_recent.each do |o| %&gt;</span>
<span style="color: #FF0000">&lt;%= o.buyer.name %&gt;</span> bought <span style="color: #FF0000">&lt;% o.product.name %&gt;</span>
<span style="color: #FF0000">&lt;% end %&gt;</span>
<span style="color: #FF0000">&lt;% cache do %&gt;</span>
All available products<span style="color: #990000">:</span>
<span style="color: #FF0000">&lt;% Product.find(:all).each do |p| %&gt;</span>
<span style="color: #FF0000">&lt;%= link_to p.name, product_url(p) %&gt;</span>
<span style="color: #FF0000">&lt;% end %&gt;</span>
<span style="color: #FF0000">&lt;% end %&gt;</span>
</tt></pre></div></div>
<div class="para"><p>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:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000">&lt;% cache(:action =&gt;</span> <span style="color: #FF0000">'recent'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action_suffix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'all_products'</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">%&gt;</span>
All available products<span style="color: #990000">:</span>
</tt></pre></div></div>
<div class="para"><p>and you can expire it using the expire_fragment method, like so:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>expire_fragment<span style="color: #990000">(:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'producst'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'recent'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action_suffix <span style="color: #990000">=&gt;</span> 'all_products<span style="color: #990000">)</span>
</tt></pre></div></div>
<h3 id="_sweepers">1.4. Sweepers</h3>
<div class="para"><p>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 a ActionController::Caching::Sweeper
class that is an Observer and looks for changes to an object via callbacks,
and when a change occurs it expires the caches associated with that object n
an around or after filter.</p></div>
<div class="para"><p>Continuing with our Product controller example, we could rewrite it with a
sweeper such as the following:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> StoreSweeper <span style="color: #990000">&lt;</span> ActionController<span style="color: #990000">::</span>Caching<span style="color: #990000">::</span>Sweeper
observe Product <span style="font-style: italic"><span style="color: #9A1900"># This sweeper is going to keep an eye on the Post model</span></span>
<span style="font-style: italic"><span style="color: #9A1900"># If our sweeper detects that a Post was created call this</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> after_create<span style="color: #990000">(</span>product<span style="color: #990000">)</span>
expire_cache_for<span style="color: #990000">(</span>product<span style="color: #990000">)</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-style: italic"><span style="color: #9A1900"># If our sweeper detects that a Post was updated call this</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> after_update<span style="color: #990000">(</span>product<span style="color: #990000">)</span>
expire_cache_for<span style="color: #990000">(</span>product<span style="color: #990000">)</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-style: italic"><span style="color: #9A1900"># If our sweeper detects that a Post was deleted call this</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> after_destroy<span style="color: #990000">(</span>product<span style="color: #990000">)</span>
expire_cache_for<span style="color: #990000">(</span>product<span style="color: #990000">)</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
private
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> expire_cache_for<span style="color: #990000">(</span>record<span style="color: #990000">)</span>
<span style="font-style: italic"><span style="color: #9A1900"># Expire the list page now that we added a new product</span></span>
expire_page<span style="color: #990000">(:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'#{record}'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'list'</span><span style="color: #990000">)</span>
<span style="font-style: italic"><span style="color: #9A1900"># Expire a fragment</span></span>
expire_fragment<span style="color: #990000">(:</span>controller <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'#{record}'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'recent'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>action_suffix <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'all_products'</span><span style="color: #990000">)</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>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:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
before_filter <span style="color: #990000">:</span>authenticate<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>edit<span style="color: #990000">,</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
cache_page <span style="color: #990000">:</span>list
caches_action <span style="color: #990000">:</span>edit
cache_sweeper <span style="color: #990000">:</span>store_sweeper<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
expire_page <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>list
expire_action <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>edit
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> edit<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<h3 id="_sql_caching">1.5. SQL Caching</h3>
<div class="para"><p>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.</p></div>
<div class="para"><p>For example:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ProductController <span style="color: #990000">&lt;</span> ActionController
before_filter <span style="color: #990000">:</span>authenticate<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>edit<span style="color: #990000">,</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
cache_page <span style="color: #990000">:</span>list
caches_action <span style="color: #990000">:</span>edit
cache_sweeper <span style="color: #990000">:</span>store_sweeper<span style="color: #990000">,</span> <span style="color: #990000">:</span>only <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span> <span style="color: #990000">:</span>create <span style="color: #990000">]</span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> list
<span style="font-style: italic"><span style="color: #9A1900"># Run a find query</span></span>
Product<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">)</span>
<span style="color: #990000">...</span>
<span style="font-style: italic"><span style="color: #9A1900"># Run the same query again</span></span>
Product<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">)</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> create
expire_page <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>list
expire_action <span style="color: #990000">:</span>action <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>edit
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> edit<span style="color: #990000">;</span> <span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>In the <em>list</em> 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.</p></div>
<div class="para"><p>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.</p></div>
<h3 id="_cache_stores">1.6. Cache stores</h3>
<div class="para"><p>Rails provides different stores for the cached data for action and fragment
caches. Page caches are always stored on disk.</p></div>
<div class="para"><p>The cache stores provided include:</p></div>
<div class="para"><p>1) Memory store: Cached data is stored in the memory allocated to the Rails
process, which is fine for WEBrick and for FCGI (if you
don't care that each FCGI process holds its 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 up a lot of memory since each process keeps all the
caches in memory.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ActionController<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>cache_store <span style="color: #990000">=</span> <span style="color: #990000">:</span>memory_store
</tt></pre></div></div>
<div class="para"><p>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. Works
well for all types of environments and allows all processes
running from the same application directory to access the
cached content.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ActionController<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>cache_store <span style="color: #990000">=</span> <span style="color: #990000">:</span>file_store<span style="color: #990000">,</span> <span style="color: #FF0000">"/path/to/cache/directory"</span>
</tt></pre></div></div>
<div class="para"><p>3) DRb store: Cached data is stored in a separate shared DRb process that all
servers communicate with. This works for all environments and
only keeps one cache around for all processes, but requires
that you run and manage a separate DRb process.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ActionController<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>cache_store <span style="color: #990000">=</span> <span style="color: #990000">:</span>drb_store<span style="color: #990000">,</span> <span style="color: #FF0000">"druby://localhost:9192"</span>
</tt></pre></div></div>
<div class="para"><p>4) MemCached store: Works like DRbStore, but uses Danga's MemCache instead.
Requires the ruby-memcache library:
gem install ruby-memcache.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ActionController<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>cache_store <span style="color: #990000">=</span> <span style="color: #990000">:</span>mem_cache_store<span style="color: #990000">,</span> <span style="color: #FF0000">"localhost"</span>
</tt></pre></div></div>
<div class="para"><p>5) Custom store: You can define your own cache store (new in Rails 2.1)</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ActionController<span style="color: #990000">::</span>Base<span style="color: #990000">.</span>cache_store <span style="color: #990000">=</span> MyOwnStore<span style="color: #990000">.</span>new<span style="color: #990000">(</span><span style="color: #FF0000">"parameter"</span><span style="color: #990000">)</span>
</tt></pre></div></div>
</div>
<h2 id="_advanced_caching">2. Advanced Caching</h2>
<div class="sectionbody">
<div class="para"><p>Along with the built-in mechanisms outlined above, a number of excellent
plugins exist to help with finer grained control over caching. These include
Chris Wanstrath's excellent cache_fu plugin (more info here:
<a href="http://errtheblog.com/posts/57-kickin-ass-w-cachefu">http://errtheblog.com/posts/57-kickin-ass-w-cachefu</a>) and Evan Weaver's
interlock plugin (more info here:
<a href="http://blog.evanweaver.com/articles/2007/12/13/better-rails-caching/">http://blog.evanweaver.com/articles/2007/12/13/better-rails-caching/</a>). Both
of these plugins play nice with memcached and are a must-see for anyone
seriously considering optimizing their caching needs.</p></div>
</div>
</div>
</div>
</body>
</html>

1402
railties/doc/guides/html/creating_plugins.html.html Normal file
View file

File diff suppressed because it is too large Load diff

1051
railties/doc/guides/html/debugging_rails_applications.html Normal file
View file

File diff suppressed because it is too large Load diff

901
railties/doc/guides/html/finders.html Normal file
View file

@ -0,0 +1,901 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Rails Finders</title>
<!--[if lt IE 8]>
<script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
<![endif]-->
<link href="http://manuals.rubyonrails.org/stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
<style type="text/css">
div#container {
max-width: 900px;
padding-bottom: 3em;
}
div#content {
margin-left: 200px;
}
div#container.notoc {
max-width: 600px;
}
.notoc div#content {
margin-left: 0;
}
pre {
line-height: 1.4em;
}
#content p tt {
background: #eeeeee;
border: solid 1px #cccccc;
padding: 3px;
}
dt {
font-weight: bold;
}
#content dt tt {
font-size: 10pt;
}
dd {
margin-left: 3em;
}
#content dt tt, #content pre tt {
background: none;
padding: 0;
border: 0;
}
#content .olist ol {
margin-left: 2em;
}
#header {
position: relative;
max-width: 840px;
margin-left: auto;
margin-right: auto;
}
#header.notoc {
max-width: 580px;
}
#logo {
position: absolute;
left: 10px;
top: 10px;
width: 110px;
height: 140px;
}
div#header h1#site_title {
background: url('http://web.rubyonrails.com/images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
position: absolute;
width: 392px;
height: 55px;
left: 145px;
top: 20px;
margin: 0;
padding: 0;
}
#site_title span {
display: none;
}
#site_title_tagline {
display: none;
}
ul#navMain {
position: absolute;
margin: 0;
padding: 0;
top: 97px;
left: 145px;
}
.left-floaty, .right-floaty {
padding: 15px;
}
.admonitionblock,
.tableblock {
margin-left: 1em;
margin-right: 1em;
margin-top: 0.25em;
margin-bottom: 1em;
}
.admonitionblock .icon {
padding-right: 8px;
}
.admonitionblock .content {
border: solid 1px #ffda78;
background: #fffebd;
padding: 10px;
padding-top: 8px;
padding-bottom: 8px;
}
.admonitionblock .title {
font-size: 140%;
margin-bottom: 0.5em;
}
.tableblock table {
border: solid 1px #aaaaff;
background: #f0f0ff;
}
.tableblock th {
background: #e0e0e0;
}
.tableblock th,
.tableblock td {
padding: 3px;
padding-left: 5px;
padding-right: 5px;
}
.sidebarblock {
margin-top: 0.25em;
margin: 1em;
border: solid 1px #ccccbb;
padding: 8px;
background: #ffffe0;
}
.sidebarblock .sidebar-title {
font-size: 140%;
font-weight: 600;
margin-bottom: 0.3em;
}
.sidebarblock .sidebar-content > .para:last-child > p {
margin-bottom: 0;
}
.sidebarblock .sidebar-title a {
text-decoration: none;
}
.sidebarblock .sidebar-title a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div id="header" >
<div id="logo">
<a href="http://www.rubyonrails.org/" title="Ruby on Rails"><img src="http://web.rubyonrails.com/images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
</div>
<h1 id="site_title"><span>Ruby on Rails</span></h1>
<h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
<ul id="navMain">
<li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
<li><a class="manuals" href="http://manuals.rubyonrails.org/" title="Manuals Index">Manuals Index</a></li>
</ul>
</div>
<div id="container">
<div id="sidebar">
<h2>Chapters</h2>
<ol>
<li>
<a href="#_in_the_beginning_8230">In the beginning&#8230;</a>
</li>
<li>
<a href="#_our_models">Our Models</a>
</li>
<li>
<a href="#_database_agnostic">Database Agnostic</a>
</li>
<li>
<a href="#_ids_first_last_and_all">IDs, First, Last and All</a>
</li>
<li>
<a href="#_conditions">Conditions</a>
</li>
<li>
<a href="#_ordering">Ordering</a>
</li>
<li>
<a href="#_selecting_certain_fields">Selecting Certain Fields</a>
</li>
<li>
<a href="#_limit_amp_offset">Limit &amp; Offset</a>
</li>
<li>
<a href="#_group">Group</a>
</li>
<li>
<a href="#_read_only">Read Only</a>
</li>
<li>
<a href="#_lock">Lock</a>
</li>
<li>
<a href="#_making_it_all_work_together">Making It All Work Together</a>
</li>
<li>
<a href="#_eager_loading">Eager Loading</a>
</li>
<li>
<a href="#_dynamic_finders">Dynamic finders</a>
</li>
<li>
<a href="#_finding_by_sql">Finding By SQL</a>
</li>
<li>
<a href="#_working_with_associations">Working with Associations</a>
</li>
<li>
<a href="#_named_scopes">Named Scopes</a>
</li>
<li>
<a href="#_existance_of_objects">Existance of Objects</a>
</li>
<li>
<a href="#_calculations">Calculations</a>
<ul>
<li><a href="#_count">Count</a></li>
</ul>
</li>
<li>
<a href="#_with_scope">With Scope</a>
</li>
<li>
<a href="#_credits">Credits</a>
</li>
<li>
<a href="#_change_log">Change Log</a>
<ul>
<li><a href="#_sunday_28_september_2008">Sunday, 28 September 2008</a></li>
<li><a href="#_wednesday_01_october_2008">Wednesday, 01 October 2008</a></li>
<li><a href="#_sunday_05_october_2008">Sunday, 05 October 2008</a></li>
<li><a href="#_monday_06_october_2008">Monday, 06 October 2008</a></li>
<li><a href="#_thursday_09_october_2008">Thursday, 09 October 2008</a></li>
<li><a href="#_tuesday_21_october_2008">Tuesday, 21 October 2008</a></li>
</ul>
</li>
</ol>
</div>
<div id="content">
<h1>Rails Finders</h1>
<div id="preamble">
<div class="sectionbody">
<div class="para"><p>This guide is all about the <tt>find</tt> method defined in ActiveRecord::Base, finding on associations, and associated goodness such as named scopes. You will learn how to be a find master.</p></div>
</div>
</div>
<h2 id="_in_the_beginning_8230">1. In the beginning&#8230;</h2>
<div class="sectionbody">
<div class="para"><p>In the beginning there was SQL. SQL looked like this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients
<span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> id <span style="color: #990000">=</span> <span style="color: #FF0000">'1'</span>
<span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span>
<span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">ORDER</span></span> <span style="font-weight: bold"><span style="color: #0000FF">BY</span></span> id <span style="font-weight: bold"><span style="color: #0000FF">DESC</span></span> <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">0</span><span style="color: #990000">,</span><span style="color: #993399">1</span>
</tt></pre></div></div>
<div class="para"><p>In Rails you don't usually have to type SQL (unlike other languages) because ActiveRecord is there to help you find your records.</p></div>
</div>
<h2 id="_our_models">2. Our Models</h2>
<div class="sectionbody">
<div class="para"><p>For this guide we have the following models:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
has_one <span style="color: #990000">:</span>address
has_one <span style="color: #990000">:</span>mailing_address
has_many <span style="color: #990000">:</span>orders
has_and_belongs_to_many <span style="color: #990000">:</span>roles
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Address <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
belongs_to <span style="color: #990000">:</span>client
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> MailingAddress <span style="color: #990000">&lt;</span> Address
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Order <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
belongs_to <span style="color: #990000">:</span>client<span style="color: #990000">,</span> <span style="color: #990000">:</span>counter_cache <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Role <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
has_and_belongs_to_many <span style="color: #990000">:</span>clients
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
</div>
<h2 id="_database_agnostic">3. Database Agnostic</h2>
<div class="sectionbody">
<div class="para"><p>ActiveRecord will perform queries on the database for you and is compatible with most database systems (MySQL, PostgreSQL and SQLite to name a few). Regardless of which database system you're using, the ActiveRecord method format will always be the same.</p></div>
</div>
<h2 id="_ids_first_last_and_all">4. IDs, First, Last and All</h2>
<div class="sectionbody">
<div class="para"><p>ActiveRecord::Base has methods defined on it to make interacting with your database and the tables within it much, much easier: find. This method allows you to pass arguments into it to perform certain queries on your database without the need of SQL. If you wanted to find the record with the id of 1, you could type Client.find(1) which would execute this query on your database:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> <span style="color: #FF0000">`clients`</span> <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span><span style="color: #FF0000">`clients`</span><span style="color: #990000">.</span><span style="color: #FF0000">`id`</span> <span style="color: #990000">=</span> <span style="color: #993399">1</span><span style="color: #990000">)</span>
NOTE<span style="color: #990000">:</span> Please be aware that because this <span style="font-weight: bold"><span style="color: #0000FF">is</span></span> a standard <span style="font-weight: bold"><span style="color: #0000FF">table</span></span> created <span style="font-weight: bold"><span style="color: #0000FF">from</span></span> a migration <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> Rails that the <span style="font-weight: bold"><span style="color: #0000FF">primary</span></span> <span style="font-weight: bold"><span style="color: #0000FF">key</span></span> <span style="font-weight: bold"><span style="color: #0000FF">is</span></span> defaulted <span style="font-weight: bold"><span style="color: #0000FF">to</span></span> <span style="color: #FF0000">'id'</span><span style="color: #990000">.</span> <span style="font-weight: bold"><span style="color: #0000FF">If</span></span> you have specified a different <span style="font-weight: bold"><span style="color: #0000FF">primary</span></span> <span style="font-weight: bold"><span style="color: #0000FF">key</span></span> <span style="font-weight: bold"><span style="color: #0000FF">in</span></span> your migrations<span style="color: #990000">,</span> this <span style="font-weight: bold"><span style="color: #0000FF">is</span></span> what Rails will find <span style="font-weight: bold"><span style="color: #0000FF">on</span></span> when you call the find method<span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">not</span></span> the id <span style="font-weight: bold"><span style="color: #0000FF">column</span></span><span style="color: #990000">.</span>
</tt></pre></div></div>
<div class="para"><p>If you wanted to find clients with id 1 or 2, you call <tt>Client.find([1,2])</tt> or <tt>Client.find(1,2)</tt> and then this will be executed as:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> <span style="color: #FF0000">`clients`</span> <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span><span style="color: #FF0000">`clients`</span><span style="color: #990000">.</span><span style="color: #FF0000">`id`</span> <span style="font-weight: bold"><span style="color: #0000FF">IN</span></span> <span style="color: #990000">(</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">))</span>
<span style="color: #990000">[</span>source<span style="color: #990000">,</span>txt<span style="color: #990000">]</span>
<span style="color: #990000">&gt;&gt;</span> Client<span style="color: #990000">.</span>find<span style="color: #990000">(</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">)</span>
<span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="font-style: italic"><span style="color: #9A1900">#&lt;Client id: 1, name: =&gt; "Ryan", locked: false, orders_count: 2, created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"&gt;, #&lt;Client id: 2, name: =&gt; "Michael", locked: false, orders_count: 3, created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;]</span></span>
</tt></pre></div></div>
<div class="para"><p>Note that if you pass in a list of numbers that the result will be returned as an array, not an object of Client.</p></div>
<div class="para"><p>If you wanted to find the first client you would simply type <tt>Client.find(:first)</tt> and that would find the first client created in your clients table:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>&gt;&gt; Client.find(:first)
=&gt; #&lt;Client id: 1, name: =&gt; "Ryan", locked: false, orders_count: 2, created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"&gt;
If you were running script/server you may see the following output:
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">1</span>
</tt></pre></div></div>
<div class="para"><p>Indicating the query that Rails has performed on your database.</p></div>
<div class="para"><p>To find the last client you would simply type <tt>Client.find(:last)</tt> and that would find the last client created in your clients table:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>&gt;&gt; Client.find(:last)
=&gt; #&lt;Client id: 2, name: =&gt; "Michael", locked: false, orders_count: 3, created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">ORDER</span></span> <span style="font-weight: bold"><span style="color: #0000FF">BY</span></span> clients<span style="color: #990000">.</span>id <span style="font-weight: bold"><span style="color: #0000FF">DESC</span></span> <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">1</span>
</tt></pre></div></div>
<div class="para"><p>To find all the clients you would simply type <tt>Client.find(:all)</tt> and that would find all the clients in your clients table:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>&gt;&gt; Client.find(:all)
=&gt; [#&lt;Client id: 1, name: =&gt; "Ryan", locked: false, orders_count: 2, created_at: "2008-09-28 15:38:50", updated_at: "2008-09-28 15:38:50"&gt;, #&lt;Client id: 2, name: =&gt; "Michael", locked: false, orders_count: 3, created_at: "2008-09-28 13:12:40", updated_at: "2008-09-28 13:12:40"&gt;]
</tt></pre></div></div>
<div class="para"><p>Alternatively to calling Client.find(:first)/<tt>Client.find(:last)</tt>/<tt>Client.find(:all)</tt>, you could use the class method of <tt>Client.first</tt>/<tt>Client.last</tt>/<tt>Client.all</tt> instead. <tt>Client.first</tt>, <tt>Client.last</tt> and <tt>Client.all</tt> just call their longer counterparts.</p></div>
<div class="para"><p>Be aware that <tt>Client.first</tt>/<tt>Client.find(:first)</tt> and <tt>Client.last</tt>/<tt>Client.find(:last)</tt> will both return a single object, where as <tt>Client.all</tt>/<tt>Client.find(:all)</tt> will return an array of Client objects, just as passing in an array of ids to find will do also.</p></div>
</div>
<h2 id="_conditions">5. Conditions</h2>
<div class="sectionbody">
<div class="para"><p>If you'd like to add conditions to your find, you could just specify them in there, just like <tt>Client.find(:first, :conditions &#8658; "orders_count = <em>2</em>")</tt>. 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 <tt>Client.find(:first, :conditions &#8658; ["orders_count = ?", params[:orders]])</tt>. ActiveRecord will go through the first element in the conditions value 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 <tt>Client.find(:first, :conditions &#8658; ["orders_count = ? AND locked = ?", params[:orders], false])</tt>. In this example, the first question mark will be replaced with the value in params orders and the second will be replaced with true and this will find the first record in the table that has <em>2</em> as its value for the orders_count field and <em>false</em> for its locked field.</p></div>
<div class="para"><p>The reason for doing code like:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>`Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>first<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"orders_count = ?"</span><span style="color: #990000">,</span> params<span style="color: #990000">[:</span>orders<span style="color: #990000">]])</span>`
</tt></pre></div></div>
<div class="para"><p>instead of:</p></div>
<div class="para"><p><tt>Client.find(:first, :conditions &#8658; "orders_count = #{params[:orders]}")</tt></p></div>
<div class="para"><p>is because of parameter safety. Putting the variable directly into the conditions string will parse the variable <strong>as-is</strong>. This means that it will be an unescaped variable directly from a user who may have malicious intent. If you do this, you put your entire database at risk because once a user finds out he or she can exploit your database they can do just about anything to it. Never ever put your parameters directly inside the conditions string.</p></div>
<div class="para"><p>If you're looking for a range inside of a table for example users created in a certain timeframe you can use the conditions option coupled with the IN sql statement for this. If we had two dates coming in from a controller we could do something like this to look for a range:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at IN (?)"</span><span style="color: #990000">,</span> <span style="color: #990000">(</span>params<span style="color: #990000">[:</span>start_date<span style="color: #990000">].</span>to_date<span style="color: #990000">)..(</span>params<span style="color: #990000">[:</span>end_date<span style="color: #990000">].</span>to_date<span style="color: #990000">)])</span>
</tt></pre></div></div>
<div class="para"><p>This would generate the proper query which is great for small ranges but not so good for larger ranges. For example if you pass in a range of date objects spanning a year that's 365 (or possibly 366, depending on the year) strings it will attempt to match your field against.</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> <span style="color: #FF0000">`users`</span> <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span>created_at <span style="font-weight: bold"><span style="color: #0000FF">IN</span></span> <span style="color: #990000">(</span><span style="color: #FF0000">'2007-12-31'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-01'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-02'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-03'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-04'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-05'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-06'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-07'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-08'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-09'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-10'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-11'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-12'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-13'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-14'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-15'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-16'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-17'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-18'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-19'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-20'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-21'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-22'</span><span style="color: #990000">,</span><span style="color: #FF0000">'2008-01-23'</span><span style="color: #990000">,...</span>
<span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">15</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">16</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">17</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">18</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">19</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">20</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">21</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">22</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">23</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">24</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">25</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">26</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">27</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">28</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">29</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">30</span><span style="color: #FF0000">','</span><span style="color: #993399">2008</span><span style="color: #990000">-</span><span style="color: #993399">12</span><span style="color: #990000">-</span><span style="color: #993399">31</span><span style="color: #FF0000">'))</span>
</tt></pre></div></div>
<div class="para"><p>Things can get <strong>really</strong> messy if you pass in time objects as it will attempt to compare your field to <strong>every second</strong> in that range:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at IN (?)"</span><span style="color: #990000">,</span> <span style="color: #990000">(</span>params<span style="color: #990000">[:</span>start_date<span style="color: #990000">].</span>to_date<span style="color: #990000">.</span>to_time<span style="color: #990000">)..(</span>params<span style="color: #990000">[:</span>end_date<span style="color: #990000">].</span>to_date<span style="color: #990000">.</span>to_time<span style="color: #990000">)])</span>
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> <span style="color: #FF0000">`users`</span> <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span>created_at <span style="font-weight: bold"><span style="color: #0000FF">IN</span></span> <span style="color: #990000">(</span><span style="color: #FF0000">'2007-12-01 00:00:00'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'2007-12-01 00:00:01'</span> <span style="color: #990000">...</span> <span style="color: #FF0000">'2007-12-01 23:59:59'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'2007-12-02 00:00:00'</span><span style="color: #990000">))</span>
</tt></pre></div></div>
<div class="para"><p>This could possibly cause your database server to raise an unexpected error, for example MySQL will throw back this error:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Got a packet bigger than 'max_allowed_packet' bytes: &lt;query&gt;
</tt></pre></div></div>
<div class="para"><p>Where &lt;query&gt; is the actual query used to get that error.</p></div>
<div class="para"><p>In this example it would be better to use greater-than and less-than operators in SQL, like so:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">,</span> <span style="color: #990000">:</span>condtions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at &gt; ? AND created_at &lt; ?"</span><span style="color: #990000">,</span> params<span style="color: #990000">[:</span>start_date<span style="color: #990000">],</span> params<span style="color: #990000">[:</span>end_date<span style="color: #990000">]])</span>
</tt></pre></div></div>
<div class="para"><p>You can also use the greater-than-or-equal-to and less-than-or-equal-to like this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">,</span> <span style="color: #990000">:</span>condtions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at &gt;= ? AND created_at &lt;= ?"</span><span style="color: #990000">,</span> params<span style="color: #990000">[:</span>start_date<span style="color: #990000">],</span> params<span style="color: #990000">[:</span>end_date<span style="color: #990000">]])</span>
</tt></pre></div></div>
<div class="para"><p>Just like in Ruby.</p></div>
</div>
<h2 id="_ordering">6. Ordering</h2>
<div class="sectionbody">
<div class="para"><p>If you're getting a set of records and want to force an order, you can use <tt>Client.find(:all, :order &#8658; "created_at")</tt> 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 <tt>Client.find(:all, :order &#8658; "created_at desc")</tt></p></div>
</div>
<h2 id="_selecting_certain_fields">7. Selecting Certain Fields</h2>
<div class="sectionbody">
<div class="para"><p>To select certain fields, you can use the select option like this: <tt>Client.find(:first, :select &#8658; "viewable_by, locked")</tt>. This select option does not use an array of fields, but rather requires you to type SQL-like code. The above code will execute <tt>SELECT viewable_by, locked FROM clients LIMIT 0,1</tt> on your database.</p></div>
</div>
<h2 id="_limit_amp_offset">8. Limit &amp; Offset</h2>
<div class="sectionbody">
<div class="para"><p>If you want to limit the amount of records to a certain subset of all the records retreived you usually use limit for this, sometimes coupled with offset. Limit is the maximum number of records that will be retreived from a query, and offset is the number of records it will start reading from from the first record of the set. Take this code for example:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">,</span> <span style="color: #990000">:</span>limit <span style="color: #990000">=&gt;</span> <span style="color: #993399">5</span><span style="color: #990000">)</span>
</tt></pre></div></div>
<div class="para"><p>This code will return a maximum of 5 clients and because we've specified no offset it will return the first 5 clients in the table. The SQL it executes will look like this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">5</span>
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">,</span> <span style="color: #990000">:</span>limit <span style="color: #990000">=&gt;</span> <span style="color: #993399">5</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>offset <span style="color: #990000">=&gt;</span> <span style="color: #993399">5</span><span style="color: #990000">)</span>
</tt></pre></div></div>
<div class="para"><p>This code will return a maximum of 5 clients and because we have specified an offset this time, it will return these records starting from the 5th client in the clients table. The SQL looks like:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">5</span><span style="color: #990000">,</span> <span style="color: #993399">5</span>
</tt></pre></div></div>
</div>
<h2 id="_group">9. Group</h2>
<div class="sectionbody">
<div class="para"><p>TODO</p></div>
</div>
<h2 id="_read_only">10. Read Only</h2>
<div class="sectionbody">
<div class="para"><p>Readonly is a find option that you can set in order to make that instance of the record read-only. Any attempt to alter or destroy the record will not succeed, raising an <tt>ActiveRecord::ReadOnlyRecord</tt> error. To set this option, specify it like this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>first<span style="color: #990000">,</span> <span style="color: #990000">:</span>readonly <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">)</span>
</tt></pre></div></div>
<div class="para"><p>If you assign this record to a variable <tt>client</tt> calling the following code will raise an ActiveRecord::ReadOnlyRecord:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>client <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>first<span style="color: #990000">,</span> <span style="color: #990000">:</span>readonly <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">)</span>
client<span style="color: #990000">.</span>locked <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
client<span style="color: #990000">.</span>save
</tt></pre></div></div>
</div>
<h2 id="_lock">11. Lock</h2>
<div class="sectionbody">
<div class="para"><p>If you're wanting to stop race conditions for a specific record, say for example you're incrementing a single field for a record you can use the lock option to ensure that the record is updated correctly. It's recommended this be used inside a transaction.</p></div>
<div class="exampleblock">
<div class="exampleblock-content"></div></div>
</div>
<h2 id="_making_it_all_work_together">12. Making It All Work Together</h2>
<div class="sectionbody">
<div class="para"><p>You can chain these options together in no particular order as ActiveRecord will write the correct SQL for you. If you specify two instances of the same options inside the find statement ActiveRecord will use the latter.</p></div>
</div>
<h2 id="_eager_loading">13. Eager Loading</h2>
<div class="sectionbody">
<div class="para"><p>Eager loading is loading associated records along with any number of records in as few queries as possible. Lets say for example if we wanted to load all the addresses associated with all the clients all in the same query we would use <tt>Client.find(:all, :include &#8658; :address)</tt>. If we wanted to include both the address and mailing address for the client we would use `Client.find(:all), :include &#8658; [:address, :mailing_address]). Inclue will first find the client records and then load the associated address records. Running script/server in one window, and executing the code through script/console in another window, the output should look similar to this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client <span style="font-weight: bold"><span style="color: #0000FF">Load</span></span> <span style="color: #990000">(</span><span style="color: #993399">0.000383</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> clients
Address <span style="font-weight: bold"><span style="color: #0000FF">Load</span></span> <span style="color: #990000">(</span><span style="color: #993399">0.119770</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> addresses<span style="color: #990000">.*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> addresses <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span>addresses<span style="color: #990000">.</span>client_id <span style="font-weight: bold"><span style="color: #0000FF">IN</span></span> <span style="color: #990000">(</span><span style="color: #993399">13</span><span style="color: #990000">,</span><span style="color: #993399">14</span><span style="color: #990000">))</span>
MailingAddress <span style="font-weight: bold"><span style="color: #0000FF">Load</span></span> <span style="color: #990000">(</span><span style="color: #993399">0.001985</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> mailing_addresses<span style="color: #990000">.*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> mailing_addresses <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span>mailing_addresses<span style="color: #990000">.</span>client_id <span style="font-weight: bold"><span style="color: #0000FF">IN</span></span> <span style="color: #990000">(</span><span style="color: #993399">13</span><span style="color: #990000">,</span><span style="color: #993399">14</span><span style="color: #990000">))</span>
</tt></pre></div></div>
<div class="para"><p>The numbers <tt>13</tt> and <tt>14</tt> in the above SQL are the ids of the clients gathered from the <tt>Client.find(:all)</tt> query. Rails will then run a query to gather all the addresses and mailing addresses that have a client_id of 13 or 14. Although this is done in 3 queries, this is more efficient than not eager loading because without eager loading it would run a query for every time you called <tt>address</tt> or <tt>mailing_address</tt> on one of the objects in the clients array, which may lead to performance issues if you're loading a large number of records at once.</p></div>
<div class="para"><p>An alternative (and more efficient) way to do eager loading is to use the joins option. For example if we wanted to get all the addresses for a client we would do <tt>Client.find(:all, :joins &#8658; :address)</tt> and if we wanted to find the address and mailing address for that client we would do <tt>Client.find(:all, :joins &#8658; [:address, :mailing_address])</tt>. This is more efficient because it does all the SQL in one query, as shown by this example:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="color: #FF0000">`Client Load (0.000455) SELECT clients.* FROM clients INNER JOIN addresses ON addresses.client_id = client.id INNER JOIN mailing_addresses ON mailing_addresses.client_id = client.id</span>
</tt></pre></div></div>
<div class="para"><p>This query is more efficent, but there's a gotcha. If you have a client who does not have an address or a mailing address they will not be returned in this query at all. If you have any association as an optional association, you may want to use include rather than joins.</p></div>
<div class="para"><p>When using eager loading you can specify conditions for the columns of the tables inside the eager loading to get back a smaller subset. If, for example, you want to find a client and all their orders within the last two weeks you could use eager loading with conditions for this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"></div></div>
</div>
<h2 id="_dynamic_finders">14. Dynamic finders</h2>
<div class="sectionbody">
<div class="para"><p>With every field (also known as an attribute) you define in your table, ActiveRecord provides finder methods for these. If you have a field called <tt>name</tt> on your Client model for example, you get <tt>find_by_name</tt> and <tt>find_all_by_name</tt> for free from ActiveRecord. If you have also have a <tt>locked</tt> field on the client model, you also get <tt>find_by_locked</tt> and <tt>find_all_by_locked</tt>. If you want to find both by name and locked, you can chain these finders together by simply typing and between the fields for example <tt>Client.find_by_name_and_locked(<em>Ryan</em>, true)</tt>. These finders are an excellent alternative to using the conditions option, mainly because it's shorter to type <tt>find_by_name(params[:name])</tt> than it is to type <tt>find(:first, :conditions &#8658; ["name = ?", params[:name]])</tt>.</p></div>
<div class="para"><p>There's another set of dynamic finders that let you find or create/initialize objects if they aren't find. These work in a similar fashion to the other finders and can be used like <tt>find_or_create_by_name(params[:name])</tt>. Using this will firstly perform a find and then create if the find returns nil, the SQL looks like this for <tt>Client.find_or_create_by_name(<em>Ryan</em>)</tt>:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> <span style="color: #990000">*</span> <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> <span style="color: #FF0000">`clients`</span> <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span><span style="color: #FF0000">`clients`</span><span style="color: #990000">.</span><span style="color: #FF0000">`name`</span> <span style="color: #990000">=</span> <span style="color: #FF0000">'Ryan'</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">LIMIT</span></span> <span style="color: #993399">1</span>
BEGIN
<span style="font-weight: bold"><span style="color: #0000FF">INSERT</span></span> <span style="font-weight: bold"><span style="color: #0000FF">INTO</span></span> <span style="color: #FF0000">`clients`</span> <span style="color: #990000">(</span><span style="color: #FF0000">`name`</span><span style="color: #990000">,</span> <span style="color: #FF0000">`updated_at`</span><span style="color: #990000">,</span> <span style="color: #FF0000">`created_at`</span><span style="color: #990000">,</span> <span style="color: #FF0000">`orders_count`</span><span style="color: #990000">,</span> <span style="color: #FF0000">`locked`</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">VALUES</span></span><span style="color: #990000">(</span><span style="color: #FF0000">'Ryan'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'2008-09-28 15:39:12'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'2008-09-28 15:39:12'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'0'</span><span style="color: #990000">,</span> <span style="color: #FF0000">'0'</span><span style="color: #990000">)</span>
COMMIT
</tt></pre></div></div>
<div class="para"><p><tt>find_or_create</tt>'s sibling, find_or_initialize, will find an object and if it does not exist will call <tt>new</tt> with the parameters you passed in. For example:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>client <span style="color: #990000">=</span> Client<span style="color: #990000">.</span>find_or_initialize_by_name<span style="color: #990000">(</span><span style="color: #FF0000">'Ryan'</span><span style="color: #990000">)</span>
</tt></pre></div></div>
<div class="para"><p>will either assign an existing client object with the name <em>Ryan</em> to the client local variable, or initialize new object similar to calling <tt>Client.new(:name &#8658; <em>Ryan</em>)</tt>. From here, you can modify other fields in client by calling the attribute setters on it: <tt>client.locked = true</tt> and when you want to write it to the database just call <tt>save</tt> on it.</p></div>
</div>
<h2 id="_finding_by_sql">15. Finding By SQL</h2>
<div class="sectionbody">
<div class="para"><p>If you'd like to use your own SQL to find records a table you can use <tt>find_by_sql</tt>. <tt>find_by_sql</tt> will return an array of objects even if it only returns a single record in it's call to the database. For example you could run this query:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>find_by_sql<span style="color: #990000">(</span><span style="color: #FF0000">"SELECT * FROM clients INNER JOIN orders ON clients.id = orders.client_id ORDER clients.created_at desc"</span><span style="color: #990000">)</span>
</tt></pre></div></div>
<div class="para"><p><tt>find_by_sql</tt> provides you with a simple way of making custom calls to the database and converting those to objects.</p></div>
</div>
<h2 id="_working_with_associations">16. Working with Associations</h2>
<div class="sectionbody">
<div class="para"><p>When you define a has_many association on a model you get the find method and dynamic finders also on that association. This is helpful for finding associated records within the scope of an exisiting record, for example finding all the orders for a client that have been sent and not received by doing something like <tt>Client.find(params[:id]).orders.find_by_sent_and_received(true, false)</tt>. Having this find method available on associations is extremely helpful when using nested controllers.</p></div>
</div>
<h2 id="_named_scopes">17. Named Scopes</h2>
<div class="sectionbody">
<div class="para"><p>In this section we'll cover adding named scopes to the models in the application. Let's say we want to find all clients who are male we would use this code:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
named_scope <span style="color: #990000">:</span>males<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>gender <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"male"</span> <span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>And we could call it like <tt>Client.males</tt> to get all the clients who are male.</p></div>
<div class="para"><p>If we wanted to find all the clients who are active, we could use this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
named_scope <span style="color: #990000">:</span>active<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>active <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>We would call this new named_scope by doing <tt>Client.active</tt> and this will do the same query as if we just used <tt>Client.find(:all, :conditions &#8658; ["active = ?", true])</tt>. Please be aware that the conditions syntax in named_scope and find is different and the two are not interchangeable. If you want to find the first client within this named scope you could do <tt>Client.active.first</tt>.</p></div>
<div class="para"><p>and then if we wanted to find all the clients who are active and male we could stack the named scopes like this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>males<span style="color: #990000">.</span>active
</tt></pre></div></div>
<div class="para"><p>If you would then like to do a <tt>find</tt> on that subset of clients, you can. Just like an association, named scopes allow you to call <tt>find</tt> on a set of records:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>males<span style="color: #990000">.</span>active<span style="color: #990000">.</span>find<span style="color: #990000">(:</span>all<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"age &gt; ?"</span><span style="color: #990000">,</span> params<span style="color: #990000">[:</span>age<span style="color: #990000">]])</span>
</tt></pre></div></div>
<div class="para"><p>Now observe the following code:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
named_scope <span style="color: #990000">:</span>recent<span style="color: #990000">,</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>created_at <span style="color: #990000">&gt;</span> <span style="color: #993399">2</span><span style="color: #990000">.</span>weeks<span style="color: #990000">.</span>ago <span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>What we see here is what looks to be a standard named scope that defines a method called recent which gathers all records created any time between now and 2 weeks ago. That's correct for the first time the model is loaded but for any time after that, <tt>2.weeks.ago</tt> is set to that same value, so you will consistently get records from a certain date until your model is reloaded by something like your application restarting. The way to fix this is to put the code in a lambda block:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
named_scope <span style="color: #990000">:</span>recent<span style="color: #990000">,</span> lambda <span style="color: #FF0000">{</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at &gt; ?"</span><span style="color: #990000">,</span> <span style="color: #993399">2</span><span style="color: #990000">.</span>weeks<span style="color: #990000">.</span>ago<span style="color: #990000">]</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>And now every time the recent named scope is called, because it's wrapped in a lambda block this code will be parsed every time so you'll get actually 2 weeks ago from the code execution, not 2 weeks ago from the time the model was loaded.</p></div>
<div class="para"><p>In a named scope you can use <tt>:include</tt> and <tt>:joins</tt> options just like in find.</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
named_scope <span style="color: #990000">:</span>active_within_2_weeks<span style="color: #990000">,</span> <span style="color: #990000">:</span>joins <span style="color: #990000">=&gt;</span> <span style="color: #990000">:</span>order<span style="color: #990000">,</span> lambda <span style="color: #FF0000">{</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"orders.created_at &gt; ?"</span><span style="color: #990000">,</span> <span style="color: #993399">2</span><span style="color: #990000">.</span>weeks<span style="color: #990000">.</span>ago<span style="color: #990000">]</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>This method called as <tt>Client.active_within_2_weeks</tt> will return all clients who have placed orders in the past 2 weeks.</p></div>
<div class="para"><p>If you want to pass a named scope a compulsory argument, just specify it as a block parameter like this:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
named_scope <span style="color: #990000">:</span>recent<span style="color: #990000">,</span> lambda <span style="color: #FF0000">{</span> <span style="color: #990000">|</span>time<span style="color: #990000">|</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at &gt; ?"</span><span style="color: #990000">,</span> time<span style="color: #990000">]</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>This will work if we call <tt>Client.recent(2.weeks.ago)</tt> but not if we call <tt>Client.recent</tt>. If we want to add an optional argument for this, we have to use the splat operator as the block's parameter.</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Client <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
named_scope <span style="color: #990000">:</span>recent<span style="color: #990000">,</span> lambda <span style="color: #FF0000">{</span> <span style="color: #990000">|*</span>args<span style="color: #990000">|</span> <span style="color: #FF0000">{</span> <span style="color: #990000">:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #990000">[</span><span style="color: #FF0000">"created_at &gt; ?"</span><span style="color: #990000">,</span> args<span style="color: #990000">.</span>first <span style="color: #990000">||</span> <span style="color: #993399">2</span><span style="color: #990000">.</span>weeks<span style="color: #990000">.</span>ago<span style="color: #990000">]</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span> <span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>This will work with <tt>Client.recent(2.weeks.ago)</tt> and <tt>Client.recent</tt> with the latter always returning records with a created_at date between right now and 2 weeks ago.</p></div>
<div class="para"><p>Remember that named scopes are stackable, so you will be able to do <tt>Client.recent(2.weeks.ago).unlocked</tt> to find all clients created between right now and 2 weeks ago and have their locked field set to false.</p></div>
</div>
<h2 id="_existance_of_objects">18. Existance of Objects</h2>
<div class="sectionbody">
<div class="para"><p>If you simply want to check for the existance of the object there's a method called <tt>exists?</tt>. This method will query the database using the same query as find, but instead of returning an object or collection of objects it will return either true or false.</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>exists?<span style="color: #990000">(</span><span style="color: #993399">1</span><span style="color: #990000">)</span>
</tt></pre></div></div>
<div class="para"><p>The above code will check for the existance of a clients table record with the id of 1 and return true if it exists.</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>exists?<span style="color: #990000">(</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">)</span>
<span style="font-style: italic"><span style="color: #9A1900"># or</span></span>
Client<span style="color: #990000">.</span>exists?<span style="color: #990000">([</span><span style="color: #993399">1</span><span style="color: #990000">,</span><span style="color: #993399">2</span><span style="color: #990000">,</span><span style="color: #993399">3</span><span style="color: #990000">])</span>
</tt></pre></div></div>
<div class="para"><p><tt>exists?</tt> also takes multiple ids, as shown by the above code, but the catch is that it will return true if any one of those records exists.</p></div>
<div class="para"><p>Further more, <tt>exists</tt> takes a <tt>conditions</tt> option much like find:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>exists?<span style="color: #990000">(:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"first_name = 'Ryan'"</span><span style="color: #990000">)</span>
</tt></pre></div></div>
</div>
<h2 id="_calculations">19. Calculations</h2>
<div class="sectionbody">
<h3 id="_count">19.1. Count</h3>
<div class="para"><p>If you want to see how many records are in your models table you could call <tt>Client.count</tt> and that will return the number. If you want to be more specific and find all the clients with their age present in the database you can use <tt>Client.count(:age)</tt>.</p></div>
<div class="para"><p><tt>count</tt> takes conditions much in the same way <tt>exists?</tt> does:</p></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>Client<span style="color: #990000">.</span>count<span style="color: #990000">(:</span>conditions <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"first_name = 'Ryan'"</span><span style="color: #990000">)</span>
</tt></pre></div></div>
<div class="exampleblock">
<div class="exampleblock-content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">SELECT</span></span> count<span style="color: #990000">(*)</span> <span style="font-weight: bold"><span style="color: #0000FF">AS</span></span> count_all <span style="font-weight: bold"><span style="color: #0000FF">FROM</span></span> <span style="color: #FF0000">`clients`</span> <span style="font-weight: bold"><span style="color: #0000FF">WHERE</span></span> <span style="color: #990000">(</span>first_name <span style="color: #990000">=</span> <span style="color: #993399">1</span><span style="color: #990000">)</span>
</tt></pre></div></div>
</div>
<h2 id="_with_scope">20. With Scope</h2>
<div class="sectionbody">
<div class="para"><p>TODO</p></div>
</div>
<h2 id="_credits">21. Credits</h2>
<div class="sectionbody">
<div class="para"><p>Thanks to Ryan Bates for his awesome screencast on named scope #108. The information within the named scope section is intentionally similar to it, and without the cast may have not been possible.</p></div>
<div class="para"><p>Thanks to Mike Gunderloy for his tips on creating this guide.</p></div>
</div>
<h2 id="_change_log">22. Change Log</h2>
<div class="sectionbody">
<h3 id="_sunday_28_september_2008">22.1. Sunday, 28 September 2008</h3>
<div class="olist"><ol>
<li>
<p>
Changed "In Rails you don't have to type SQL" to "In Rails you don't usually have to type SQL"
</p>
</li>
<li>
<p>
Inserted paragraph in dynamic finders about find_or_create and find_or_initialize
</p>
</li>
<li>
<p>
Extended "First, Last, All" section.
</p>
</li>
<li>
<p>
Renamed "First, Last &amp; All" to "IDs, First, Last and All"
</p>
</li>
<li>
<p>
Added finding by id and passing in ids to "IDs, First, Last and All"
</p>
</li>
</ol></div>
<h3 id="_wednesday_01_october_2008">22.2. Wednesday, 01 October 2008</h3>
<div class="olist"><ol>
<li>
<p>
Did section on limit and offset, as well as section on readonly.
</p>
</li>
<li>
<p>
Altered formatting so it doesn't look bad.
</p>
</li>
</ol></div>
<h3 id="_sunday_05_october_2008">22.3. Sunday, 05 October 2008</h3>
<div class="olist"><ol>
<li>
<p>
Extended conditions section to include IN and using operators inside the conditions.
</p>
</li>
<li>
<p>
Extended conditions section to include paragraph and example of parameter safety.
</p>
</li>
<li>
<p>
Added TODO sections.
</p>
</li>
</ol></div>
<h3 id="_monday_06_october_2008">22.4. Monday, 06 October 2008</h3>
<div class="olist"><ol>
<li>
<p>
Added section in Eager Loading about using conditions on tables that are not the model's own.
</p>
</li>
</ol></div>
<h3 id="_thursday_09_october_2008">22.5. Thursday, 09 October 2008</h3>
<div class="olist"><ol>
<li>
<p>
Wrote section about lock option and tidied up "Making it all work together" section.
</p>
</li>
<li>
<p>
Added section on using count.
</p>
</li>
</ol></div>
<h3 id="_tuesday_21_october_2008">22.6. Tuesday, 21 October 2008</h3>
<div class="olist"><ol>
<li>
<p>
Extended named scope guide by adding :include and :joins and find sub-sections.
</p>
</li>
</ol></div>
</div>
</div>
</div>
</body>
</html>

570
railties/doc/guides/html/form_helpers.html Normal file
View file

@ -0,0 +1,570 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Rails form helpers</title>
<!--[if lt IE 8]>
<script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
<![endif]-->
<link href="http://manuals.rubyonrails.org/stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
<style type="text/css">
div#container {
max-width: 900px;
padding-bottom: 3em;
}
div#content {
margin-left: 200px;
}
div#container.notoc {
max-width: 600px;
}
.notoc div#content {
margin-left: 0;
}
pre {
line-height: 1.4em;
}
#content p tt {
background: #eeeeee;
border: solid 1px #cccccc;
padding: 3px;
}
dt {
font-weight: bold;
}
#content dt tt {
font-size: 10pt;
}
dd {
margin-left: 3em;
}
#content dt tt, #content pre tt {
background: none;
padding: 0;
border: 0;
}
#content .olist ol {
margin-left: 2em;
}
#header {
position: relative;
max-width: 840px;
margin-left: auto;
margin-right: auto;
}
#header.notoc {
max-width: 580px;
}
#logo {
position: absolute;
left: 10px;
top: 10px;
width: 110px;
height: 140px;
}
div#header h1#site_title {
background: url('http://web.rubyonrails.com/images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
position: absolute;
width: 392px;
height: 55px;
left: 145px;
top: 20px;
margin: 0;
padding: 0;
}
#site_title span {
display: none;
}
#site_title_tagline {
display: none;
}
ul#navMain {
position: absolute;
margin: 0;
padding: 0;
top: 97px;
left: 145px;
}
.left-floaty, .right-floaty {
padding: 15px;
}
.admonitionblock,
.tableblock {
margin-left: 1em;
margin-right: 1em;
margin-top: 0.25em;
margin-bottom: 1em;
}
.admonitionblock .icon {
padding-right: 8px;
}
.admonitionblock .content {
border: solid 1px #ffda78;
background: #fffebd;
padding: 10px;
padding-top: 8px;
padding-bottom: 8px;
}
.admonitionblock .title {
font-size: 140%;
margin-bottom: 0.5em;
}
.tableblock table {
border: solid 1px #aaaaff;
background: #f0f0ff;
}
.tableblock th {
background: #e0e0e0;
}
.tableblock th,
.tableblock td {
padding: 3px;
padding-left: 5px;
padding-right: 5px;
}
.sidebarblock {
margin-top: 0.25em;
margin: 1em;
border: solid 1px #ccccbb;
padding: 8px;
background: #ffffe0;
}
.sidebarblock .sidebar-title {
font-size: 140%;
font-weight: 600;
margin-bottom: 0.3em;
}
.sidebarblock .sidebar-content > .para:last-child > p {
margin-bottom: 0;
}
.sidebarblock .sidebar-title a {
text-decoration: none;
}
.sidebarblock .sidebar-title a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div id="header" >
<div id="logo">
<a href="http://www.rubyonrails.org/" title="Ruby on Rails"><img src="http://web.rubyonrails.com/images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
</div>
<h1 id="site_title"><span>Ruby on Rails</span></h1>
<h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
<ul id="navMain">
<li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
<li><a class="manuals" href="http://manuals.rubyonrails.org/" title="Manuals Index">Manuals Index</a></li>
</ul>
</div>
<div id="container">
<div id="sidebar">
<h2>Chapters</h2>
<ol>
<li>
<a href="#_basic_forms">Basic forms</a>
<ul>
<li><a href="#_generic_search_form">Generic search form</a></li>
<li><a href="#_multiple_hashes_in_form_helper_attributes">Multiple hashes in form helper attributes</a></li>
<li><a href="#_checkboxes_radio_buttons_and_other_controls">Checkboxes, radio buttons and other controls</a></li>
<li><a href="#_how_do_forms_with_put_or_delete_methods_work">How do forms with PUT or DELETE methods work?</a></li>
</ul>
</li>
<li>
<a href="#_forms_that_deal_with_model_attributes">Forms that deal with model attributes</a>
<ul>
<li><a href="#_relying_on_record_identification">Relying on record identification</a></li>
</ul>
</li>
</ol>
</div>
<div id="content">
<h1>Rails form helpers</h1>
<div id="preamble">
<div class="sectionbody">
<div class="para"><p>Forms in web applications are an essential interface for user input. They are also often considered the most complex elements of HTML. Rails deals away with these complexities by providing numerous view helpers for generating form markup. However, since they have different use-cases, developers are required to know all the differences between similar helper methods before putting them to use.</p></div>
<div class="para"><p>In this guide we will:</p></div>
<div class="ilist"><ul>
<li>
<p>
Create search forms and similar kind of generic forms not representing any specific model in your application;
</p>
</li>
<li>
<p>
Make model-centric forms for creation and editing of specific database records;
</p>
</li>
<li>
<p>
Generate select boxes from multiple types of data;
</p>
</li>
<li>
<p>
Learn what makes a file upload form different;
</p>
</li>
<li>
<p>
Build complex, multi-model forms.
</p>
</li>
</ul></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
</td>
<td class="content">This guide is not intended to be a complete documentation of available form helpers and their arguments. Please visit <a href="http://api.rubyonrails.org/">the Rails API documentation</a> for a complete reference.</td>
</tr></table>
</div>
</div>
</div>
<h2 id="_basic_forms">1. Basic forms</h2>
<div class="sectionbody">
<div class="para"><p>The most basic form helper is <tt>form_tag</tt>.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;% form_tag do %&gt;
Form contents
&lt;% end %&gt;</tt></pre>
</div></div>
<div class="para"><p>When called without arguments like this, it creates a form element that has the current page for action attribute and "POST" as method (some line breaks added for readability):</p></div>
<div class="listingblock">
<div class="title">Example: Sample rendering of <tt>form_tag</tt></div>
<div class="content">
<pre><tt>&lt;form action="/home/index" method="post"&gt;
&lt;div style="margin:0;padding:0"&gt;
&lt;input name="authenticity_token" type="hidden" value="f755bb0ed134b76c432144748a6d4b7a7ddf2b71" /&gt;
&lt;/div&gt;
Form contents
&lt;/form&gt;</tt></pre>
</div></div>
<div class="para"><p>If you carefully observe this output, you can see that the helper generated something we didn't specify: a <tt>div</tt> element with a hidden input inside. This is a security feature of Rails called <strong>cross-site request forgery protection</strong> and form helpers generate it for every form which action isn't "GET" (provided that this security feature is enabled).</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
</td>
<td class="content">Throughout this guide, this <tt>div</tt> with the hidden input will be stripped away to have clearer code samples.</td>
</tr></table>
</div>
<h3 id="_generic_search_form">1.1. Generic search form</h3>
<div class="para"><p>Probably the most minimal form often seen on the web is a search form with a single text input for search terms. This form consists of:</p></div>
<div class="olist"><ol>
<li>
<p>
a form element with "GET" method,
</p>
</li>
<li>
<p>
a label for the input,
</p>
</li>
<li>
<p>
a text input element, and
</p>
</li>
<li>
<p>
a submit element.
</p>
</li>
</ol></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/important.png" alt="Important" />
</td>
<td class="content">Always use "GET" as the method for search forms. Benefits are many: users are able to bookmark a specific search and get back to it; browsers cache results of "GET" requests, but not "POST"; and other.</td>
</tr></table>
</div>
<div class="para"><p>To create that, we will use <tt>form_tag</tt>, <tt>label_tag</tt>, <tt>text_field_tag</tt> and <tt>submit_tag</tt>, respectively.</p></div>
<div class="listingblock">
<div class="title">Example: A basic search form</div>
<div class="content">
<pre><tt>&lt;% form_tag(search_path, :method =&gt; "get") do %&gt;
&lt;%= label_tag(:q, "Search for:") %&gt;
&lt;%= text_field_tag(:q) %&gt;
&lt;%= submit_tag("Search") %&gt;
&lt;% end %&gt;</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/tip.png" alt="Tip" />
</td>
<td class="content">
<div class="para"><p><tt>search_path</tt> can be a named route specified in "routes.rb":</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>map.search "search", :controller =&gt; "search"</tt></pre>
</div></div>
</td>
</tr></table>
</div>
<div class="para"><p>The above view code will result in the following markup:</p></div>
<div class="listingblock">
<div class="title">Example: Search form HTML</div>
<div class="content">
<pre><tt>&lt;form action="/search" method="get"&gt;
&lt;label for="q"&gt;Search for:&lt;/label&gt;
&lt;input id="q" name="q" type="text" /&gt;
&lt;input name="commit" type="submit" value="Search" /&gt;
&lt;/form&gt;</tt></pre>
</div></div>
<div class="para"><p>Besides <tt>text_field_tag</tt> and <tt>submit_tag</tt>, there is a similar helper for <em>every</em> form control in HTML.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/tip.png" alt="Tip" />
</td>
<td class="content">For every form input, an ID attribute is generated from its name ("q" in our example). These IDs can be very useful for CSS styling or manipulation of form controls with JavaScript.</td>
</tr></table>
</div>
<h3 id="_multiple_hashes_in_form_helper_attributes">1.2. Multiple hashes in form helper attributes</h3>
<div class="para"><p>By now we've seen that the <tt>form_tag</tt> helper accepts 2 arguments: the path for the action attribute and an options hash for parameters (like <tt>:method</tt>).</p></div>
<div class="para"><p>Identical to the <tt>link_to</tt> helper, the path argument doesn't have to be given as string or a named route. It can be a hash of URL parameters that Rails' routing mechanism will turn into a valid URL. Still, we cannot simply write this:</p></div>
<div class="listingblock">
<div class="title">Example: A bad way to pass multiple hashes as method arguments</div>
<div class="content">
<pre><tt>form_tag(:controller =&gt; "people", :action =&gt; "search", :method =&gt; "get")
# =&gt; &lt;form action="/people/search?method=get" method="post"&gt;</tt></pre>
</div></div>
<div class="para"><p>Here we wanted to pass two hashes, but the Ruby interpreter sees only one hash, so Rails will construct a URL that we didn't want. The solution is to delimit the first hash (or both hashes) with curly brackets:</p></div>
<div class="listingblock">
<div class="title">Example: The correct way of passing multiple hashes as arguments</div>
<div class="content">
<pre><tt>form_tag({:controller =&gt; "people", :action =&gt; "search"}, :method =&gt; "get")
# =&gt; &lt;form action="/people/search" method="get"&gt;</tt></pre>
</div></div>
<div class="para"><p>This is a common pitfall when using form helpers, since many of them accept multiple hashes. So in future, if a helper produces unexpected output, make sure that you have delimited the hash parameters properly.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/warning.png" alt="Warning" />
</td>
<td class="content">Do not delimit the second hash without doing so with the first hash, otherwise your method invocation will result in an ugly <tt>expecting tASSOC</tt> syntax error.</td>
</tr></table>
</div>
<h3 id="_checkboxes_radio_buttons_and_other_controls">1.3. Checkboxes, radio buttons and other controls</h3>
<div class="para"><p>Checkboxes are form controls that give the user a set of options they can enable or disable:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;%= check_box_tag(:pet_dog) %&gt;
&lt;%= label_tag(:pet_dog, "I own a dog") %&gt;
&lt;%= check_box_tag(:pet_cat) %&gt;
&lt;%= label_tag(:pet_cat, "I own a cat") %&gt;
output:
&lt;input id="pet_dog" name="pet_dog" type="checkbox" value="1" /&gt;
&lt;label for="pet_dog"&gt;I own a dog&lt;/label&gt;
&lt;input id="pet_cat" name="pet_cat" type="checkbox" value="1" /&gt;
&lt;label for="pet_cat"&gt;I own a cat&lt;/label&gt;</tt></pre>
</div></div>
<div class="para"><p>Radio buttons, while similar to checkboxes, are controls that specify a set of options in which they are mutually exclusive (user can only pick one):</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;%= radio_button_tag(:age, "child") %&gt;
&lt;%= label_tag(:age_child, "I am younger than 21") %&gt;
&lt;%= radio_button_tag(:age, "adult") %&gt;
&lt;%= label_tag(:age_adult, "I'm over 21") %&gt;
output:
&lt;input id="age_child" name="age" type="radio" value="child" /&gt;
&lt;label for="age_child"&gt;I am younger than 21&lt;/label&gt;
&lt;input id="age_adult" name="age" type="radio" value="adult" /&gt;
&lt;label for="age_adult"&gt;I'm over 21&lt;/label&gt;</tt></pre>
</div></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/important.png" alt="Important" />
</td>
<td class="content">Always use labels for each checkbox and radio button. They associate text with a specific option, while also providing a larger clickable region.</td>
</tr></table>
</div>
<div class="para"><p>Other form controls we might mention are the text area, password input and hidden input:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;%= text_area_tag(:message, "Hi, nice site", :size =&gt; "24x6") %&gt;
&lt;%= password_field_tag(:password) %&gt;
&lt;%= hidden_field_tag(:parent_id, "5") %&gt;
output:
&lt;textarea id="message" name="message" cols="24" rows="6"&gt;Hi, nice site&lt;/textarea&gt;
&lt;input id="password" name="password" type="password" /&gt;
&lt;input id="parent_id" name="parent_id" type="hidden" value="5" /&gt;</tt></pre>
</div></div>
<div class="para"><p>Hidden inputs are not shown to the user, but they hold data same as any textual input. Values inside them can be changed with JavaScript.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/tip.png" alt="Tip" />
</td>
<td class="content">If you're using password input fields (for any purpose), you might want to prevent their values showing up in application logs by activating <tt>filter_parameter_logging(:password)</tt> in your ApplicationController.</td>
</tr></table>
</div>
<h3 id="_how_do_forms_with_put_or_delete_methods_work">1.4. How do forms with PUT or DELETE methods work?</h3>
<div class="para"><p>Rails framework encourages RESTful design of your applications, which means you'll be making a lot of "PUT" and "DELETE" requests (besides "GET" and "POST"). Still, most browsers <em>don't support</em> methods other than "GET" and "POST" when it comes to submitting forms. How does this work, then?</p></div>
<div class="para"><p>Rails works around this issue by emulating other methods over POST with a hidden input named <tt>"<em>method"</tt> that is set to reflect the _real</em> method:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>form_tag(search_path, :method =&gt; "put")
output:
&lt;form action="/search" method="post"&gt;
&lt;div style="margin:0;padding:0"&gt;
&lt;input name="_method" type="hidden" value="put" /&gt;
&lt;input name="authenticity_token" type="hidden" value="f755bb0ed134b76c432144748a6d4b7a7ddf2b71" /&gt;
&lt;/div&gt;
...</tt></pre>
</div></div>
<div class="para"><p>When parsing POSTed data, Rails will take into account the special <tt>"_method"</tt> parameter and act as if the HTTP method was the one specified inside it ("PUT" in this example).</p></div>
</div>
<h2 id="_forms_that_deal_with_model_attributes">2. Forms that deal with model attributes</h2>
<div class="sectionbody">
<div class="para"><p>When we're dealing with an actual model, we will use a different set of form helpers and have Rails take care of some details in the background. In the following examples we will handle an Article model. First, let us have the controller create one:</p></div>
<div class="listingblock">
<div class="title">Example: articles_controller.rb</div>
<div class="content">
<pre><tt>def new
@article = Article.new
end</tt></pre>
</div></div>
<div class="para"><p>Now we switch to the view. The first thing to remember is that we should use <tt>form_for</tt> helper instead of <tt>form_tag</tt>, and that we should pass the model name and object as arguments:</p></div>
<div class="listingblock">
<div class="title">Example: articles/new.html.erb</div>
<div class="content">
<pre><tt>&lt;% form_for :article, @article, :url =&gt; { :action =&gt; "create" } do |f| %&gt;
&lt;%= f.text_field :title %&gt;
&lt;%= f.text_area :body, :size =&gt; "60x12" %&gt;
&lt;%= submit_tag "Create" %&gt;
&lt;% end %&gt;</tt></pre>
</div></div>
<div class="para"><p>There are a few things to note here:</p></div>
<div class="olist"><ol>
<li>
<p>
<tt>:article</tt> is the name of the model and <tt>@article</tt> is our record.
</p>
</li>
<li>
<p>
The URL for the action attribute is passed as a parameter named <tt>:url</tt>.
</p>
</li>
<li>
<p>
The <tt>form_for</tt> method yields <strong>a form builder</strong> object (the <tt>f</tt> variable).
</p>
</li>
<li>
<p>
Methods to create form controls are called <strong>on</strong> the form builder object <tt>f</tt> and <strong>without</strong> the <tt>"_tag"</tt> suffix (so <tt>text_field_tag</tt> becomes <tt>f.text_field</tt>).
</p>
</li>
</ol></div>
<div class="para"><p>The resulting HTML is:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;form action="/articles/create" method="post"&gt;
&lt;input id="article_title" name="article[title]" size="30" type="text" /&gt;
&lt;textarea id="article_body" name="article[body]" cols="60" rows="12"&gt;&lt;/textarea&gt;
&lt;input name="commit" type="submit" value="Create" /&gt;
&lt;/form&gt;</tt></pre>
</div></div>
<div class="para"><p>A nice thing about <tt>f.text_field</tt> and other helper methods is that they will pre-fill the form control with the value read from the corresponding attribute in the model. For example, if we created the article instance by supplying an initial value for the title in the controller:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>@article = Article.new(:title =&gt; "Rails makes forms easy")</tt></pre>
</div></div>
<div class="para"><p>&#8230; the corresponding input will be rendered with a value:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>&lt;input id="post_title" name="post[title]" size="30" type="text" value="Rails makes forms easy" /&gt;</tt></pre>
</div></div>
<h3 id="_relying_on_record_identification">2.1. Relying on record identification</h3>
<div class="para"><p>In the previous chapter we handled the Article model. This model is directly available to users of our application and, following the best practices for developing with Rails, we should declare it <strong>a resource</strong>.</p></div>
<div class="para"><p>When dealing with RESTful resources, our calls to <tt>form_for</tt> can get significantly easier if we rely on <strong>record identification</strong>. In short, we can just pass the model instance and have Rails figure out model name and the rest:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>## Creating a new article
# long-style:
form_for(:article, @article, :url =&gt; articles_path)
# same thing, short-style (record identification gets used):
form_for(@article)
## Editing an existing article
# long-style:
form_for(:article, @article, :url =&gt; article_path(@article), :method =&gt; "put")
# short-style:
form_for(@article)</tt></pre>
</div></div>
<div class="para"><p>Notice how the short-style <tt>form_for</tt> invocation is conveniently the same, regardless of the record being new or existing. Record identification is smart enough to figure out if the record is new by asking <tt>record.new_record?</tt>.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/warning.png" alt="Warning" />
</td>
<td class="content">When you're using STI (single-table inheritance) with your models, you can't rely on record identification on a subclass if only their parent class is declared a resource. You will have to specify the model name, <tt>:url</tt> and <tt>:method</tt> explicitly.</td>
</tr></table>
</div>
</div>
</div>
</div>
</body>
</html>

1895
railties/doc/guides/html/getting_started_with_rails.html Normal file
View file

File diff suppressed because it is too large Load diff

380
railties/doc/guides/html/index.html Normal file
View file

@ -0,0 +1,380 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Ruby on Rails guides</title>
<!--[if lt IE 8]>
<script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
<![endif]-->
<link href="http://manuals.rubyonrails.org/stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
<style type="text/css">
div#container {
max-width: 900px;
padding-bottom: 3em;
}
div#content {
margin-left: 200px;
}
div#container.notoc {
max-width: 600px;
}
.notoc div#content {
margin-left: 0;
}
pre {
line-height: 1.4em;
}
#content p tt {
background: #eeeeee;
border: solid 1px #cccccc;
padding: 3px;
}
dt {
font-weight: bold;
}
#content dt tt {
font-size: 10pt;
}
dd {
margin-left: 3em;
}
#content dt tt, #content pre tt {
background: none;
padding: 0;
border: 0;
}
#content .olist ol {
margin-left: 2em;
}
#header {
position: relative;
max-width: 840px;
margin-left: auto;
margin-right: auto;
}
#header.notoc {
max-width: 580px;
}
#logo {
position: absolute;
left: 10px;
top: 10px;
width: 110px;
height: 140px;
}
div#header h1#site_title {
background: url('http://web.rubyonrails.com/images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
position: absolute;
width: 392px;
height: 55px;
left: 145px;
top: 20px;
margin: 0;
padding: 0;
}
#site_title span {
display: none;
}
#site_title_tagline {
display: none;
}
ul#navMain {
position: absolute;
margin: 0;
padding: 0;
top: 97px;
left: 145px;
}
.left-floaty, .right-floaty {
padding: 15px;
}
.admonitionblock,
.tableblock {
margin-left: 1em;
margin-right: 1em;
margin-top: 0.25em;
margin-bottom: 1em;
}
.admonitionblock .icon {
padding-right: 8px;
}
.admonitionblock .content {
border: solid 1px #ffda78;
background: #fffebd;
padding: 10px;
padding-top: 8px;
padding-bottom: 8px;
}
.admonitionblock .title {
font-size: 140%;
margin-bottom: 0.5em;
}
.tableblock table {
border: solid 1px #aaaaff;
background: #f0f0ff;
}
.tableblock th {
background: #e0e0e0;
}
.tableblock th,
.tableblock td {
padding: 3px;
padding-left: 5px;
padding-right: 5px;
}
.sidebarblock {
margin-top: 0.25em;
margin: 1em;
border: solid 1px #ccccbb;
padding: 8px;
background: #ffffe0;
}
.sidebarblock .sidebar-title {
font-size: 140%;
font-weight: 600;
margin-bottom: 0.3em;
}
.sidebarblock .sidebar-content > .para:last-child > p {
margin-bottom: 0;
}
.sidebarblock .sidebar-title a {
text-decoration: none;
}
.sidebarblock .sidebar-title a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div id="header" class="notoc">
<div id="logo">
<a href="http://www.rubyonrails.org/" title="Ruby on Rails"><img src="http://web.rubyonrails.com/images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
</div>
<h1 id="site_title"><span>Ruby on Rails</span></h1>
<h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
<ul id="navMain">
<li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
<li><a class="manuals" href="http://manuals.rubyonrails.org/" title="Manuals Index">Manuals Index</a></li>
</ul>
</div>
<div id="container" class="notoc">
<div id="content">
<h1>Ruby on Rails guides</h1>
<div id="preamble">
<div class="sectionbody">
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/warning.png" alt="Warning" />
</td>
<td class="content">This page is the result of ongoing <a href="http://hackfest.rubyonrails.org/guide">Rails Guides hackfest</a> and a work in progress.</td>
</tr></table>
</div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content">Guides marked with this icon are currently being worked on. While they might still be useful to you, they may contain incomplete information and even errors. You can help by reviewing them and posting your comments and corrections at the respective Lighthouse ticket.</td>
</tr></table>
</div>
<h2>Start Here</h2>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="getting_started_with_rails/getting_started_with_rails.html">Getting Started with Rails</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/2">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>Everything you need to know to install Rails and create your first application.</p></div>
</div></div>
<h2>Models</h2>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="migrations/migrations.html">Rails Database Migrations</a></div>
<div class="para"><p>This guide covers how you can use Active Record migrations to alter your database in a structured and organized manner.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="activerecord/association_basics.html">Active Record Associations</a></div>
<div class="para"><p>This guide covers all the associations provided by Active Record.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="activerecord/finders.html">Active Record Finders</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/16">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>This guide covers the find method defined in ActiveRecord::Base, as well as named scopes.</p></div>
</div></div>
<h2>Views</h2>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="actionview/layouts_and_rendering.html">Layouts and Rendering in Rails</a></div>
<div class="para"><p>This guide covers the basic layout features of Action Controller and Action View,
including rendering and redirecting, using +content_for_ blocks, and working
with partials.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="forms/form_helpers.html">Action View Form Helpers</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/1">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>Guide to using built in Form helpers.</p></div>
</div></div>
<h2>Controllers</h2>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="routing/routing_outside_in.html">Rails Routing from the Outside In</a></div>
<div class="para"><p>This guide covers the user-facing features of Rails routing. If you want to
understand how to use routing in your own Rails applications, start here.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="actioncontroller/actioncontroller.html">Basics of Action Controller</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/17">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>This guide covers how controllers work and how they fit into the request cycle in your application. It includes sessions, filters, and cookies, data streaming, and dealing with exceptions raised by a request, among other topics.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="caching/caching_with_rails.html">Rails Caching</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/10">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>This guide covers the three types of caching that Rails provides by default.</p></div>
</div></div>
<h2>Digging Deeper</h2>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="testing_rails_applications/testing_rails_applications.html">Testing Rails Applications</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/8">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>This is a rather comprehensive guide to doing both unit and functional tests
in Rails. It covers everything from &#8220;What is a test?&#8221; to the testing APIs.
Enjoy.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="securing_rails_applications/security.html">Securing Rails Applications</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/7">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>This manual describes common security problems in web applications and how to
avoid them with Rails.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="debugging/debugging_rails_applications.html">Debugging Rails Applications</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/5">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>This guide describes how to debug Rails applications. It covers the different
ways of achieving this and how to understand what is happening "behind the scenes"
of your code.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="benchmarking_and_profiling/index.html">Benchmarking and Profiling Rails Applications</a></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/caution.png" alt="Caution" />
</td>
<td class="content"><a href="http://rails.lighthouseapp.com/projects/16213/tickets/4">Lighthouse Ticket</a></td>
</tr></table>
</div>
<div class="para"><p>This guide covers ways to analyze and optimize your running Rails code.</p></div>
</div></div>
<div class="sidebarblock">
<div class="sidebar-content">
<div class="sidebar-title"><a href="creating_plugins/creating_plugins.html">The Basics of Creating Rails Plugins</a></div>
<div class="para"><p>This guide covers how to build a plugin to extend the functionality of Rails.</p></div>
</div></div>
<div class="para"><p>Authors who have contributed to complete guides are listed <a href="authors.html">here</a>.</p></div>
</div>
</div>
</div>
</div>
</body>
</html>

1199
railties/doc/guides/html/layouts_and_rendering.html Normal file
View file

File diff suppressed because it is too large Load diff

921
railties/doc/guides/html/migrations.html.html Normal file
View file

@ -0,0 +1,921 @@
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>Migrations</title>
<!--[if lt IE 8]>
<script src="http://ie7-js.googlecode.com/svn/version/2.0(beta3)/IE8.js" type="text/javascript"></script>
<![endif]-->
<link href="http://manuals.rubyonrails.org/stylesheets/base.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/forms.css" media="screen" rel="Stylesheet" type="text/css" />
<link href="http://manuals.rubyonrails.org/stylesheets/more.css" media="screen" rel="Stylesheet" type="text/css" />
<style type="text/css">
div#container {
max-width: 900px;
padding-bottom: 3em;
}
div#content {
margin-left: 200px;
}
div#container.notoc {
max-width: 600px;
}
.notoc div#content {
margin-left: 0;
}
pre {
line-height: 1.4em;
}
#content p tt {
background: #eeeeee;
border: solid 1px #cccccc;
padding: 3px;
}
dt {
font-weight: bold;
}
#content dt tt {
font-size: 10pt;
}
dd {
margin-left: 3em;
}
#content dt tt, #content pre tt {
background: none;
padding: 0;
border: 0;
}
#content .olist ol {
margin-left: 2em;
}
#header {
position: relative;
max-width: 840px;
margin-left: auto;
margin-right: auto;
}
#header.notoc {
max-width: 580px;
}
#logo {
position: absolute;
left: 10px;
top: 10px;
width: 110px;
height: 140px;
}
div#header h1#site_title {
background: url('http://web.rubyonrails.com/images/ruby_on_rails_by_mike_rundle2.gif') top left no-repeat;
position: absolute;
width: 392px;
height: 55px;
left: 145px;
top: 20px;
margin: 0;
padding: 0;
}
#site_title span {
display: none;
}
#site_title_tagline {
display: none;
}
ul#navMain {
position: absolute;
margin: 0;
padding: 0;
top: 97px;
left: 145px;
}
.left-floaty, .right-floaty {
padding: 15px;
}
.admonitionblock,
.tableblock {
margin-left: 1em;
margin-right: 1em;
margin-top: 0.25em;
margin-bottom: 1em;
}
.admonitionblock .icon {
padding-right: 8px;
}
.admonitionblock .content {
border: solid 1px #ffda78;
background: #fffebd;
padding: 10px;
padding-top: 8px;
padding-bottom: 8px;
}
.admonitionblock .title {
font-size: 140%;
margin-bottom: 0.5em;
}
.tableblock table {
border: solid 1px #aaaaff;
background: #f0f0ff;
}
.tableblock th {
background: #e0e0e0;
}
.tableblock th,
.tableblock td {
padding: 3px;
padding-left: 5px;
padding-right: 5px;
}
.sidebarblock {
margin-top: 0.25em;
margin: 1em;
border: solid 1px #ccccbb;
padding: 8px;
background: #ffffe0;
}
.sidebarblock .sidebar-title {
font-size: 140%;
font-weight: 600;
margin-bottom: 0.3em;
}
.sidebarblock .sidebar-content > .para:last-child > p {
margin-bottom: 0;
}
.sidebarblock .sidebar-title a {
text-decoration: none;
}
.sidebarblock .sidebar-title a:hover {
text-decoration: underline;
}
</style>
</head>
<body>
<div id="header" >
<div id="logo">
<a href="http://www.rubyonrails.org/" title="Ruby on Rails"><img src="http://web.rubyonrails.com/images/rails_logo_remix.gif" alt="Rails" height="140" width="110" /></a>
</div>
<h1 id="site_title"><span>Ruby on Rails</span></h1>
<h2 id="site_title_tagline">Sustainable productivity for web-application development</h2>
<ul id="navMain">
<li class="first-child"><a href="http://www.rubyonrails.org/" title="Ruby on Rails" class="ruby_on_rails">Ruby on Rails</a></li>
<li><a class="manuals" href="http://manuals.rubyonrails.org/" title="Manuals Index">Manuals Index</a></li>
</ul>
</div>
<div id="container">
<div id="sidebar">
<h2>Chapters</h2>
<ol>
<li>
<a href="#_anatomy_of_a_migration">Anatomy Of A Migration</a>
<ul>
<li><a href="#_migrations_are_classes">Migrations are classes</a></li>
<li><a href="#_what_s_in_a_name">What's in a name</a></li>
<li><a href="#_changing_migrations">Changing migrations</a></li>
</ul>
</li>
<li>
<a href="#_creating_a_migration">Creating A Migration</a>
<ul>
<li><a href="#_creating_a_model">Creating a model</a></li>
<li><a href="#_creating_a_standalone_migration">Creating a standalone migration</a></li>
</ul>
</li>
<li>
<a href="#_writing_a_migration">Writing a Migration</a>
<ul>
<li><a href="#_creating_a_table">Creating a table</a></li>
<li><a href="#_changing_tables">Changing tables</a></li>
<li><a href="#_special_helpers">Special helpers</a></li>
<li><a href="#_writing_your_down_method">Writing your down method</a></li>
</ul>
</li>
<li>
<a href="#_running_migrations">Running Migrations</a>
<ul>
<li><a href="#_rolling_back">Rolling back</a></li>
<li><a href="#_being_specific">Being Specific</a></li>
<li><a href="#_being_talkative">Being talkative</a></li>
</ul>
</li>
<li>
<a href="#models">Using Models In Your Migrations</a>
<ul>
<li><a href="#_dealing_with_changing_models">Dealing with changing models</a></li>
</ul>
</li>
<li>
<a href="#_schema_dumping_and_you">Schema dumping and you</a>
<ul>
<li><a href="#schema">What are schema files for?</a></li>
<li><a href="#_types_of_schema_dumps">Types of schema dumps</a></li>
<li><a href="#_schema_dumps_and_source_control">Schema dumps and source control</a></li>
</ul>
</li>
<li>
<a href="#foreign_key">Active Record and Referential Integrity</a>
</li>
<li>
<a href="#_changelog">Changelog</a>
</li>
</ol>
</div>
<div id="content">
<h1>Migrations</h1>
<div id="preamble">
<div class="sectionbody">
<div class="para"><p>Migrations are a convenient way for you to alter your database in a structured and organised manner. You could edit fragments of SQL by hand but you would then be responsible for telling other developers that they need to go and run it. You'd also have to keep track of which changes need to be run against the production machines next time you deploy. Active Record tracks which migrations have already been run so all you have to do is update your source and run <tt>rake db:migrate</tt>. Active Record will work out which migrations should be run.</p></div>
<div class="para"><p>Migrations also allow you to describe these transformations using Ruby. The great thing about this is that (like most of Active Record's functionality) it is database independent: you don't need to worry about the precise syntax of CREATE TABLE any more that you worry about variations on SELECT * (you can drop down to raw SQL for database specific features). For example you could use SQLite3 in development, but MySQL in production.</p></div>
<div class="para"><p>You'll learn all about migrations including:</p></div>
<div class="ilist"><ul>
<li>
<p>
The generators you can use to create them
</p>
</li>
<li>
<p>
The methods Active Record provides to manipulate your database
</p>
</li>
<li>
<p>
The Rake tasks that manipulate them
</p>
</li>
<li>
<p>
How they relate to <tt>schema.rb</tt>
</p>
</li>
</ul></div>
</div>
</div>
<h2 id="_anatomy_of_a_migration">1. Anatomy Of A Migration</h2>
<div class="sectionbody">
<div class="para"><p>Before I dive into the details of a migration, here are a few examples of the sorts of things you can do:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> CreateProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name
t<span style="color: #990000">.</span>text <span style="color: #990000">:</span>description
t<span style="color: #990000">.</span>timestamps
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
drop_table <span style="color: #990000">:</span>products
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>This migration adds a table called <tt>products</tt> with a string column called <tt>name</tt> and a text column called <tt>description</tt>. A primary key column called <tt>id</tt> will also be added, however since this is the default we do not need to ask for this. The timestamp columns <tt>created_at</tt> and <tt>updated_at</tt> which Active Record populates automatically will also be added. Reversing this migration is as simple as dropping the table.</p></div>
<div class="para"><p>Migrations are not limited to changing the schema. You can also use them to fix bad data in the database or populate new fields:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddReceiveNewsletterToUsers <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
change_table <span style="color: #990000">:</span>users <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>boolean <span style="color: #990000">:</span>receive_newsletter<span style="color: #990000">,</span> <span style="color: #990000">:</span>default <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
User<span style="color: #990000">.</span>update_all <span style="color: #990000">[</span><span style="color: #FF0000">"receive_newsletter = ?"</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span><span style="color: #990000">]</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
remove_column <span style="color: #990000">:</span>users<span style="color: #990000">,</span> <span style="color: #990000">:</span>receive_newsletter
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>This migration adds an <tt>receive_newsletter</tt> column to the <tt>users</tt> table. We want it to default to <tt>false</tt> for new users, but existing users are considered
to have already opted in, so we use the User model to set the flag to <tt>true</tt> for existing users.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
</td>
<td class="content">Some <a href="#models">caveats</a> apply to using models in your migrations.</td>
</tr></table>
</div>
<h3 id="_migrations_are_classes">1.1. Migrations are classes</h3>
<div class="para"><p>A migration is a subclass of ActiveRecord::Migration that implements two class methods: <tt>up</tt> (perform the required transformations) and <tt>down</tt> (revert them).</p></div>
<div class="para"><p>Active Record provides methods that perform common data definition tasks in a database independent way (you'll read about them in detail later):</p></div>
<div class="ilist"><ul>
<li>
<p>
<tt>create_table</tt>
</p>
</li>
<li>
<p>
<tt>change_table</tt>
</p>
</li>
<li>
<p>
<tt>drop_table</tt>
</p>
</li>
<li>
<p>
<tt>add_column</tt>
</p>
</li>
<li>
<p>
<tt>remove_column</tt>
</p>
</li>
<li>
<p>
<tt>change_column</tt>
</p>
</li>
<li>
<p>
<tt>rename_column</tt>
</p>
</li>
<li>
<p>
<tt>add_index</tt>
</p>
</li>
<li>
<p>
<tt>remove_index</tt>
</p>
</li>
</ul></div>
<div class="para"><p>If you need to perform tasks specific to your database (for example create a <a href="#foreign_key">foreign key</a> constraint) then the <tt>execute</tt> function allows you to execute arbitrary SQL. A migration is just a regular Ruby class so you're not limited to these functions. For example after adding a column you could
write code to set the value of that column for existing records (if necessary using your models).</p></div>
<div class="para"><p>On databases that support transactions with statements that change the schema (such as PostgreSQL), migrations are wrapped in a transaction. If the database does not support this (for example MySQL and SQLite) then when a migration fails the parts of it that succeeded will not be rolled back. You will have to unpick the changes that were made by hand.</p></div>
<h3 id="_what_s_in_a_name">1.2. What's in a name</h3>
<div class="para"><p>Migrations are stored in files in <tt>db/migrate</tt>, one for each migration class. The name of the file is of the form <tt>YYYYMMDDHHMMSS_create_products.rb</tt>, that is to say a UTC timestamp identifying the migration followed by an underscore followed by the name of the migration. The migration class' name must match (the camelcased version of) the latter part of the file name. For example <tt>20080906120000_create_products.rb</tt> should define CreateProducts and <tt>20080906120001_add_details_to_products.rb</tt> should define AddDetailsToProducts. If you do feel the need to change the file name then you MUST update the name of the class inside or Rails will complain about a missing class.</p></div>
<div class="para"><p>Internally Rails only uses the migration's number (the timestamp) to identify them. Prior to Rails 2.1 the migration number started at 1 and was incremented each time a migration was generated. With multiple developers it was easy for these to clash requiring you to rollback migrations and renumber them. With Rails 2.1 this is largely avoided by using the creation time of the migration to identify them. You can revert to the old numbering scheme by setting <tt>config.active_record.timestamped_migrations</tt> to <tt>false</tt> in <tt>environment.rb</tt>.</p></div>
<div class="para"><p>The combination of timestamps and recording which migrations have been run allows Rails to handle common situations that occur with multiple developers.</p></div>
<div class="para"><p>For example Alice adds migrations <tt>20080906120000</tt> and <tt>20080906123000</tt> and Bob adds <tt>20080906124500</tt> and runs it. Alice finishes her changes and checks in her migrations and Bob pulls down the latest changes. Rails knows that it has not run Alice's two migrations so <tt>rake db:migrate</tt> would run them (even though Bob's migration with a later timestamp has been run), and similarly migrating down would not run their down methods.</p></div>
<div class="para"><p>Of course this is no substitution for communication within the team, for example if Alice's migration removed a table that Bob's migration assumed the existence of then trouble will still occur.</p></div>
<h3 id="_changing_migrations">1.3. Changing migrations</h3>
<div class="para"><p>Occasionally you will make a mistake while writing a migration. If you have already run the migration then you cannot just edit the migration and run the migration again: Rails thinks it has already run the migration and so will do nothing when you run <tt>rake db:migrate</tt>. You must rollback the migration (for example with <tt>rake db:rollback</tt>), edit your migration and then run <tt>rake db:migrate</tt> to run the corrected version.</p></div>
<div class="para"><p>In general editing existing migrations is not a good idea: you will be creating extra work for yourself and your co-workers and cause major headaches if the existing version of the migration has already been run on production machines. Instead you should write a new migration that performs the changes you require. Editing a freshly generated migration that has not yet been committed to source control (or more generally which has not been propagated beyond your development machine) is relatively harmless. Just use some common sense.</p></div>
</div>
<h2 id="_creating_a_migration">2. Creating A Migration</h2>
<div class="sectionbody">
<h3 id="_creating_a_model">2.1. Creating a model</h3>
<div class="para"><p>The model and scaffold generators will create migrations appropriate for adding a new model. This migration will already contain instructions for creating the relevant table. If you tell Rails what columns you want then statements for adding those will also be created. For example, running</p></div>
<div class="para"><p><tt>ruby script/generate model Product name:string description:text</tt> will create a migration that looks like this</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> CreateProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name
t<span style="color: #990000">.</span>text <span style="color: #990000">:</span>description
t<span style="color: #990000">.</span>timestamps
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
drop_table <span style="color: #990000">:</span>products
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>You can append as many column name/type pairs as you want. By default <tt>t.timestamps</tt> (which creates the <tt>updated_at</tt> and <tt>created_at</tt> columns that
are automatically populated by Active Record) will be added for you.</p></div>
<h3 id="_creating_a_standalone_migration">2.2. Creating a standalone migration</h3>
<div class="para"><p>If you are creating migrations for other purposes (for example to add a column to an existing table) then you can use the migration generator:</p></div>
<div class="para"><p><tt>ruby script/generate migration AddPartNumberToProducts</tt></p></div>
<div class="para"><p>This will create an empty but appropriately named migration:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddPartNumberToProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>If the migration name is of the form AddXXXToYYY or RemoveXXXFromY and is followed by a list of column names and types then a migration containing
the appropriate add and remove column statements will be created.</p></div>
<div class="para"><p><tt>ruby script/generate migration AddPartNumberToProducts part_number:string</tt></p></div>
<div class="para"><p>will generate</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddPartNumberToProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
add_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
remove_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>Similarly,</p></div>
<div class="para"><p><tt>ruby script/generate migration RemovePartNumberFromProducts part_number:string</tt></p></div>
<div class="para"><p>generates</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> RemovePartNumberFromProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
remove_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
add_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>You are not limited to one magically generated column, for example</p></div>
<div class="para"><p><tt>ruby script/generate migration AddDetailsToProducts part_number:string price:decimal</tt></p></div>
<div class="para"><p>generates</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddDetailsToProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
add_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
add_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>price<span style="color: #990000">,</span> <span style="color: #990000">:</span>decimal
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
remove_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>price
remove_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>As always, what has been generated for you is just a starting point. You can add or remove from it as you see fit.</p></div>
</div>
<h2 id="_writing_a_migration">3. Writing a Migration</h2>
<div class="sectionbody">
<div class="para"><p>Once you have created your migration using one of the generators it's time to get to work!</p></div>
<h3 id="_creating_a_table">3.1. Creating a table</h3>
<div class="para"><p><tt>create_table</tt> will be one of your workhorses. A typical use would be</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>which creates a <tt>products</tt> table with a column called <tt>name</tt> (and as discussed below, an implicit <tt>id</tt> column).</p></div>
<div class="para"><p>The object yielded to the block allows you create columns on the table. There are two ways of doing this. The first looks like</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>column <span style="color: #990000">:</span>name<span style="color: #990000">,</span> <span style="color: #990000">:</span>string<span style="color: #990000">,</span> <span style="color: #990000">:</span>null <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>the second form, the so called "sexy" migrations, drops the somewhat redundant column method. Instead, the <tt>string</tt>, <tt>integer</tt> etc. methods create a column of that type. Subsequent parameters are identical.</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name<span style="color: #990000">,</span> <span style="color: #990000">:</span>null <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>By default <tt>create_table</tt> will create a primary key called <tt>id</tt>. You can change the name of the primary key with the <tt>:primary_key</tt> option (don't forget to update the corresponding model) or if you don't want a primary key at all (for example for a HABTM join table) you can pass <tt>:id &#8658; false</tt>. If you need to pass database specific options you can place an sql fragment in the <tt>:options</tt> option. For example</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>options <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"ENGINE=BLACKHOLE"</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name<span style="color: #990000">,</span> <span style="color: #990000">:</span>null <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>Will append <tt>ENGINE=BLACKHOLE</tt> to the sql used to create the table (when using MySQL the default is "ENGINE=InnoDB").</p></div>
<div class="para"><p>The types Active Record supports are <tt>:primary_key</tt>, <tt>:string</tt>, <tt>:text</tt>, <tt>:integer</tt>, <tt>:float</tt>, <tt>:decimal</tt>, <tt>:datetime</tt>, <tt>:timestamp</tt>, <tt>:time</tt>, <tt>:date</tt>, <tt>:binary</tt>, <tt>:boolean</tt>.</p></div>
<div class="para"><p>These will be mapped onto an appropriate underlying database type, for example with MySQL <tt>:string</tt> is mapped to <tt>VARCHAR(255)</tt>. You can create columns of
types not supported by Active Record when using the non sexy syntax, for example</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>column <span style="color: #990000">:</span>name<span style="color: #990000">,</span> <span style="color: #FF0000">'polygon'</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>null <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">false</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>This may however hinder portability to other databases.</p></div>
<h3 id="_changing_tables">3.2. Changing tables</h3>
<div class="para"><p><tt>create_table</tt>'s close cousin is <tt>change_table</tt>. Used for changing existing tables, it is used in a similar fashion to <tt>create_table</tt> but the object yielded to the block knows more tricks. For example</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>change_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>remove <span style="color: #990000">:</span>description<span style="color: #990000">,</span> <span style="color: #990000">:</span>name
t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>part_number
t<span style="color: #990000">.</span>index <span style="color: #990000">:</span>part_number
t<span style="color: #990000">.</span>rename <span style="color: #990000">:</span>upccode<span style="color: #990000">,</span> <span style="color: #990000">:</span>upc_code
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>removes the <tt>description</tt> column, creates a <tt>part_number</tt> column and adds an index on it. Finally it renames the <tt>upccode</tt> column. This is the same as doing</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>remove_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>description
remove_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>name
add_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
add_index <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number
rename_column <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>upccode<span style="color: #990000">,</span> <span style="color: #990000">:</span>upc_code
</tt></pre></div></div>
<div class="para"><p>You don't have to keep repeating the table name and it groups all the statements related to modifying one particular table. The individual transformation names are also shorter, for example <tt>remove_column</tt> becomes just <tt>remove</tt> and <tt>add_index</tt> becomes just <tt>index</tt>.</p></div>
<h3 id="_special_helpers">3.3. Special helpers</h3>
<div class="para"><p>Active Record provides some shortcuts for common functionality. It is for example very common to add both the <tt>created_at</tt> and <tt>updated_at</tt> columns and so there is a method that does exactly that:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>timestamps
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>will create a new products table with those two columns whereas</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>change_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>timestamps
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>adds those columns to an existing table.</p></div>
<div class="para"><p>The other helper is called <tt>references</tt> (also available as <tt>belongs_to</tt>). In its simplest form it just adds some readability</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>references <span style="color: #990000">:</span>category
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>will create a <tt>category_id</tt> column of the appropriate type. Note that you pass the model name, not the column name. Active Record adds the <tt>_id</tt> for you. If you have polymorphic belongs_to associations then <tt>references</tt> will add both of the columns required:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>references <span style="color: #990000">:</span>attachment<span style="color: #990000">,</span> <span style="color: #990000">:</span>polymorphic <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">{</span><span style="color: #990000">:</span>default <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">'Photo'</span><span style="color: #FF0000">}</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>will add an <tt>attachment_id</tt> column and a string <tt>attachment_type</tt> column with a default value of <em>Photo</em>.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
</td>
<td class="content">The <tt>references</tt> helper does not actually create foreign key constraints for you. You will need to use <tt>execute</tt> for that or a plugin that adds <a href="#foreign_key">foreign key support</a>.</td>
</tr></table>
</div>
<div class="para"><p>If the helpers provided by Active Record aren't enough you can use the <tt>execute</tt> function to execute arbitrary SQL.</p></div>
<div class="para"><p>For more details and examples of individual methods check the API documentation, in particular the documentation for <a href="http://api.rubyonrails.com/classes/ActiveRecord/ConnectionAdapters/SchemaStatements.html">ActiveRecord::ConnectionAdapters::SchemaStatements</a> (which provides the methods available in the <tt>up</tt> and <tt>down</tt> methods), <a href="http://api.rubyonrails.com/classes/ActiveRecord/ConnectionAdapters/TableDefinition.html">ActiveRecord::ConnectionAdapters::TableDefinition</a> (which provides the methods available on the object yielded by <tt>create_table</tt>) and <a href="http://api.rubyonrails.com/classes/ActiveRecord/ConnectionAdapters/Table.html">ActiveRecord::ConnectionAdapters::Table</a> (which provides the methods available on the object yielded by <tt>change_table</tt>).</p></div>
<h3 id="_writing_your_down_method">3.4. Writing your down method</h3>
<div class="para"><p>The <tt>down</tt> method of your migration should revert the transformations done by the <tt>up</tt> method. In other words the database should be unchanged if you do an <tt>up</tt> followed by a <tt>down</tt>. For example if you create a table in the up you should drop it in the <tt>down</tt> method. It is wise to do things in precisely the reverse order to in the <tt>up</tt> method. For example</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> ExampleMigration <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>references <span style="color: #990000">:</span>category
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-style: italic"><span style="color: #9A1900">#add a foreign key</span></span>
execute <span style="color: #FF0000">"ALTER TABLE products ADD CONSTRAINT fk_products_categories FOREIGN KEY (category_id) REFERENCES categories(id)"</span>
add_column <span style="color: #990000">:</span>users<span style="color: #990000">,</span> <span style="color: #990000">:</span>home_page_url<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
rename_column <span style="color: #990000">:</span>users<span style="color: #990000">,</span> <span style="color: #990000">:</span>email<span style="color: #990000">,</span> <span style="color: #990000">:</span>email_address
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
rename_column <span style="color: #990000">:</span>users<span style="color: #990000">,</span> <span style="color: #990000">:</span>email_address<span style="color: #990000">,</span> <span style="color: #990000">:</span>email
remove_column <span style="color: #990000">:</span>users<span style="color: #990000">,</span> <span style="color: #990000">:</span>home_page_url
execute <span style="color: #FF0000">"ALTER TABLE products DROP FOREIGN KEY fk_products_categories"</span>
drop_table <span style="color: #990000">:</span>products
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>Sometimes your migration will do something which is just plain irreversible, for example it might destroy some data. In cases like those when you can't reverse the migration you can raise IrreversibleMigration from your <tt>down</tt> method. If someone tries to revert your migration an error message will be
displayed saying that it can't be done.</p></div>
</div>
<h2 id="_running_migrations">4. Running Migrations</h2>
<div class="sectionbody">
<div class="para"><p>Rails provides a set of rake tasks to work with migrations which boils down to running certain sets of migrations. The very first migration related rake task you use will probably be <tt>db:migrate</tt>. In its most basic form it just runs the <tt>up</tt> method for all the migrations that have not yet been run. If there are no such migrations it exits.</p></div>
<div class="para"><p>If you specify a target version, Active Record will run the required migrations (up or down) until it has reached the specified version. The
version is the numerical prefix on the migration's filename. For example to migrate to version 20080906120000 run</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>rake db:migrate VERSION=20080906120000</tt></pre>
</div></div>
<div class="para"><p>If this is greater than the current version (i.e. it is migrating upwards) this will run the <tt>up</tt> method on all migrations up to and including 20080906120000, if migrating downwards this will run the <tt>down</tt> method on all the migrations down to, but not including, 20080906120000.</p></div>
<h3 id="_rolling_back">4.1. Rolling back</h3>
<div class="para"><p>A common task is to rollback the last migration, for example if you made a mistake in it and wish to correct it. Rather than tracking down the version number associated with the previous migration you can run</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>rake db:rollback</tt></pre>
</div></div>
<div class="para"><p>This will run the <tt>down</tt> method from the latest migration. If you need to undo several migrations you can provide a <tt>STEP</tt> parameter:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>rake db:rollback STEP=3</tt></pre>
</div></div>
<div class="para"><p>will run the <tt>down</tt> method fron the last 3 migrations.</p></div>
<div class="para"><p>The <tt>db:migrate:redo</tt> task is a shortcut for doing a rollback and then migrating back up again. As with the <tt>db:rollback</tt> task you can use the <tt>STEP</tt> parameter if you need to go more than one version back, for example</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>rake db:migrate:redo STEP=3</tt></pre>
</div></div>
<div class="para"><p>Neither of these Rake tasks do anything you could not do with <tt>db:migrate</tt>, they are simply more convenient since you do not need to explicitly specify the version to migrate to.</p></div>
<div class="para"><p>Lastly, the <tt>db:reset</tt> task will drop the database, recreate it and load the current schema into it.</p></div>
<div class="admonitionblock">
<table><tr>
<td class="icon">
<img src="/Users/lifo/Docs/docrails/railties/doc/guides/source/icons/note.png" alt="Note" />
</td>
<td class="content">This is not the same as running all the migrations - see the section on <a href="#schema">schema.rb</a>.</td>
</tr></table>
</div>
<h3 id="_being_specific">4.2. Being Specific</h3>
<div class="para"><p>If you need to run a specific migration up or down the <tt>db:migrate:up</tt> and <tt>db:migrate:down</tt> tasks will do that. Just specify the appropriate version and the corresponding migration will have its <tt>up</tt> or <tt>down</tt> method invoked, for example</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>rake db:migrate:up VERSION=20080906120000</tt></pre>
</div></div>
<div class="para"><p>will run the <tt>up</tt> method from the 20080906120000 migration. These tasks check whether the migration has already run, so for example <tt>db:migrate:up VERSION=20080906120000</tt> will do nothing if Active Record believes that 20080906120000 has already been run.</p></div>
<h3 id="_being_talkative">4.3. Being talkative</h3>
<div class="para"><p>By default migrations tell you exactly what they're doing and how long it took.
A migration creating a table and adding an index might produce output like this</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>== 20080906170109 CreateProducts: migrating ===================================
-- create_table(:products)
-&gt; 0.0021s
-- add_index(:products, :name)
-&gt; 0.0026s
== 20080906170109 CreateProducts: migrated (0.0059s) ==========================</tt></pre>
</div></div>
<div class="para"><p>Several methods are provided that allow you to control all this:</p></div>
<div class="ilist"><ul>
<li>
<p>
<tt>suppress_messages</tt> suppresses any output generated by its block
</p>
</li>
<li>
<p>
<tt>say</tt> outputs text (the second argument controls whether it is indented or not)
</p>
</li>
<li>
<p>
<tt>say_with_time</tt> outputs text along with how long it took to run its block. If the block returns an integer it assumes it is the number of rows affected.
</p>
</li>
</ul></div>
<div class="para"><p>For example, this migration</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> CreateProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
suppress_messages <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
create_table <span style="color: #990000">:</span>products <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #990000">:</span>name
t<span style="color: #990000">.</span>text <span style="color: #990000">:</span>description
t<span style="color: #990000">.</span>timestamps
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
say <span style="color: #FF0000">"Created a table"</span>
suppress_messages <span style="color: #FF0000">{</span>add_index <span style="color: #990000">:</span>products<span style="color: #990000">,</span> <span style="color: #990000">:</span>name<span style="color: #FF0000">}</span>
say <span style="color: #FF0000">"and an index!"</span><span style="color: #990000">,</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span>
say_with_time <span style="color: #FF0000">'Waiting for a while'</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
sleep <span style="color: #993399">10</span>
<span style="color: #993399">250</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
drop_table <span style="color: #990000">:</span>products
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>generates the following output</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>== 20080906170109 CreateProducts: migrating ===================================
-- Created a table
-&gt; and an index!
-- Waiting for a while
-&gt; 10.0001s
-&gt; 250 rows
== 20080906170109 CreateProducts: migrated (10.0097s) =========================</tt></pre>
</div></div>
<div class="para"><p>If you just want Active Record to shut up then running <tt>rake db:migrate VERBOSE=false</tt> will suppress any output.</p></div>
</div>
<h2 id="models">5. Using Models In Your Migrations</h2>
<div class="sectionbody">
<div class="para"><p>When creating or updating data in a migration it is often tempting to use one of your models. After all they exist to provide easy access to the underlying data. This can be done but some caution should be observed.</p></div>
<div class="para"><p>Consider for example a migration that uses the Product model to update a row in the corresponding table. Alice later updates the Product model, adding a new column and a validation on it. Bob comes back from holiday, updates the source and runs outstanding migrations with <tt>rake db:migrate</tt>, including the one that used the Product model. When the migration runs the source is up to date and so the Product model has the validation added by Alice. The database however is still old and so does not have that column and an error ensues because that validation is on a column that does not yet exist.</p></div>
<div class="para"><p>Frequently I just want to update rows in the database without writing out the SQL by hand: I'm not using anything specific to the model. One pattern for this is to define a copy of the model inside the migration itself, for example:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddPartNumberToProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Product <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
<span style="color: #990000">...</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
<span style="color: #990000">...</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>The migration has its own minimal copy of the Product model and no longer cares about the Product model defined in the application.</p></div>
<h3 id="_dealing_with_changing_models">5.1. Dealing with changing models</h3>
<div class="para"><p>For performance reasons information about the columns a model has is cached. For example if you add a column to a table and then try and use the corresponding model to insert a new row it may try and use the old column information. You can force Active Record to re-read the column information with the <tt>reset_column_information</tt> method, for example</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt><span style="font-weight: bold"><span style="color: #0000FF">class</span></span> AddPartNumberToProducts <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Migration
<span style="font-weight: bold"><span style="color: #0000FF">class</span></span> Product <span style="color: #990000">&lt;</span> ActiveRecord<span style="color: #990000">::</span>Base
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>up
add_column <span style="color: #990000">:</span>product<span style="color: #990000">,</span> <span style="color: #990000">:</span>part_number<span style="color: #990000">,</span> <span style="color: #990000">:</span>string
Product<span style="color: #990000">.</span>reset_column_information
<span style="color: #990000">...</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">def</span></span> <span style="font-weight: bold"><span style="color: #0000FF">self</span></span><span style="color: #990000">.</span>down
<span style="color: #990000">...</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
</div>
<h2 id="_schema_dumping_and_you">6. Schema dumping and you</h2>
<div class="sectionbody">
<h3 id="schema">6.1. What are schema files for?</h3>
<div class="para"><p>Migrations, mighty as they may be, are not the authoritative source for your database schema. That role falls to either <tt>schema.rb</tt> or an SQL file which Active Record generates by examining the database. They are not designed to be edited, they just represent the current state of the database.</p></div>
<div class="para"><p>There is no need (and it is error prone) to deploy a new instance of an app by replaying the entire migration history. It is much simpler and faster to just load into the database a description of the current schema.</p></div>
<div class="para"><p>For example, this is how the test database is created: the current development database is dumped (either to <tt>schema.rb</tt> or <tt>development.sql</tt>) and then loaded into the test database.</p></div>
<div class="para"><p>Schema files are also useful if want a quick look at what attributes an Active Record object has. This information is not in the model's code and is frequently spread across several migrations but is all summed up in the schema file. The <a href="http://agilewebdevelopment.com/plugins/annotate_models">annotate_models</a> plugin, which automatically adds (and updates) comments at the top of each model summarising the schema, may also be of interest.</p></div>
<h3 id="_types_of_schema_dumps">6.2. Types of schema dumps</h3>
<div class="para"><p>There are two ways to dump the schema. This is set in <tt>config/environment.rb</tt> by the <tt>config.active_record.schema_format</tt> setting, which may be either <tt>:sql</tt> or <tt>:ruby</tt>.</p></div>
<div class="para"><p>If <tt>:ruby</tt> is selected then the schema is stored in <tt>db/schema.rb</tt>. If you look at this file you'll find that it looks an awful lot like one very big migration:</p></div>
<div class="listingblock">
<div class="content"><!-- Generator: GNU source-highlight 2.9
by Lorenzo Bettini
http://www.lorenzobettini.it
http://www.gnu.org/software/src-highlite -->
<pre><tt>ActiveRecord<span style="color: #990000">::</span>Schema<span style="color: #990000">.</span>define<span style="color: #990000">(:</span>version <span style="color: #990000">=&gt;</span> <span style="color: #993399">20080906171750</span><span style="color: #990000">)</span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span>
create_table <span style="color: #FF0000">"authors"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>force <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #FF0000">"name"</span>
t<span style="color: #990000">.</span>datetime <span style="color: #FF0000">"created_at"</span>
t<span style="color: #990000">.</span>datetime <span style="color: #FF0000">"updated_at"</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
create_table <span style="color: #FF0000">"products"</span><span style="color: #990000">,</span> <span style="color: #990000">:</span>force <span style="color: #990000">=&gt;</span> <span style="font-weight: bold"><span style="color: #0000FF">true</span></span> <span style="font-weight: bold"><span style="color: #0000FF">do</span></span> <span style="color: #990000">|</span>t<span style="color: #990000">|</span>
t<span style="color: #990000">.</span>string <span style="color: #FF0000">"name"</span>
t<span style="color: #990000">.</span>text <span style="color: #FF0000">"description"</span>
t<span style="color: #990000">.</span>datetime <span style="color: #FF0000">"created_at"</span>
t<span style="color: #990000">.</span>datetime <span style="color: #FF0000">"updated_at"</span>
t<span style="color: #990000">.</span>string <span style="color: #FF0000">"part_number"</span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
<span style="font-weight: bold"><span style="color: #0000FF">end</span></span>
</tt></pre></div></div>
<div class="para"><p>In many ways this is exactly what it is. This file is created by inspecting the database and expressing its structure using <tt>create_table</tt>, <tt>add_index</tt> and so on. Because this is database independent it could be loaded into any database that Active Record supports. This could be very useful if you were to distribute an application that is able to run against multiple databases.</p></div>
<div class="para"><p>There is however a trade-off: <tt>schema.rb</tt> cannot express database specific items such as foreign key constraints, triggers or stored procedures. While in a migration you can execute custom SQL statements, the schema dumper cannot reconstitute those statements from the database. If you are using features like this then you should set the schema format to <tt>:sql</tt>.</p></div>
<div class="para"><p>Instead of using Active Record's schema dumper the database's structure will be dumped using a tool specific to that database (via the <tt>db:structure:dump</tt> Rake task) into <tt>db/#{RAILS_ENV}_structure.sql</tt>. For example for PostgreSQL the <tt>pg_dump</tt> utility is used and for MySQL this file will contain the output of SHOW CREATE TABLE for the various tables. Loading this schema is simply a question of executing the SQL statements contained inside.</p></div>
<div class="para"><p>By definition this will be a perfect copy of the database's structure but this will usually prevent loading the schema into a database other than the one used to create it.</p></div>
<h3 id="_schema_dumps_and_source_control">6.3. Schema dumps and source control</h3>
<div class="para"><p>Because they are the authoritative source for your database schema, it is strongly recommended that you check them into source control.</p></div>
</div>
<h2 id="foreign_key">7. Active Record and Referential Integrity</h2>
<div class="sectionbody">
<div class="para"><p>The Active Record way is that intelligence belongs in your models, not in the database. As such features such as triggers or foreign key constraints, which push some of that intelligence back into the database are not heavily used.</p></div>
<div class="para"><p>Validations such as <tt>validates_uniqueness_of</tt> are one way in which models can enforce data integrity. The <tt>:dependent</tt> option on associations allows models to automatically destroy child objects when the parent is destroyed. Like anything which operates at the application level these cannot guarantee referential integrity and so some people augment them with foreign key constraints.</p></div>
<div class="para"><p>Although Active Record does not provide any tools for working directly with such features, the <tt>execute</tt> method can be used to execute arbitrary SQL. There are also a number of plugins such as <a href="http://agilewebdevelopment.com/plugins/search?search=redhillonrails">redhillonrails</a> which add foreign key support to Active Record (including support for dumping foreign keys in <tt>schema.rb</tt>).</p></div>
</div>
<h2 id="_changelog">8. Changelog</h2>
<div class="sectionbody">
<div class="para"><p><a href="http://rails.lighthouseapp.com/projects/16213-rails-guides/tickets/6">Lighthouse ticket</a></p></div>
<div class="ilist"><ul>
<li>
<p>
September 14, 2008: initial version by <a href="../authors.html#fcheung">Frederick Cheung</a>
</p>
</li>
</ul></div>
</div>
</div>
</div>
</body>
</html>

2183
railties/doc/guides/html/routing_outside_in.html Normal file
View file

File diff suppressed because it is too large Load diff

1280
railties/doc/guides/html/security.html Normal file
View file

File diff suppressed because it is too large Load diff

1751
railties/doc/guides/html/testing_rails_applications.html Normal file
View file

File diff suppressed because it is too large Load diff

0
railties/doc/guides/actioncontroller/cookies.txt → railties/doc/guides/source/actioncontroller_basics/cookies.txt
View file

0
railties/doc/guides/actioncontroller/filters.txt → railties/doc/guides/source/actioncontroller_basics/filters.txt
View file

0
railties/doc/guides/actioncontroller/http_auth.txt → railties/doc/guides/source/actioncontroller_basics/http_auth.txt
View file

0
railties/doc/guides/actioncontroller/actioncontroller.txt → railties/doc/guides/source/actioncontroller_basics/index.txt
View file

0
railties/doc/guides/actioncontroller/introduction.txt → railties/doc/guides/source/actioncontroller_basics/introduction.txt
View file

0
railties/doc/guides/actioncontroller/methods.txt → railties/doc/guides/source/actioncontroller_basics/methods.txt
View file

0
railties/doc/guides/actioncontroller/parameter_filtering.txt → railties/doc/guides/source/actioncontroller_basics/parameter_filtering.txt
View file

0
railties/doc/guides/actioncontroller/params.txt → railties/doc/guides/source/actioncontroller_basics/params.txt
View file

0
railties/doc/guides/actioncontroller/request_response_objects.txt → railties/doc/guides/source/actioncontroller_basics/request_response_objects.txt
View file

0
railties/doc/guides/actioncontroller/rescue.txt → railties/doc/guides/source/actioncontroller_basics/rescue.txt
View file

0
railties/doc/guides/actioncontroller/session.txt → railties/doc/guides/source/actioncontroller_basics/session.txt
View file

0
railties/doc/guides/actioncontroller/streaming.txt → railties/doc/guides/source/actioncontroller_basics/streaming.txt
View file

0
railties/doc/guides/actioncontroller/verification.txt → railties/doc/guides/source/actioncontroller_basics/verification.txt
View file

0
railties/doc/guides/activerecord/active_record_basics.txt → railties/doc/guides/source/active_record_basics.txt
View file

0
railties/doc/guides/activerecord/association_basics.txt → railties/doc/guides/source/association_basics.txt
View file

0
railties/doc/guides/authors.txt → railties/doc/guides/source/authors.txt
View file

0
railties/doc/guides/benchmarking_and_profiling/appendix.txt → railties/doc/guides/source/benchmarking_and_profiling/appendix.txt
View file

0
railties/doc/guides/benchmarking_and_profiling/digging_deeper.txt → railties/doc/guides/source/benchmarking_and_profiling/digging_deeper.txt
View file

0
railties/doc/guides/benchmarking_and_profiling/edge_rails_features.txt → railties/doc/guides/source/benchmarking_and_profiling/edge_rails_features.txt
View file

0
railties/doc/guides/benchmarking_and_profiling/examples/graph.html → railties/doc/guides/source/benchmarking_and_profiling/examples/graph.html
View file

0
railties/doc/guides/benchmarking_and_profiling/gameplan.txt → railties/doc/guides/source/benchmarking_and_profiling/gameplan.txt
View file

0
railties/doc/guides/benchmarking_and_profiling/images/kgraph.png.html → railties/doc/guides/source/benchmarking_and_profiling/images/kgraph.png.html
View file

0
railties/doc/guides/benchmarking_and_profiling/images/klist.png.html → railties/doc/guides/source/benchmarking_and_profiling/images/klist.png.html
View file

0
railties/doc/guides/benchmarking_and_profiling/index.txt → railties/doc/guides/source/benchmarking_and_profiling/index.txt
View file

0
railties/doc/guides/benchmarking_and_profiling/rubyprof.txt → railties/doc/guides/source/benchmarking_and_profiling/rubyprof.txt
View file

0
railties/doc/guides/benchmarking_and_profiling/statistics.txt → railties/doc/guides/source/benchmarking_and_profiling/statistics.txt
View file

0
railties/doc/guides/caching/caching_with_rails.txt → railties/doc/guides/source/caching_with_rails.txt
View file

0
railties/doc/guides/creating_plugins/acts_as_yaffle.txt → railties/doc/guides/source/creating_plugins/acts_as_yaffle.txt
View file

0
railties/doc/guides/creating_plugins/appendix.txt → railties/doc/guides/source/creating_plugins/appendix.txt
View file

0
railties/doc/guides/creating_plugins/basics.markdown → railties/doc/guides/source/creating_plugins/basics.markdown
View file

0
railties/doc/guides/creating_plugins/custom_generator.txt → railties/doc/guides/source/creating_plugins/custom_generator.txt
View file

0
railties/doc/guides/creating_plugins/custom_route.txt → railties/doc/guides/source/creating_plugins/custom_route.txt
View file

0
railties/doc/guides/creating_plugins/creating_plugins.txt → railties/doc/guides/source/creating_plugins/index.txt
View file

0
railties/doc/guides/creating_plugins/migration_generator.txt → railties/doc/guides/source/creating_plugins/migration_generator.txt
View file

0
railties/doc/guides/creating_plugins/odds_and_ends.txt → railties/doc/guides/source/creating_plugins/odds_and_ends.txt
View file

0
railties/doc/guides/creating_plugins/preparation.txt → railties/doc/guides/source/creating_plugins/preparation.txt
View file

0
railties/doc/guides/creating_plugins/string_to_squawk.txt → railties/doc/guides/source/creating_plugins/string_to_squawk.txt
View file

0
railties/doc/guides/creating_plugins/view_helper.txt → railties/doc/guides/source/creating_plugins/view_helper.txt
View file

0
railties/doc/guides/debugging/debugging_rails_applications.txt → railties/doc/guides/source/debugging_rails_applications.txt
View file

0
railties/doc/guides/activerecord/finders.txt → railties/doc/guides/source/finders.txt
View file

0
railties/doc/guides/forms/form_helpers.txt → railties/doc/guides/source/form_helpers.txt
View file

0
railties/doc/guides/getting_started_with_rails/getting_started_with_rails.txt → railties/doc/guides/source/getting_started_with_rails.txt
View file

0
railties/doc/guides/icons/README → railties/doc/guides/source/icons/README
View file

0
railties/doc/guides/icons/callouts/1.png → railties/doc/guides/source/icons/callouts/1.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 329 B

After

Width:  |  Height:  |  Size: 329 B

0
railties/doc/guides/icons/callouts/10.png → railties/doc/guides/source/icons/callouts/10.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 361 B

After

Width:  |  Height:  |  Size: 361 B

0
railties/doc/guides/icons/callouts/11.png → railties/doc/guides/source/icons/callouts/11.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 565 B

After

Width:  |  Height:  |  Size: 565 B

0
railties/doc/guides/icons/callouts/12.png → railties/doc/guides/source/icons/callouts/12.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 617 B

After

Width:  |  Height:  |  Size: 617 B

0
railties/doc/guides/icons/callouts/13.png → railties/doc/guides/source/icons/callouts/13.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 623 B

After

Width:  |  Height:  |  Size: 623 B

0
railties/doc/guides/icons/callouts/14.png → railties/doc/guides/source/icons/callouts/14.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 411 B

After

Width:  |  Height:  |  Size: 411 B

0
railties/doc/guides/icons/callouts/15.png → railties/doc/guides/source/icons/callouts/15.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 640 B

After

Width:  |  Height:  |  Size: 640 B

0
railties/doc/guides/icons/callouts/2.png → railties/doc/guides/source/icons/callouts/2.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 353 B

After

Width:  |  Height:  |  Size: 353 B

0
railties/doc/guides/icons/callouts/3.png → railties/doc/guides/source/icons/callouts/3.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 350 B

After

Width:  |  Height:  |  Size: 350 B

0
railties/doc/guides/icons/callouts/4.png → railties/doc/guides/source/icons/callouts/4.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 345 B

After

Width:  |  Height:  |  Size: 345 B

0
railties/doc/guides/icons/callouts/5.png → railties/doc/guides/source/icons/callouts/5.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 348 B

After

Width:  |  Height:  |  Size: 348 B

0
railties/doc/guides/icons/callouts/6.png → railties/doc/guides/source/icons/callouts/6.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 355 B

After

Width:  |  Height:  |  Size: 355 B

0
railties/doc/guides/icons/callouts/7.png → railties/doc/guides/source/icons/callouts/7.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 344 B

After

Width:  |  Height:  |  Size: 344 B

0
railties/doc/guides/icons/callouts/8.png → railties/doc/guides/source/icons/callouts/8.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 357 B

After

Width:  |  Height:  |  Size: 357 B

0
railties/doc/guides/icons/callouts/9.png → railties/doc/guides/source/icons/callouts/9.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 357 B

After

Width:  |  Height:  |  Size: 357 B

0
railties/doc/guides/icons/caution.png → railties/doc/guides/source/icons/caution.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.5 KiB

After

Width:  |  Height:  |  Size: 2.5 KiB

0
railties/doc/guides/icons/example.png → railties/doc/guides/source/icons/example.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.3 KiB

After

Width:  |  Height:  |  Size: 2.3 KiB

0
railties/doc/guides/icons/home.png → railties/doc/guides/source/icons/home.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

0
railties/doc/guides/icons/important.png → railties/doc/guides/source/icons/important.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.6 KiB

After

Width:  |  Height:  |  Size: 2.6 KiB

0
railties/doc/guides/icons/next.png → railties/doc/guides/source/icons/next.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

0
railties/doc/guides/icons/note.png → railties/doc/guides/source/icons/note.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.7 KiB

After

Width:  |  Height:  |  Size: 2.7 KiB

0
railties/doc/guides/icons/prev.png → railties/doc/guides/source/icons/prev.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

0
railties/doc/guides/icons/tip.png → railties/doc/guides/source/icons/tip.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.5 KiB

After

Width:  |  Height:  |  Size: 2.5 KiB

0
railties/doc/guides/icons/up.png → railties/doc/guides/source/icons/up.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 1.3 KiB

After

Width:  |  Height:  |  Size: 1.3 KiB

0
railties/doc/guides/icons/warning.png → railties/doc/guides/source/icons/warning.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 2.8 KiB

After

Width:  |  Height:  |  Size: 2.8 KiB

0
railties/doc/guides/activerecord/images/belongs_to.png → railties/doc/guides/source/images/belongs_to.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 33 KiB

After

Width:  |  Height:  |  Size: 33 KiB

0
railties/doc/guides/securing_rails_applications/images/csrf.png → railties/doc/guides/source/images/csrf.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 41 KiB

After

Width:  |  Height:  |  Size: 41 KiB

0
railties/doc/guides/activerecord/images/habtm.png → railties/doc/guides/source/images/habtm.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 62 KiB

After

Width:  |  Height:  |  Size: 62 KiB

0
railties/doc/guides/activerecord/images/has_many.png → railties/doc/guides/source/images/has_many.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB

0
railties/doc/guides/activerecord/images/has_many_through.png → railties/doc/guides/source/images/has_many_through.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 98 KiB

After

Width:  |  Height:  |  Size: 98 KiB

0
railties/doc/guides/activerecord/images/has_one.png → railties/doc/guides/source/images/has_one.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 38 KiB

After

Width:  |  Height:  |  Size: 38 KiB

0
railties/doc/guides/activerecord/images/has_one_through.png → railties/doc/guides/source/images/has_one_through.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 90 KiB

After

Width:  |  Height:  |  Size: 90 KiB

0
railties/doc/guides/activerecord/images/polymorphic.png → railties/doc/guides/source/images/polymorphic.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 83 KiB

After

Width:  |  Height:  |  Size: 83 KiB

0
railties/doc/guides/securing_rails_applications/images/session_fixation.png → railties/doc/guides/source/images/session_fixation.png
View file

Side by side Swipe Overlay

Before

Width:  |  Height:  |  Size: 47 KiB

After

Width:  |  Height:  |  Size: 47 KiB

0
railties/doc/guides/index.txt → railties/doc/guides/source/index.txt
View file

0
railties/doc/guides/actionview/layouts_and_rendering.txt → railties/doc/guides/source/layouts_and_rendering.txt
View file

Some files were not shown because too many files have changed in this diff Show more