railties 3.1.1 → 3.1.2.rc1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (189) hide show
  1. data/CHANGELOG.md +2382 -0
  2. data/guides/output/2_2_release_notes.html +565 -0
  3. data/guides/output/2_3_release_notes.html +713 -0
  4. data/guides/output/3_0_release_notes.html +652 -0
  5. data/guides/output/3_1_release_notes.html +670 -0
  6. data/guides/output/action_controller_overview.html +925 -0
  7. data/guides/output/action_mailer_basics.html +658 -0
  8. data/guides/output/action_view_overview.html +1471 -0
  9. data/guides/output/active_model_basics.html +349 -0
  10. data/guides/output/active_record_basics.html +364 -0
  11. data/guides/output/active_record_querying.html +1272 -0
  12. data/guides/output/active_record_validations_callbacks.html +1292 -0
  13. data/guides/output/active_resource_basics.html +252 -0
  14. data/guides/output/active_support_core_extensions.html +3374 -0
  15. data/guides/output/ajax_on_rails.html +412 -0
  16. data/guides/output/api_documentation_guidelines.html +317 -0
  17. data/guides/output/asset_pipeline.html +691 -0
  18. data/guides/output/association_basics.html +1742 -0
  19. data/guides/output/caching_with_rails.html +533 -0
  20. data/guides/output/command_line.html +662 -0
  21. data/guides/output/configuring.html +811 -0
  22. data/guides/output/contribute.html +216 -0
  23. data/guides/output/contributing_to_ruby_on_rails.html +465 -0
  24. data/guides/output/credits.html +210 -0
  25. data/guides/output/debugging_rails_applications.html +791 -0
  26. data/guides/output/engines.html +673 -0
  27. data/guides/output/form_helpers.html +850 -0
  28. data/guides/output/generators.html +725 -0
  29. data/guides/output/getting_started.html +1980 -0
  30. data/guides/output/i18n.html +1054 -0
  31. data/guides/output/images/belongs_to.png +0 -0
  32. data/guides/output/images/book_icon.gif +0 -0
  33. data/guides/output/images/bullet.gif +0 -0
  34. data/guides/output/images/challenge.png +0 -0
  35. data/guides/output/images/chapters_icon.gif +0 -0
  36. data/guides/output/images/check_bullet.gif +0 -0
  37. data/guides/output/images/credits_pic_blank.gif +0 -0
  38. data/guides/output/images/csrf.png +0 -0
  39. data/guides/output/images/customized_error_messages.png +0 -0
  40. data/guides/output/images/edge_badge.png +0 -0
  41. data/guides/output/images/error_messages.png +0 -0
  42. data/guides/output/images/feature_tile.gif +0 -0
  43. data/guides/output/images/footer_tile.gif +0 -0
  44. data/guides/output/images/fxn.png +0 -0
  45. data/guides/output/images/grey_bullet.gif +0 -0
  46. data/guides/output/images/habtm.png +0 -0
  47. data/guides/output/images/has_many.png +0 -0
  48. data/guides/output/images/has_many_through.png +0 -0
  49. data/guides/output/images/has_one.png +0 -0
  50. data/guides/output/images/has_one_through.png +0 -0
  51. data/guides/output/images/header_backdrop.png +0 -0
  52. data/guides/output/images/header_tile.gif +0 -0
  53. data/guides/output/images/i18n/demo_html_safe.png +0 -0
  54. data/guides/output/images/i18n/demo_localized_pirate.png +0 -0
  55. data/guides/output/images/i18n/demo_translated_en.png +0 -0
  56. data/guides/output/images/i18n/demo_translated_pirate.png +0 -0
  57. data/guides/output/images/i18n/demo_translation_missing.png +0 -0
  58. data/guides/output/images/i18n/demo_untranslated.png +0 -0
  59. data/guides/output/images/icons/README +5 -0
  60. data/guides/output/images/icons/callouts/1.png +0 -0
  61. data/guides/output/images/icons/callouts/10.png +0 -0
  62. data/guides/output/images/icons/callouts/11.png +0 -0
  63. data/guides/output/images/icons/callouts/12.png +0 -0
  64. data/guides/output/images/icons/callouts/13.png +0 -0
  65. data/guides/output/images/icons/callouts/14.png +0 -0
  66. data/guides/output/images/icons/callouts/15.png +0 -0
  67. data/guides/output/images/icons/callouts/2.png +0 -0
  68. data/guides/output/images/icons/callouts/3.png +0 -0
  69. data/guides/output/images/icons/callouts/4.png +0 -0
  70. data/guides/output/images/icons/callouts/5.png +0 -0
  71. data/guides/output/images/icons/callouts/6.png +0 -0
  72. data/guides/output/images/icons/callouts/7.png +0 -0
  73. data/guides/output/images/icons/callouts/8.png +0 -0
  74. data/guides/output/images/icons/callouts/9.png +0 -0
  75. data/guides/output/images/icons/caution.png +0 -0
  76. data/guides/output/images/icons/example.png +0 -0
  77. data/guides/output/images/icons/home.png +0 -0
  78. data/guides/output/images/icons/important.png +0 -0
  79. data/guides/output/images/icons/next.png +0 -0
  80. data/guides/output/images/icons/note.png +0 -0
  81. data/guides/output/images/icons/prev.png +0 -0
  82. data/guides/output/images/icons/tip.png +0 -0
  83. data/guides/output/images/icons/up.png +0 -0
  84. data/guides/output/images/icons/warning.png +0 -0
  85. data/guides/output/images/jaimeiniesta.jpg +0 -0
  86. data/guides/output/images/nav_arrow.gif +0 -0
  87. data/guides/output/images/polymorphic.png +0 -0
  88. data/guides/output/images/posts_index.png +0 -0
  89. data/guides/output/images/radar.png +0 -0
  90. data/guides/output/images/rails_guides_logo.gif +0 -0
  91. data/guides/output/images/rails_logo_remix.gif +0 -0
  92. data/guides/output/images/rails_welcome.png +0 -0
  93. data/guides/output/images/session_fixation.png +0 -0
  94. data/guides/output/images/tab_grey.gif +0 -0
  95. data/guides/output/images/tab_info.gif +0 -0
  96. data/guides/output/images/tab_note.gif +0 -0
  97. data/guides/output/images/tab_red.gif +0 -0
  98. data/guides/output/images/tab_yellow.gif +0 -0
  99. data/guides/output/images/tab_yellow.png +0 -0
  100. data/guides/output/images/validation_error_messages.png +0 -0
  101. data/guides/output/images/vijaydev.jpg +0 -0
  102. data/guides/output/index.html +300 -0
  103. data/guides/output/initialization.html +1087 -0
  104. data/guides/output/javascripts/guides.js +7 -0
  105. data/guides/output/javascripts/syntaxhighlighter/shBrushAS3.js +59 -0
  106. data/guides/output/javascripts/syntaxhighlighter/shBrushAppleScript.js +75 -0
  107. data/guides/output/javascripts/syntaxhighlighter/shBrushBash.js +59 -0
  108. data/guides/output/javascripts/syntaxhighlighter/shBrushCSharp.js +65 -0
  109. data/guides/output/javascripts/syntaxhighlighter/shBrushColdFusion.js +100 -0
  110. data/guides/output/javascripts/syntaxhighlighter/shBrushCpp.js +97 -0
  111. data/guides/output/javascripts/syntaxhighlighter/shBrushCss.js +91 -0
  112. data/guides/output/javascripts/syntaxhighlighter/shBrushDelphi.js +55 -0
  113. data/guides/output/javascripts/syntaxhighlighter/shBrushDiff.js +41 -0
  114. data/guides/output/javascripts/syntaxhighlighter/shBrushErlang.js +52 -0
  115. data/guides/output/javascripts/syntaxhighlighter/shBrushGroovy.js +67 -0
  116. data/guides/output/javascripts/syntaxhighlighter/shBrushJScript.js +52 -0
  117. data/guides/output/javascripts/syntaxhighlighter/shBrushJava.js +57 -0
  118. data/guides/output/javascripts/syntaxhighlighter/shBrushJavaFX.js +58 -0
  119. data/guides/output/javascripts/syntaxhighlighter/shBrushPerl.js +72 -0
  120. data/guides/output/javascripts/syntaxhighlighter/shBrushPhp.js +88 -0
  121. data/guides/output/javascripts/syntaxhighlighter/shBrushPlain.js +33 -0
  122. data/guides/output/javascripts/syntaxhighlighter/shBrushPowerShell.js +74 -0
  123. data/guides/output/javascripts/syntaxhighlighter/shBrushPython.js +64 -0
  124. data/guides/output/javascripts/syntaxhighlighter/shBrushRuby.js +55 -0
  125. data/guides/output/javascripts/syntaxhighlighter/shBrushSass.js +94 -0
  126. data/guides/output/javascripts/syntaxhighlighter/shBrushScala.js +51 -0
  127. data/guides/output/javascripts/syntaxhighlighter/shBrushSql.js +66 -0
  128. data/guides/output/javascripts/syntaxhighlighter/shBrushVb.js +56 -0
  129. data/guides/output/javascripts/syntaxhighlighter/shBrushXml.js +69 -0
  130. data/guides/output/javascripts/syntaxhighlighter/shCore.js +17 -0
  131. data/guides/output/layout.html +312 -0
  132. data/guides/output/layouts_and_rendering.html +1257 -0
  133. data/guides/output/migrations.html +751 -0
  134. data/guides/output/nested_model_forms.html +350 -0
  135. data/guides/output/performance_testing.html +858 -0
  136. data/guides/output/plugins.html +590 -0
  137. data/guides/output/rails_application_templates.html +368 -0
  138. data/guides/output/rails_on_rack.html +408 -0
  139. data/guides/output/routing.html +1246 -0
  140. data/guides/output/ruby_on_rails_guides_guidelines.html +218 -0
  141. data/guides/output/security.html +968 -0
  142. data/guides/output/stylesheets/fixes.css +16 -0
  143. data/guides/output/stylesheets/main.css +445 -0
  144. data/guides/output/stylesheets/print.css +52 -0
  145. data/guides/output/stylesheets/reset.css +43 -0
  146. data/guides/output/stylesheets/style.css +13 -0
  147. data/guides/output/stylesheets/syntaxhighlighter/shCore.css +226 -0
  148. data/guides/output/stylesheets/syntaxhighlighter/shCoreDefault.css +328 -0
  149. data/guides/output/stylesheets/syntaxhighlighter/shCoreDjango.css +331 -0
  150. data/guides/output/stylesheets/syntaxhighlighter/shCoreEclipse.css +339 -0
  151. data/guides/output/stylesheets/syntaxhighlighter/shCoreEmacs.css +324 -0
  152. data/guides/output/stylesheets/syntaxhighlighter/shCoreFadeToGrey.css +328 -0
  153. data/guides/output/stylesheets/syntaxhighlighter/shCoreMDUltra.css +324 -0
  154. data/guides/output/stylesheets/syntaxhighlighter/shCoreMidnight.css +324 -0
  155. data/guides/output/stylesheets/syntaxhighlighter/shCoreRDark.css +324 -0
  156. data/guides/output/stylesheets/syntaxhighlighter/shThemeDefault.css +117 -0
  157. data/guides/output/stylesheets/syntaxhighlighter/shThemeDjango.css +120 -0
  158. data/guides/output/stylesheets/syntaxhighlighter/shThemeEclipse.css +128 -0
  159. data/guides/output/stylesheets/syntaxhighlighter/shThemeEmacs.css +113 -0
  160. data/guides/output/stylesheets/syntaxhighlighter/shThemeFadeToGrey.css +117 -0
  161. data/guides/output/stylesheets/syntaxhighlighter/shThemeMDUltra.css +113 -0
  162. data/guides/output/stylesheets/syntaxhighlighter/shThemeMidnight.css +113 -0
  163. data/guides/output/stylesheets/syntaxhighlighter/shThemeRDark.css +113 -0
  164. data/guides/output/stylesheets/syntaxhighlighter/shThemeRailsGuides.css +116 -0
  165. data/guides/output/testing.html +1182 -0
  166. data/guides/source/active_record_validations_callbacks.textile +3 -3
  167. data/guides/source/active_support_core_extensions.textile +2 -2
  168. data/guides/source/asset_pipeline.textile +7 -5
  169. data/guides/source/association_basics.textile +2 -4
  170. data/guides/source/command_line.textile +1 -1
  171. data/guides/source/configuring.textile +4 -2
  172. data/guides/source/contributing_to_ruby_on_rails.textile +6 -6
  173. data/guides/source/initialization.textile +2 -2
  174. data/guides/source/performance_testing.textile +1 -1
  175. data/guides/source/routing.textile +1 -1
  176. data/guides/source/security.textile +2 -2
  177. data/lib/rails/commands/server.rb +1 -1
  178. data/lib/rails/engine.rb +1 -1
  179. data/lib/rails/generators/app_base.rb +2 -1
  180. data/lib/rails/generators/base.rb +3 -3
  181. data/lib/rails/generators/rails/app/templates/gitignore +15 -5
  182. data/lib/rails/rack.rb +0 -1
  183. data/lib/rails/tasks/documentation.rake +7 -7
  184. data/lib/rails/tasks/misc.rake +0 -2
  185. data/lib/rails/test_unit/testing.rake +2 -0
  186. data/lib/rails/version.rb +2 -2
  187. metadata +495 -326
  188. data/CHANGELOG +0 -2371
  189. data/lib/rails/rack/content_length.rb +0 -38
@@ -0,0 +1,652 @@
1
+ <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
+
4
+ <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5
+ <head>
6
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
7
+
8
+ <title>Ruby on Rails Guides: Ruby on Rails 3.0 Release Notes</title>
9
+
10
+ <link rel="stylesheet" type="text/css" href="stylesheets/style.css" />
11
+ <link rel="stylesheet" type="text/css" href="stylesheets/print.css" media="print" />
12
+
13
+ <link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shCore.css" />
14
+ <link rel="stylesheet" type="text/css" href="stylesheets/syntaxhighlighter/shThemeRailsGuides.css" />
15
+
16
+ <link rel="stylesheet" type="text/css" href="stylesheets/fixes.css" />
17
+ </head>
18
+ <body class="guide">
19
+ <div id="topNav">
20
+ <div class="wrapper">
21
+ <strong>More at <a href="http://rubyonrails.org/">rubyonrails.org:</a> </strong>
22
+ <a href="http://rubyonrails.org/">Overview</a> |
23
+ <a href="http://rubyonrails.org/download">Download</a> |
24
+ <a href="http://rubyonrails.org/deploy">Deploy</a> |
25
+ <a href="https://github.com/rails/rails">Code</a> |
26
+ <a href="http://rubyonrails.org/screencasts">Screencasts</a> |
27
+ <a href="http://rubyonrails.org/documentation">Documentation</a> |
28
+ <a href="http://rubyonrails.org/ecosystem">Ecosystem</a> |
29
+ <a href="http://rubyonrails.org/community">Community</a> |
30
+ <a href="http://weblog.rubyonrails.org/">Blog</a>
31
+ </div>
32
+ </div>
33
+ <div id="header">
34
+ <div class="wrapper clearfix">
35
+ <h1><a href="index.html" title="Return to home page">Guides.rubyonrails.org</a></h1>
36
+ <p class="hide"><a href="#mainCol">Skip navigation</a>.</p>
37
+ <ul class="nav">
38
+ <li><a href="index.html">Home</a></li>
39
+ <li class="index"><a href="index.html" onclick="guideMenu(); return false;" id="guidesMenu">Guides Index</a>
40
+ <div id="guides" class="clearfix" style="display: none;">
41
+ <hr />
42
+ <dl class="L">
43
+ <dt>Start Here</dt>
44
+ <dd><a href="getting_started.html">Getting Started with Rails</a></dd>
45
+ <dt>Models</dt>
46
+ <dd><a href="migrations.html">Rails Database Migrations</a></dd>
47
+ <dd><a href="active_record_validations_callbacks.html">Active Record Validations and Callbacks</a></dd>
48
+ <dd><a href="association_basics.html">Active Record Associations</a></dd>
49
+ <dd><a href="active_record_querying.html">Active Record Query Interface</a></dd>
50
+ <dt>Views</dt>
51
+ <dd><a href="layouts_and_rendering.html">Layouts and Rendering in Rails</a></dd>
52
+ <dd><a href="form_helpers.html">Action View Form Helpers</a></dd>
53
+ <dt>Controllers</dt>
54
+ <dd><a href="action_controller_overview.html">Action Controller Overview</a></dd>
55
+ <dd><a href="routing.html">Rails Routing from the Outside In</a></dd>
56
+ </dl>
57
+ <dl class="R">
58
+ <dt>Digging Deeper</dt>
59
+ <dd><a href="active_support_core_extensions.html">Active Support Core Extensions</a></dd>
60
+ <dd><a href="i18n.html">Rails Internationalization API</a></dd>
61
+ <dd><a href="action_mailer_basics.html">Action Mailer Basics</a></dd>
62
+ <dd><a href="testing.html">Testing Rails Applications</a></dd>
63
+ <dd><a href="security.html">Securing Rails Applications</a></dd>
64
+ <dd><a href="debugging_rails_applications.html">Debugging Rails Applications</a></dd>
65
+ <dd><a href="performance_testing.html">Performance Testing Rails Applications</a></dd>
66
+ <dd><a href="configuring.html">Configuring Rails Applications</a></dd>
67
+ <dd><a href="command_line.html">Rails Command Line Tools and Rake Tasks</a></dd>
68
+ <dd><a href="caching_with_rails.html">Caching with Rails</a></dd>
69
+ <dd><a href="asset_pipeline.html">Asset Pipeline</a></dd>
70
+
71
+ <dt>Extending Rails</dt>
72
+ <dd><a href="plugins.html">The Basics of Creating Rails Plugins</a></dd>
73
+ <dd><a href="rails_on_rack.html">Rails on Rack</a></dd>
74
+ <dd><a href="generators.html">Creating and Customizing Rails Generators</a></dd>
75
+
76
+ <dt>Contributing to Ruby on Rails</dt>
77
+ <dd><a href="contributing_to_ruby_on_rails.html">Contributing to Ruby on Rails</a></dd>
78
+ <dd><a href="api_documentation_guidelines.html">API Documentation Guidelines</a></dd>
79
+ <dd><a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a></dd>
80
+
81
+ <dt>Release Notes</dt>
82
+ <dd><a href="3_1_release_notes.html">Ruby on Rails 3.1 Release Notes</a></dd>
83
+ <dd><a href="3_0_release_notes.html">Ruby on Rails 3.0 Release Notes</a></dd>
84
+ <dd><a href="2_3_release_notes.html">Ruby on Rails 2.3 Release Notes</a></dd>
85
+ <dd><a href="2_2_release_notes.html">Ruby on Rails 2.2 Release Notes</a></dd>
86
+ </dl>
87
+ </div>
88
+ </li>
89
+ <li><a href="contributing_to_ruby_on_rails.html">Contribute</a></li>
90
+ <li><a href="credits.html">Credits</a></li>
91
+ </ul>
92
+ </div>
93
+ </div>
94
+ <hr class="hide" />
95
+
96
+ <div id="feature">
97
+ <div class="wrapper">
98
+ <h2>Ruby on Rails 3.0 Release Notes</h2>
99
+ <p>Rails 3.0 is ponies and rainbows! It&#8217;s going to cook you dinner and fold your laundry. You&#8217;re going to wonder how life was ever possible before it arrived. It&#8217;s the Best Version of Rails We&#8217;ve Ever Done!</p>
100
+ <p>But seriously now, it&#8217;s really good stuff. There are all the good ideas brought over from when the Merb team joined the party and brought a focus on framework agnosticism, slimmer and faster internals, and a handful of tasty APIs. If you&#8217;re coming to Rails 3.0 from Merb 1.x, you should recognize lots. If you&#8217;re coming from Rails 2.x, you&#8217;re going to love it too.</p>
101
+ <p>Even if you don&#8217;t give a hoot about any of our internal cleanups, Rails 3.0 is going to delight. We have a bunch of new features and improved APIs. It&#8217;s never been a better time to be a Rails developer. Some of the highlights are:</p>
102
+ <ul>
103
+ <li>Brand new router with an emphasis on RESTful declarations</li>
104
+ <li>New Action Mailer <span class="caps">API</span> modeled after Action Controller (now without the agonizing pain of sending multipart messages!)</li>
105
+ <li>New Active Record chainable query language built on top of relational algebra</li>
106
+ <li>Unobtrusive JavaScript helpers with drivers for Prototype, jQuery, and more coming (end of inline JS)</li>
107
+ <li>Explicit dependency management with Bundler</li>
108
+ </ul>
109
+ <p>On top of all that, we&#8217;ve tried our best to deprecate the old APIs with nice warnings. That means that you can move your existing application to Rails 3 without immediately rewriting all your old code to the latest best practices.</p>
110
+ <p>These release notes cover the major upgrades, but don&#8217;t include every little bug fix and change. Rails 3.0 consists of almost 4,000 commits by more than 250 authors! If you want to see everything, check out the <a href="http://github.com/rails/rails/commits/master">list of commits</a> in the main Rails repository on GitHub.</p>
111
+
112
+ <div id="subCol">
113
+ <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
114
+ <ol class="chapters">
115
+ <li><a href="#upgrading-to-rails-3">Upgrading to Rails 3</a><ul><li><a href="#rails-3-requires-at-least-ruby-1-8-7">Rails 3 requires at least Ruby 1.8.7</a></li> <li><a href="#rails-application-object">Rails Application object</a></li> <li><a href="#script-replaced-by-script-rails">script/* replaced by script/rails</a></li> <li><a href="#dependencies-and-config-gem">Dependencies and config.gem</a></li> <li><a href="#upgrade-process">Upgrade Process</a></li></ul></li><li><a href="#creating-a-rails-3-0-application">Creating a Rails 3.0 application</a><ul><li><a href="#vendoring-gems">Vendoring Gems</a></li> <li><a href="#living-on-the-edge">Living on the Edge</a></li></ul></li><li><a href="#rails-architectural-changes">Rails Architectural Changes</a><ul><li><a href="#railties-restrung">Railties Restrung</a></li> <li><a href="#all-rails-core-components-are-decoupled">All Rails core components are decoupled</a></li> <li><a href="#active-model-abstraction">Active Model Abstraction</a></li> <li><a href="#controller-abstraction">Controller Abstraction</a></li> <li><a href="#arel-integration">Arel Integration</a></li> <li><a href="#mail-extraction">Mail Extraction</a></li></ul></li><li><a href="#documentation">Documentation</a></li><li><a href="#internationalization">Internationalization</a></li><li><a href="#railties">Railties</a></li><li><a href="#action-pack">Action Pack</a><ul><li><a href="#abstract-controller">Abstract Controller</a></li> <li><a href="#action-controller">Action Controller</a></li> <li><a href="#action-dispatch">Action Dispatch</a></li> <li><a href="#action-view">Action View</a></li></ul></li><li><a href="#active-model">Active Model</a><ul><li><a href="#orm-abstraction-and-action-pack-interface"><span class="caps">ORM</span> Abstraction and Action Pack Interface</a></li> <li><a href="#validations">Validations</a></li></ul></li><li><a href="#active-record">Active Record</a><ul><li><a href="#query-interface">Query Interface</a></li> <li><a href="#enhancements">Enhancements</a></li> <li><a href="#patches-and-deprecations">Patches and Deprecations</a></li></ul></li><li><a href="#active-resource">Active Resource</a></li><li><a href="#active-support">Active Support</a></li><li><a href="#action-mailer">Action Mailer</a></li><li><a href="#credits">Credits</a></li></ol></div>
116
+ </div>
117
+ </div>
118
+
119
+ <div id="container">
120
+ <div class="wrapper">
121
+ <div id="mainCol">
122
+ <p>To install Rails 3:</p>
123
+ <div class="code_container">
124
+ <pre class="brush: plain; gutter: false; toolbar: false">
125
+ # Use sudo if your setup requires it
126
+ $ gem install rails
127
+ </pre>
128
+ </div>
129
+ <h3 id="upgrading-to-rails-3">1 Upgrading to Rails 3</h3>
130
+ <p>If you&#8217;re upgrading an existing application, it&#8217;s a great idea to have good test coverage before going in. You should also first upgrade to Rails 2.3.5 and make sure your application still runs as expected before attempting to update to Rails 3. Then take heed of the following changes:</p>
131
+ <h4 id="rails-3-requires-at-least-ruby-1-8-7">1.1 Rails 3 requires at least Ruby 1.8.7</h4>
132
+ <p>Rails 3.0 requires Ruby 1.8.7 or higher. Support for all of the previous Ruby versions has been dropped officially and you should upgrade as early as possible. Rails 3.0 is also compatible with Ruby 1.9.2.</p>
133
+ <div class="info"><p>Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails 3.0. Ruby Enterprise Edition have these fixed since release 1.8.7-2010.02 though. On the 1.9 front, Ruby 1.9.1 is not usable because it outright segfaults on Rails 3.0, so if you want to use Rails 3 with 1.9.x jump on 1.9.2 for smooth sailing.</p></div>
134
+ <h4 id="rails-application-object">1.2 Rails Application object</h4>
135
+ <p>As part of the groundwork for supporting running multiple Rails applications in the same process, Rails 3 introduces the concept of an Application object. An application object holds all the application specific configurations and is very similar in nature to <tt>config/environment.rb</tt> from the previous versions of Rails.</p>
136
+ <p>Each Rails application now must have a corresponding application object. The application object is defined in <tt>config/application.rb</tt>. If you&#8217;re upgrading an existing application to Rails 3, you must add this file and move the appropriate configurations from <tt>config/environment.rb</tt> to <tt>config/application.rb</tt>.</p>
137
+ <h4 id="script-replaced-by-script-rails">1.3 script/* replaced by script/rails</h4>
138
+ <p>The new <tt>script/rails</tt> replaces all the scripts that used to be in the <tt>script</tt> directory. You do not run <tt>script/rails</tt> directly though, the <tt>rails</tt> command detects it is being invoked in the root of a Rails application and runs the script for you. Intended usage is:</p>
139
+ <div class="code_container">
140
+ <pre class="brush: plain; gutter: false; toolbar: false">
141
+ $ rails console # instead of script/console
142
+ $ rails g scaffold post title:string # instead of script/generate scaffold post title:string
143
+ </pre>
144
+ </div>
145
+ <p>Run <tt>rails &#8212;help</tt> for a list of all the options.</p>
146
+ <h4 id="dependencies-and-config-gem">1.4 Dependencies and config.gem</h4>
147
+ <p>The <tt>config.gem</tt> method is gone and has been replaced by using <tt>bundler</tt> and a <tt>Gemfile</tt>, see <a href="#vendoring-gems">Vendoring Gems</a> below.</p>
148
+ <h4 id="upgrade-process">1.5 Upgrade Process</h4>
149
+ <p>To help with the upgrade process, a plugin named <a href="http://github.com/rails/rails_upgrade">Rails Upgrade</a> has been created to automate part of it.</p>
150
+ <p>Simply install the plugin, then run <tt>rake rails:upgrade:check</tt> to check your app for pieces that need to be updated (with links to information on how to update them). It also offers a task to generate a <tt>Gemfile</tt> based on your current <tt>config.gem</tt> calls and a task to generate a new routes file from your current one. To get the plugin, simply run the following:</p>
151
+ <div class="code_container">
152
+ <pre class="brush: plain; gutter: false; toolbar: false">
153
+ $ ruby script/plugin install git://github.com/rails/rails_upgrade.git
154
+ </pre>
155
+ </div>
156
+ <p>You can see an example of how that works at <a href="http://omgbloglol.com/post/364624593/rails-upgrade-is-now-an-official-plugin">Rails Upgrade is now an Official Plugin</a></p>
157
+ <p>Aside from Rails Upgrade tool, if you need more help, there are people on <span class="caps">IRC</span> and <a href="http://groups.google.com/group/rubyonrails-talk">rubyonrails-talk</a> that are probably doing the same thing, possibly hitting the same issues. Be sure to blog your own experiences when upgrading so others can benefit from your knowledge!</p>
158
+ <p>More information &#8211; <a href="http://omgbloglol.com/post/353978923/the-path-to-rails-3-approaching-the-upgrade">The Path to Rails 3: Approaching the upgrade</a></p>
159
+ <h3 id="creating-a-rails-3-0-application">2 Creating a Rails 3.0 application</h3>
160
+ <div class="code_container">
161
+ <pre class="brush: plain; gutter: false; toolbar: false">
162
+ # You should have the 'rails' rubygem installed
163
+ $ rails new myapp
164
+ $ cd myapp
165
+ </pre>
166
+ </div>
167
+ <h4 id="vendoring-gems">2.1 Vendoring Gems</h4>
168
+ <p>Rails now uses a <tt>Gemfile</tt> in the application root to determine the gems you require for your application to start. This <tt>Gemfile</tt> is processed by the <a href="http://github.com/carlhuda/bundler">Bundler</a>, which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn&#8217;t depend on the system gems.</p>
169
+ <p>More information: &#8211; <a href="http://gembundler.com">bundler homepage</a></p>
170
+ <h4 id="living-on-the-edge">2.2 Living on the Edge</h4>
171
+ <p><tt>Bundler</tt> and <tt>Gemfile</tt> makes freezing your Rails application easy as pie with the new dedicated <tt>bundle</tt> command, so <tt>rake freeze</tt> is no longer relevant and has been dropped.</p>
172
+ <p>If you want to bundle straight from the Git repository, you can pass the <tt>--edge</tt> flag:</p>
173
+ <div class="code_container">
174
+ <pre class="brush: plain; gutter: false; toolbar: false">
175
+ $ rails new myapp --edge
176
+ </pre>
177
+ </div>
178
+ <p>If you have a local checkout of the Rails repository and want to generate an application using that, you can pass the <tt>--dev</tt> flag:</p>
179
+ <div class="code_container">
180
+ <pre class="brush: plain; gutter: false; toolbar: false">
181
+ $ ruby /path/to/rails/bin/rails new myapp --dev
182
+ </pre>
183
+ </div>
184
+ <h3 id="rails-architectural-changes">3 Rails Architectural Changes</h3>
185
+ <p>There are six major changes in the architecture of Rails.</p>
186
+ <h4 id="railties-restrung">3.1 Railties Restrung</h4>
187
+ <p>Railties was updated to provide a consistent plugin <span class="caps">API</span> for the entire Rails framework as well as a total rewrite of generators and the Rails bindings, the result is that developers can now hook into any significant stage of the generators and application framework in a consistent, defined manner.</p>
188
+ <h4 id="all-rails-core-components-are-decoupled">3.2 All Rails core components are decoupled</h4>
189
+ <p>With the merge of Merb and Rails, one of the big jobs was to remove the tight coupling between Rails core components. This has now been achieved, and all Rails core components are now using the same <span class="caps">API</span> that you can use for developing plugins. This means any plugin you make, or any core component replacement (like DataMapper or Sequel) can access all the functionality that the Rails core components have access to and extend and enhance at will.</p>
190
+ <p>More information: &#8211; <a href="http://yehudakatz.com/2009/07/19/rails-3-the-great-decoupling/">The Great Decoupling</a></p>
191
+ <h4 id="active-model-abstraction">3.3 Active Model Abstraction</h4>
192
+ <p>Part of decoupling the core components was extracting all ties to Active Record from Action Pack. This has now been completed. All new <span class="caps">ORM</span> plugins now just need to implement Active Model interfaces to work seamlessly with Action Pack.</p>
193
+ <p>More information: &#8211; <a href="http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/">Make Any Ruby Object Feel Like ActiveRecord</a></p>
194
+ <h4 id="controller-abstraction">3.4 Controller Abstraction</h4>
195
+ <p>Another big part of decoupling the core components was creating a base superclass that is separated from the notions of <span class="caps">HTTP</span> in order to handle rendering of views etc. This creation of <tt>AbstractController</tt> allowed <tt>ActionController</tt> and <tt>ActionMailer</tt> to be greatly simplified with common code removed from all these libraries and put into Abstract Controller.</p>
196
+ <p>More Information: &#8211; <a href="http://yehudakatz.com/2009/06/11/rails-edge-architecture/">Rails Edge Architecture</a></p>
197
+ <h4 id="arel-integration">3.5 Arel Integration</h4>
198
+ <p><a href="http://github.com/brynary/arel">Arel</a> (or Active Relation) has been taken on as the underpinnings of Active Record and is now required for Rails. Arel provides an <span class="caps">SQL</span> abstraction that simplifies out Active Record and provides the underpinnings for the relation functionality in Active Record.</p>
199
+ <p>More information: &#8211; <a href="http://magicscalingsprinkles.wordpress.com/2010/01/28/why-i-wrote-arel/">Why I wrote Arel</a>.</p>
200
+ <h4 id="mail-extraction">3.6 Mail Extraction</h4>
201
+ <p>Action Mailer ever since its beginnings has had monkey patches, pre parsers and even delivery and receiver agents, all in addition to having TMail vendored in the source tree. Version 3 changes that with all email message related functionality abstracted out to the <a href="http://github.com/mikel/mail">Mail</a> gem. This again reduces code duplication and helps create definable boundaries between Action Mailer and the email parser.</p>
202
+ <p>More information: &#8211; <a href="http://lindsaar.net/2010/1/26/new-actionmailer-api-in-rails-3">New Action Mailer <span class="caps">API</span> in Rails 3</a></p>
203
+ <h3 id="documentation">4 Documentation</h3>
204
+ <p>The documentation in the Rails tree is being updated with all the <span class="caps">API</span> changes, additionally, the <a href="http://edgeguides.rubyonrails.org/">Rails Edge Guides</a> are being updated one by one to reflect the changes in Rails 3.0. The guides at <a href="http://guides.rubyonrails.org/">guides.rubyonrails.org</a> however will continue to contain only the stable version of Rails (at this point, version 2.3.5, until 3.0 is released).</p>
205
+ <p>More Information: &#8211; <a href="http://weblog.rubyonrails.org/2009/1/15/rails-documentation-projects">Rails Documentation Projects</a>.</p>
206
+ <h3 id="internationalization">5 Internationalization</h3>
207
+ <p>A large amount of work has been done with I18n support in Rails 3, including the latest <a href="http://github.com/svenfuchs/i18n">I18n</a> gem supplying many speed improvements.</p>
208
+ <ul>
209
+ <li>I18n for any object &#8211; I18n behavior can be added to any object by including <tt>ActiveModel::Translation</tt> and <tt>ActiveModel::Validations</tt>. There is also an <tt>errors.messages</tt> fallback for translations.</li>
210
+ <li>Attributes can have default translations.</li>
211
+ <li>Form Submit Tags automatically pull the correct status (Create or Update) depending on the object status, and so pull the correct translation.</li>
212
+ <li>Labels with I18n also now work by just passing the attribute name.</li>
213
+ </ul>
214
+ <p>More Information: &#8211; <a href="http://blog.plataformatec.com.br/2010/02/rails-3-i18n-changes/">Rails 3 I18n changes</a></p>
215
+ <h3 id="railties">6 Railties</h3>
216
+ <p>With the decoupling of the main Rails frameworks, Railties got a huge overhaul so as to make linking up frameworks, engines or plugins as painless and extensible as possible:</p>
217
+ <ul>
218
+ <li>Each application now has its own name space, application is started with <tt>YourAppName.boot</tt> for example, makes interacting with other applications a lot easier.</li>
219
+ <li>Anything under <tt>Rails.root/app</tt> is now added to the load path, so you can make <tt>app/observers/user_observer.rb</tt> and Rails will load it without any modifications.</li>
220
+ <li>Rails 3.0 now provides a <tt>Rails.config</tt> object, which provides a central repository of all sorts of Rails wide configuration options.</li>
221
+ </ul>
222
+ <p>Application generation has received extra flags allowing you to skip the installation of test-unit, Active Record, Prototype and Git. Also a new <tt>&#8212;dev</tt> flag has been added which sets the application up with the <tt>Gemfile</tt> pointing to your Rails checkout (which is determined by the path to the <tt>rails</tt> binary). See <tt>rails &#8212;help</tt> for more info.</p>
223
+ <p>Railties generators got a huge amount of attention in Rails 3.0, basically:</p>
224
+ <ul>
225
+ <li>Generators were completely rewritten and are backwards incompatible.</li>
226
+ <li>Rails templates <span class="caps">API</span> and generators <span class="caps">API</span> were merged (they are the same as the former).</li>
227
+ <li>Generators are no longer loaded from special paths anymore, they are just found in the Ruby load path, so calling <tt>rails generate foo</tt> will look for <tt>generators/foo_generator</tt>.</li>
228
+ <li>New generators provide hooks, so any template engine, <span class="caps">ORM</span>, test framework can easily hook in.</li>
229
+ <li>New generators allow you to override the templates by placing a copy at <tt>Rails.root/lib/templates</tt>.</li>
230
+ <li><tt>Rails::Generators::TestCase</tt> is also supplied so you can create your own generators and test them.</li>
231
+ </ul>
232
+ <p>Also, the views generated by Railties generators had some overhaul:</p>
233
+ <ul>
234
+ <li>Views now use <tt>div</tt> tags instead of <tt>p</tt> tags.</li>
235
+ <li>Scaffolds generated now make use of <tt>_form</tt> partials, instead of duplicated code in the edit and new views.</li>
236
+ <li>Scaffold forms now use <tt>f.submit</tt> which returns &#8220;Create ModelName&#8221; or &#8220;Update ModelName&#8221; depending on the state of the object passed in.</li>
237
+ </ul>
238
+ <p>Finally a couple of enhancements were added to the rake tasks:</p>
239
+ <ul>
240
+ <li><tt>rake db:forward</tt> was added, allowing you to roll forward your migrations individually or in groups.</li>
241
+ <li><tt>rake routes <span class="caps">CONTROLLER</span>=x</tt> was added allowing you to just view the routes for one controller.</li>
242
+ </ul>
243
+ <p>Railties now deprecates:</p>
244
+ <ul>
245
+ <li><tt>RAILS_ROOT</tt> in favor of <tt>Rails.root</tt>,</li>
246
+ <li><tt>RAILS_ENV</tt> in favor of <tt>Rails.env</tt>, and</li>
247
+ <li><tt>RAILS_DEFAULT_LOGGER</tt> in favor of <tt>Rails.logger</tt>.</li>
248
+ </ul>
249
+ <p><tt><span class="caps">PLUGIN</span>/rails/tasks</tt>, and <tt><span class="caps">PLUGIN</span>/tasks</tt> are no longer loaded all tasks now must be in <tt><span class="caps">PLUGIN</span>/lib/tasks</tt>.</p>
250
+ <p>More information:</p>
251
+ <ul>
252
+ <li><a href="http://blog.plataformatec.com.br/2010/01/discovering-rails-3-generators">Discovering Rails 3 generators</a></li>
253
+ <li><a href="http://caffeinedd.com/guides/331-making-generators-for-rails-3-with-thor">Making Generators for Rails 3 with Thor</a></li>
254
+ <li><a href="http://litanyagainstfear.com/blog/2010/02/03/the-rails-module/" title="in Rails 3">The Rails Module</a></li>
255
+ </ul>
256
+ <h3 id="action-pack">7 Action Pack</h3>
257
+ <p>There have been significant internal and external changes in Action Pack.</p>
258
+ <h4 id="abstract-controller">7.1 Abstract Controller</h4>
259
+ <p>Abstract Controller pulls out the generic parts of Action Controller into a reusable module that any library can use to render templates, render partials, helpers, translations, logging, any part of the request response cycle. This abstraction allowed <tt>ActionMailer::Base</tt> to now just inherit from <tt>AbstractController</tt> and just wrap the Rails <span class="caps">DSL</span> onto the Mail gem.</p>
260
+ <p>It also provided an opportunity to clean up Action Controller, abstracting out what could to simplify the code.</p>
261
+ <p>Note however that Abstract Controller is not a user facing <span class="caps">API</span>, you will not run into it in your day to day use of Rails.</p>
262
+ <p>More Information: &#8211; <a href="http://yehudakatz.com/2009/06/11/rails-edge-architecture/">Rails Edge Architecture</a></p>
263
+ <h4 id="action-controller">7.2 Action Controller</h4>
264
+ <ul>
265
+ <li><tt>application_controller.rb</tt> now has <tt>protect_from_forgery</tt> on by default.</li>
266
+ <li>The <tt>cookie_verifier_secret</tt> has been deprecated and now instead it is assigned through <tt>Rails.application.config.cookie_secret</tt> and moved into its own file: <tt>config/initializers/cookie_verification_secret.rb</tt>.</li>
267
+ <li>The <tt>session_store</tt> was configured in <tt>ActionController::Base.session</tt>, and that is now moved to <tt>Rails.application.config.session_store</tt>. Defaults are set up in <tt>config/initializers/session_store.rb</tt>.</li>
268
+ <li><tt>cookies.secure</tt> allowing you to set encrypted values in cookies with <tt>cookie.secure[:key] =&gt; value</tt>.</li>
269
+ <li><tt>cookies.permanent</tt> allowing you to set permanent values in the cookie hash <tt>cookie.permanent[:key] =&gt; value</tt> that raise exceptions on signed values if verification failures.</li>
270
+ <li>You can now pass <tt>:notice =&gt; &#8216;This is a flash message&#8217;</tt> or <tt>:alert =&gt; &#8216;Something went wrong&#8217;</tt> to the <tt>format</tt> call inside a <tt>respond_to</tt> block. The <tt>flash[]</tt> hash still works as previously.</li>
271
+ <li><tt>respond_with</tt> method has now been added to your controllers simplifying the venerable <tt>format</tt> blocks.</li>
272
+ <li><tt>ActionController::Responder</tt> added allowing you flexibility in how your responses get generated.</li>
273
+ </ul>
274
+ <p>Deprecations:</p>
275
+ <ul>
276
+ <li><tt>filter_parameter_logging</tt> is deprecated in favor of <tt>config.filter_parameters &lt;&lt; :password</tt>.</li>
277
+ </ul>
278
+ <p>More Information:</p>
279
+ <ul>
280
+ <li><a href="http://www.engineyard.com/blog/2010/render-options-in-rails-3/">Render Options in Rails 3</a></li>
281
+ <li><a href="http://weblog.rubyonrails.org/2009/8/31/three-reasons-love-responder">Three reasons to love ActionController::Responder</a></li>
282
+ </ul>
283
+ <h4 id="action-dispatch">7.3 Action Dispatch</h4>
284
+ <p>Action Dispatch is new in Rails 3.0 and provides a new, cleaner implementation for routing.</p>
285
+ <ul>
286
+ <li>Big clean up and re-write of the router, the Rails router is now <tt>rack_mount</tt> with a Rails <span class="caps">DSL</span> on top, it is a stand alone piece of software.</li>
287
+ <li>Routes defined by each application are now name spaced within your Application module, that is:</li>
288
+ </ul>
289
+ <div class="code_container">
290
+ <pre class="brush: ruby; gutter: false; toolbar: false">
291
+ # Instead of:
292
+
293
+ ActionController::Routing::Routes.draw do |map|
294
+ map.resources :posts
295
+ end
296
+
297
+ # You do:
298
+
299
+ AppName::Application.routes do
300
+ resources :posts
301
+ end
302
+ </pre>
303
+ </div>
304
+ <ul>
305
+ <li>Added <tt>match</tt> method to the router, you can also pass any Rack application to the matched route.</li>
306
+ <li>Added <tt>constraints</tt> method to the router, allowing you to guard routers with defined constraints.</li>
307
+ <li>Added <tt>scope</tt> method to the router, allowing you to namespace routes for different languages or different actions, for example:</li>
308
+ </ul>
309
+ <div class="code_container">
310
+ <pre class="brush: ruby; gutter: false; toolbar: false">
311
+ scope 'es' do
312
+ resources :projects, :path_names =&gt; { :edit =&gt; 'cambiar' }, :path =&gt; 'proyecto'
313
+ end
314
+
315
+ # Gives you the edit action with /es/proyecto/1/cambiar
316
+ </pre>
317
+ </div>
318
+ <ul>
319
+ <li>Added <tt>root</tt> method to the router as a short cut for <tt>match &#8216;/&#8217;, :to =&gt; path</tt>.</li>
320
+ <li>You can pass optional segments into the match, for example <tt>match &#8220;/:controller(/:action(/:id))(.:format)&#8221;</tt>, each parenthesized segment is optional.</li>
321
+ <li>Routes can be expressed via blocks, for example you can call <tt>controller :home { match &#8216;/:action&#8217; }</tt>.</li>
322
+ </ul>
323
+ <div class="note"><p>The old style <tt>map</tt> commands still work as before with a backwards compatibility layer, however this will be removed in the 3.1 release.</p></div>
324
+ <p>Deprecations</p>
325
+ <ul>
326
+ <li>The catch all route for non-<span class="caps">REST</span> applications (<tt>/:controller/:action/:id</tt>) is now commented out.</li>
327
+ <li>Routes :path_prefix no longer exists and :name_prefix now automatically adds &#8220;_&#8221; at the end of the given value.</li>
328
+ </ul>
329
+ <p>More Information:</p>
330
+ <ul>
331
+ <li><a href="http://yehudakatz.com/2009/12/26/the-rails-3-router-rack-it-up/">The Rails 3 Router: Rack it Up</a></li>
332
+ <li><a href="http://rizwanreza.com/2009/12/20/revamped-routes-in-rails-3">Revamped Routes in Rails 3</a></li>
333
+ <li><a href="http://yehudakatz.com/2009/12/20/generic-actions-in-rails-3/">Generic Actions in Rails 3</a></li>
334
+ </ul>
335
+ <h4 id="action-view">7.4 Action View</h4>
336
+ <h5 id="unobtrusive-javascript">7.4.1 Unobtrusive JavaScript</h5>
337
+ <p>Major re-write was done in the Action View helpers, implementing Unobtrusive JavaScript (<span class="caps">UJS</span>) hooks and removing the old inline <span class="caps">AJAX</span> commands. This enables Rails to use any compliant <span class="caps">UJS</span> driver to implement the <span class="caps">UJS</span> hooks in the helpers.</p>
338
+ <p>What this means is that all previous <tt>remote_&lt;method&gt;</tt> helpers have been removed from Rails core and put into the <a href="http://github.com/rails/prototype_legacy_helper">Prototype Legacy Helper</a>. To get <span class="caps">UJS</span> hooks into your <span class="caps">HTML</span>, you now pass <tt>:remote =&gt; true</tt> instead. For example:</p>
339
+ <div class="code_container">
340
+ <pre class="brush: ruby; gutter: false; toolbar: false">
341
+ form_for @post, :remote =&gt; true
342
+ </pre>
343
+ </div>
344
+ <p>Produces:</p>
345
+ <div class="code_container">
346
+ <pre class="brush: xml; gutter: false; toolbar: false">
347
+ &lt;form action=&quot;http://host.com&quot; id=&quot;create-post&quot; method=&quot;post&quot; data-remote=&quot;true&quot;&gt;
348
+ </pre>
349
+ </div>
350
+ <h5 id="helpers-with-blocks">7.4.2 Helpers with Blocks</h5>
351
+ <p>Helpers like <tt>form_for</tt> or <tt>div_for</tt> that insert content from a block use <tt>&lt;%=</tt> now:</p>
352
+ <div class="code_container">
353
+ <pre class="brush: ruby; html-script: true; gutter: false; toolbar: false">
354
+ &lt;%= form_for @post do |f| %&gt;
355
+ ...
356
+ &lt;% end %&gt;
357
+ </pre>
358
+ </div>
359
+ <p>Your own helpers of that kind are expected to return a string, rather than appending to the output buffer by hand.</p>
360
+ <p>Helpers that do something else, like <tt>cache</tt> or <tt>content_for</tt>, are not affected by this change, they need <tt>&lt;%</tt> as before.</p>
361
+ <h5 id="other-changes">7.4.3 Other Changes</h5>
362
+ <ul>
363
+ <li>You no longer need to call <tt>h(string)</tt> to escape <span class="caps">HTML</span> output, it is on by default in all view templates. If you want the unescaped string, call <tt>raw(string)</tt>.</li>
364
+ <li>Helpers now output <span class="caps">HTML</span> 5 by default.</li>
365
+ <li>Form label helper now pulls values from I18n with a single value, so <tt>f.label :name</tt> will pull the <tt>:name</tt> translation.</li>
366
+ <li>I18n select label on should now be :en.helpers.select instead of :en.support.select.</li>
367
+ <li>You no longer need to place a minus sign at the end of a ruby interpolation inside an ERb template to remove the trailing carriage return in the <span class="caps">HTML</span> output.</li>
368
+ <li>Added <tt>grouped_collection_select</tt> helper to Action View.</li>
369
+ <li><tt>content_for?</tt> has been added allowing you to check for the existence of content in a view before rendering.</li>
370
+ <li>passing <tt>:value => nil</tt> to form helpers will set the field&#8217;s <tt>value</tt> attribute to nil as opposed to using the default value</li>
371
+ <li>passing <tt>:id => nil</tt> to form helpers will cause those fields to be rendered with no <tt>id</tt> attribute</li>
372
+ <li>passing <tt>:alt => nil</tt> to <tt>image_tag</tt> will cause the <tt>img</tt> tag to render with no <tt>alt</tt> attribute</li>
373
+ </ul>
374
+ <h3 id="active-model">8 Active Model</h3>
375
+ <p>Active Model is new in Rails 3.0. It provides an abstraction layer for any <span class="caps">ORM</span> libraries to use to interact with Rails by implementing an Active Model interface.</p>
376
+ <h4 id="orm-abstraction-and-action-pack-interface">8.1 <span class="caps">ORM</span> Abstraction and Action Pack Interface</h4>
377
+ <p>Part of decoupling the core components was extracting all ties to Active Record from Action Pack. This has now been completed. All new <span class="caps">ORM</span> plugins now just need to implement Active Model interfaces to work seamlessly with Action Pack.</p>
378
+ <p>More Information: &#8211; <a href="http://yehudakatz.com/2010/01/10/activemodel-make-any-ruby-object-feel-like-activerecord/">Make Any Ruby Object Feel Like ActiveRecord</a></p>
379
+ <h4 id="validations">8.2 Validations</h4>
380
+ <p>Validations have been moved from Active Record into Active Model, providing an interface to validations that works across <span class="caps">ORM</span> libraries in Rails 3.</p>
381
+ <ul>
382
+ <li>There is now a <tt>validates :attribute, options_hash</tt> shortcut method that allows you to pass options for all the validates class methods, you can pass more than one option to a validate method.</li>
383
+ <li>The <tt>validates</tt> method has the following options:
384
+ <ul>
385
+ <li><tt>:acceptance =&gt; Boolean</tt>.</li>
386
+ <li><tt>:confirmation =&gt; Boolean</tt>.</li>
387
+ <li><tt>:exclusion =&gt; { :in =&gt; Enumerable }</tt>.</li>
388
+ <li><tt>:inclusion =&gt; { :in =&gt; Enumerable }</tt>.</li>
389
+ <li><tt>:format =&gt; { :with =&gt; Regexp, :on =&gt; :create }</tt>.</li>
390
+ <li><tt>:length =&gt; { :maximum =&gt; Fixnum }</tt>.</li>
391
+ <li><tt>:numericality =&gt; Boolean</tt>.</li>
392
+ <li><tt>:presence =&gt; Boolean</tt>.</li>
393
+ <li><tt>:uniqueness =&gt; Boolean</tt>.</li>
394
+ </ul></li>
395
+ </ul>
396
+ <div class="note"><p>All the Rails version 2.3 style validation methods are still supported in Rails 3.0, the new validates method is designed as an additional aid in your model validations, not a replacement for the existing <span class="caps">API</span>.</p></div>
397
+ <p>You can also pass in a validator object, which you can then reuse between objects that use Active Model:</p>
398
+ <div class="code_container">
399
+ <pre class="brush: ruby; gutter: false; toolbar: false">
400
+ class TitleValidator &lt; ActiveModel::EachValidator
401
+ Titles = ['Mr.', 'Mrs.', 'Dr.']
402
+ def validate_each(record, attribute, value)
403
+ unless Titles.include?(value)
404
+ record.errors[attribute] &lt;&lt; 'must be a valid title'
405
+ end
406
+ end
407
+ end
408
+ </pre>
409
+ </div>
410
+ <div class="code_container">
411
+ <pre class="brush: ruby; gutter: false; toolbar: false">
412
+ class Person
413
+ include ActiveModel::Validations
414
+ attr_accessor :title
415
+ validates :title, :presence =&gt; true, :title =&gt; true
416
+ end
417
+
418
+ # Or for Active Record
419
+
420
+ class Person &lt; ActiveRecord::Base
421
+ validates :title, :presence =&gt; true, :title =&gt; true
422
+ end
423
+ </pre>
424
+ </div>
425
+ <p>There&#8217;s also support for introspection:</p>
426
+ <div class="code_container">
427
+ <pre class="brush: ruby; gutter: false; toolbar: false">
428
+ User.validators
429
+ User.validators_on(:login)
430
+ </pre>
431
+ </div>
432
+ <p>More Information:</p>
433
+ <ul>
434
+ <li><a href="http://thelucid.com/2010/01/08/sexy-validation-in-edge-rails-rails-3/">Sexy Validation in Rails 3</a></li>
435
+ <li><a href="http://lindsaar.net/2010/1/31/validates_rails_3_awesome_is_true">Rails 3 Validations Explained</a></li>
436
+ </ul>
437
+ <h3 id="active-record">9 Active Record</h3>
438
+ <p>Active Record received a lot of attention in Rails 3.0, including abstraction into Active Model, a full update to the Query interface using Arel, validation updates and many enhancements and fixes. All of the Rails 2.x <span class="caps">API</span> will be usable through a compatibility layer that will be supported until version 3.1.</p>
439
+ <h4 id="query-interface">9.1 Query Interface</h4>
440
+ <p>Active Record, through the use of Arel, now returns relations on its core methods. The existing <span class="caps">API</span> in Rails 2.3.x is still supported and will not be deprecated until Rails 3.1 and not removed until Rails 3.2, however, the new <span class="caps">API</span> provides the following new methods that all return relations allowing them to be chained together:</p>
441
+ <ul>
442
+ <li><tt>where</tt> &#8211; provides conditions on the relation, what gets returned.</li>
443
+ <li><tt>select</tt> &#8211; choose what attributes of the models you wish to have returned from the database.</li>
444
+ <li><tt>group</tt> &#8211; groups the relation on the attribute supplied.</li>
445
+ <li><tt>having</tt> &#8211; provides an expression limiting group relations (<span class="caps">GROUP</span> BY constraint).</li>
446
+ <li><tt>joins</tt> &#8211; joins the relation to another table.</li>
447
+ <li><tt>clause</tt> &#8211; provides an expression limiting join relations (<span class="caps">JOIN</span> constraint).</li>
448
+ <li><tt>includes</tt> &#8211; includes other relations pre-loaded.</li>
449
+ <li><tt>order</tt> &#8211; orders the relation based on the expression supplied.</li>
450
+ <li><tt>limit</tt> &#8211; limits the relation to the number of records specified.</li>
451
+ <li><tt>lock</tt> &#8211; locks the records returned from the table.</li>
452
+ <li><tt>readonly</tt> &#8211; returns an read only copy of the data.</li>
453
+ <li><tt>from</tt> &#8211; provides a way to select relationships from more than one table.</li>
454
+ <li><tt>scope</tt> &#8211; (previously <tt>named_scope</tt>) return relations and can be chained together with the other relation methods.</li>
455
+ <li><tt>with_scope</tt> &#8211; and <tt>with_exclusive_scope</tt> now also return relations and so can be chained.</li>
456
+ <li><tt>default_scope</tt> &#8211; also works with relations.</li>
457
+ </ul>
458
+ <p>More Information:</p>
459
+ <ul>
460
+ <li><a href="http://m.onkey.org/2010/1/22/active-record-query-interface">Active Record Query Interface</a></li>
461
+ <li><a href="http://hasmanyquestions.wordpress.com/2010/01/17/let-your-sql-growl-in-rails-3/">Let your <span class="caps">SQL</span> Growl in Rails 3</a></li>
462
+ </ul>
463
+ <h4 id="enhancements">9.2 Enhancements</h4>
464
+ <ul>
465
+ <li>Added <tt>:destroyed?</tt> to Active Record objects.</li>
466
+ <li>Added <tt>:inverse_of</tt> to Active Record associations allowing you to pull the instance of an already loaded association without hitting the database.</li>
467
+ </ul>
468
+ <h4 id="patches-and-deprecations">9.3 Patches and Deprecations</h4>
469
+ <p>Additionally, many fixes in the Active Record branch:</p>
470
+ <ul>
471
+ <li>SQLite 2 support has been dropped in favor of SQLite 3.</li>
472
+ <li>MySQL support for column order.</li>
473
+ <li>PostgreSQL adapter has had its <tt>TIME ZONE</tt> support fixed so it no longer inserts incorrect values.</li>
474
+ <li>Support multiple schemas in table names for PostgreSQL.</li>
475
+ <li>PostgreSQL support for the <span class="caps">XML</span> data type column.</li>
476
+ <li><tt>table_name</tt> is now cached.</li>
477
+ <li>A large amount of work done on the Oracle adapter as well with many bug fixes.</li>
478
+ </ul>
479
+ <p>As well as the following deprecations:</p>
480
+ <ul>
481
+ <li><tt>named_scope</tt> in an Active Record class is deprecated and has been renamed to just <tt>scope</tt>.</li>
482
+ <li>In <tt>scope</tt> methods, you should move to using the relation methods, instead of a <tt>:conditions =&gt; {}</tt> finder method, for example <tt>scope :since, lambda {|time| where(&#8220;created_at &gt; ?&#8221;, time) }</tt>.</li>
483
+ <li><tt>save(false)</tt> is deprecated, in favor of <tt>save(:validate =&gt; false)</tt>.</li>
484
+ <li>I18n error messages for ActiveRecord should be changed from :en.activerecord.errors.template to <tt>:en.errors.template</tt>.</li>
485
+ <li><tt>model.errors.on</tt> is deprecated in favor of <tt>model.errors[]</tt></li>
486
+ <li>validates_presence_of =&gt; validates&#8230; :presence =&gt; true</li>
487
+ <li><tt>ActiveRecord::Base.colorize_logging</tt> and <tt>config.active_record.colorize_logging</tt> are deprecated in favor of <tt>Rails::LogSubscriber.colorize_logging</tt> or <tt>config.colorize_logging</tt></li>
488
+ </ul>
489
+ <div class="note"><p>While an implementation of State Machine has been in Active Record edge for some months now, it has been removed from the Rails 3.0 release.</p></div>
490
+ <h3 id="active-resource">10 Active Resource</h3>
491
+ <p>Active Resource was also extracted out to Active Model allowing you to use Active Resource objects with Action Pack seamlessly.</p>
492
+ <ul>
493
+ <li>Added validations through Active Model.</li>
494
+ <li>Added observing hooks.</li>
495
+ <li><span class="caps">HTTP</span> proxy support.</li>
496
+ <li>Added support for digest authentication.</li>
497
+ <li>Moved model naming into Active Model.</li>
498
+ <li>Changed Active Resource attributes to a Hash with indifferent access.</li>
499
+ <li>Added <tt>first</tt>, <tt>last</tt> and <tt>all</tt> aliases for equivalent find scopes.</li>
500
+ <li><tt>find_every</tt> now does not return a <tt>ResourceNotFound</tt> error if nothing returned.</li>
501
+ <li>Added <tt>save!</tt> which raises <tt>ResourceInvalid</tt> unless the object is <tt>valid?</tt>.</li>
502
+ <li><tt>update_attribute</tt> and <tt>update_attributes</tt> added to Active Resource models.</li>
503
+ <li>Added <tt>exists?</tt>.</li>
504
+ <li>Renamed <tt>SchemaDefinition</tt> to <tt>Schema</tt> and <tt>define_schema</tt> to <tt>schema</tt>.</li>
505
+ <li>Use the <tt>format</tt> of Active Resources rather than the <tt>content-type</tt> of remote errors to load errors.</li>
506
+ <li>Use <tt>instance_eval</tt> for schema block.</li>
507
+ <li>Fix <tt>ActiveResource::ConnectionError#to_s</tt> when <tt>@response</tt> does not respond to #code or #message, handles Ruby 1.9 compatibility.</li>
508
+ <li>Add support for errors in <span class="caps">JSON</span> format.</li>
509
+ <li>Ensure <tt>load</tt> works with numeric arrays.</li>
510
+ <li>Recognizes a 410 response from remote resource as the resource has been deleted.</li>
511
+ <li>Add ability to set <span class="caps">SSL</span> options on Active Resource connections.</li>
512
+ <li>Setting connection timeout also affects <tt>Net::HTTP</tt> <tt>open_timeout</tt>.</li>
513
+ </ul>
514
+ <p>Deprecations:</p>
515
+ <ul>
516
+ <li><tt>save(false)</tt> is deprecated, in favor of <tt>save(:validate =&gt; false)</tt>.</li>
517
+ <li>Ruby 1.9.2: <tt><span class="caps">URI</span>.parse</tt> and <tt>.decode</tt> are deprecated and are no longer used in the library.</li>
518
+ </ul>
519
+ <h3 id="active-support">11 Active Support</h3>
520
+ <p>A large effort was made in Active Support to make it cherry pickable, that is, you no longer have to require the entire Active Support library to get pieces of it. This allows the various core components of Rails to run slimmer.</p>
521
+ <p>These are the main changes in Active Support:</p>
522
+ <ul>
523
+ <li>Large clean up of the library removing unused methods throughout.</li>
524
+ <li>Active Support no longer provides vendored versions of <a href="http://tzinfo.rubyforge.org/">TZInfo</a>, <a href="http://deveiate.org/projects/RMemCache/">Memcache Client</a> and <a href="http://builder.rubyforge.org/">Builder</a>, these are all included as dependencies and installed via the <tt>bundle install</tt> command.</li>
525
+ <li>Safe buffers are implemented in <tt>ActiveSupport::SafeBuffer</tt>.</li>
526
+ <li>Added <tt>Array.uniq_by</tt> and <tt>Array.uniq_by!</tt>.</li>
527
+ <li>Removed <tt>Array#rand</tt> and backported <tt>Array#sample</tt> from Ruby 1.9.</li>
528
+ <li>Fixed bug on <tt>TimeZone.seconds_to_utc_offset</tt> returning wrong value.</li>
529
+ <li>Added <tt>ActiveSupport::Notifications</tt> middleware.</li>
530
+ <li><tt>ActiveSupport.use_standard_json_time_format</tt> now defaults to true.</li>
531
+ <li><tt>ActiveSupport.escape_html_entities_in_json</tt> now defaults to false.</li>
532
+ <li><tt>Integer#multiple_of?</tt> accepts zero as an argument, returns false unless the receiver is zero.</li>
533
+ <li><tt>string.chars</tt> has been renamed to <tt>string.mb_chars</tt>.</li>
534
+ <li><tt>ActiveSupport::OrderedHash</tt> now can de-serialize through <span class="caps">YAML</span>.</li>
535
+ <li>Added <span class="caps">SAX</span>-based parser for XmlMini, using LibXML and Nokogiri.</li>
536
+ <li>Added <tt>Object#presence</tt> that returns the object if it&#8217;s <tt>#present?</tt> otherwise returns <tt>nil</tt>.</li>
537
+ <li>Added <tt>String#exclude?</tt> core extension that returns the inverse of <tt>#include?</tt>.</li>
538
+ <li>Added <tt>to_i</tt> to <tt>DateTime</tt> in <tt>ActiveSupport</tt> so <tt>to_yaml</tt> works correctly on models with <tt>DateTime</tt> attributes.</li>
539
+ <li>Added <tt>Enumerable#exclude?</tt> to bring parity to <tt>Enumerable#include?</tt> and avoid if <tt>!x.include?</tt>.</li>
540
+ <li>Switch to on-by-default <span class="caps">XSS</span> escaping for rails.</li>
541
+ <li>Support deep-merging in <tt>ActiveSupport::HashWithIndifferentAccess</tt>.</li>
542
+ <li><tt>Enumerable#sum</tt> now works will all enumerables, even if they don&#8217;t respond to <tt>:size</tt>.</li>
543
+ <li><tt>inspect</tt> on a zero length duration returns &#8216;0 seconds&#8217; instead of empty string.</li>
544
+ <li>Add <tt>element</tt> and <tt>collection</tt> to <tt>ModelName</tt>.</li>
545
+ <li><tt>String#to_time</tt> and <tt>String#to_datetime</tt> handle fractional seconds.</li>
546
+ <li>Added support to new callbacks for around filter object that respond to <tt>:before</tt> and <tt>:after</tt> used in before and after callbacks.</li>
547
+ <li>The <tt>ActiveSupport::OrderedHash#to_a</tt> method returns an ordered set of arrays. Matches Ruby 1.9&#8217;s <tt>Hash#to_a</tt>.</li>
548
+ <li><tt>MissingSourceFile</tt> exists as a constant but it is now just equals to <tt>LoadError</tt>.</li>
549
+ <li>Added <tt>Class#class_attribute</tt>, to be able to declare a class-level attribute whose value is inheritable and overwritable by subclasses.</li>
550
+ <li>Finally removed <tt>DeprecatedCallbacks</tt> in <tt>ActiveRecord::Associations</tt>.</li>
551
+ <li><tt>Object#metaclass</tt> is now <tt>Kernel#singleton_class</tt> to match Ruby.</li>
552
+ </ul>
553
+ <p>The following methods have been removed because they are now available in Ruby 1.8.7 and 1.9.</p>
554
+ <ul>
555
+ <li><tt>Integer#even?</tt> and <tt>Integer#odd?</tt></li>
556
+ <li><tt>String#each_char</tt></li>
557
+ <li><tt>String#start_with?</tt> and <tt>String#end_with?</tt> (3rd person aliases still kept)</li>
558
+ <li><tt>String#bytesize</tt></li>
559
+ <li><tt>Object#tap</tt></li>
560
+ <li><tt>Symbol#to_proc</tt></li>
561
+ <li><tt>Object#instance_variable_defined?</tt></li>
562
+ <li><tt>Enumerable#none?</tt></li>
563
+ </ul>
564
+ <p>The security patch for <span class="caps">REXML</span> remains in Active Support because early patch-levels of Ruby 1.8.7 still need it. Active Support knows whether it has to apply it or not.</p>
565
+ <p>The following methods have been removed because they are no longer used in the framework:</p>
566
+ <ul>
567
+ <li><tt>Kernel#daemonize</tt></li>
568
+ <li><tt>Object#remove_subclasses_of</tt> <tt>Object#extend_with_included_modules_from</tt>, <tt>Object#extended_by</tt></li>
569
+ <li><tt>Class#remove_class</tt></li>
570
+ <li><tt>Regexp#number_of_captures</tt>, <tt>Regexp.unoptionalize</tt>, <tt>Regexp.optionalize</tt>, <tt>Regexp#number_of_captures</tt></li>
571
+ </ul>
572
+ <h3 id="action-mailer">12 Action Mailer</h3>
573
+ <p>Action Mailer has been given a new <span class="caps">API</span> with TMail being replaced out with the new <a href="http://github.com/mikel/mail">Mail</a> as the Email library. Action Mailer itself has been given an almost complete re-write with pretty much every line of code touched. The result is that Action Mailer now simply inherits from Abstract Controller and wraps the Mail gem in a Rails <span class="caps">DSL</span>. This reduces the amount of code and duplication of other libraries in Action Mailer considerably.</p>
574
+ <ul>
575
+ <li>All mailers are now in <tt>app/mailers</tt> by default.</li>
576
+ <li>Can now send email using new <span class="caps">API</span> with three methods: <tt>attachments</tt>, <tt>headers</tt> and <tt>mail</tt>.</li>
577
+ <li>ActionMailer now has native support for inline attachments using the <tt>attachments.inline</tt> method.</li>
578
+ <li>Action Mailer emailing methods now return <tt>Mail::Message</tt> objects, which can then be sent the <tt>deliver</tt> message to send itself.</li>
579
+ <li>All delivery methods are now abstracted out to the Mail gem.</li>
580
+ <li>The mail delivery method can accept a hash of all valid mail header fields with their value pair.</li>
581
+ <li>The <tt>mail</tt> delivery method acts in a similar way to Action Controller&#8217;s <tt>respond_to</tt>, and you can explicitly or implicitly render templates. Action Mailer will turn the email into a multipart email as needed.</li>
582
+ <li>You can pass a proc to the <tt>format.mime_type</tt> calls within the mail block and explicitly render specific types of text, or add layouts or different templates. The <tt>render</tt> call inside the proc is from Abstract Controller and supports the same options.</li>
583
+ <li>What were mailer unit tests have been moved to functional tests.</li>
584
+ <li>Action Mailer now delegates all auto encoding of header fields and bodies to Mail Gem</li>
585
+ <li>Action Mailer will auto encode email bodies and headers for you</li>
586
+ </ul>
587
+ <p>Deprecations:</p>
588
+ <ul>
589
+ <li><tt>:charset</tt>, <tt>:content_type</tt>, <tt>:mime_version</tt>, <tt>:implicit_parts_order</tt> are all deprecated in favor of <tt>ActionMailer.default :key =&gt; value</tt> style declarations.</li>
590
+ <li>Mailer dynamic <tt>create_method_name</tt> and <tt>deliver_method_name</tt> are deprecated, just call <tt>method_name</tt> which now returns a <tt>Mail::Message</tt> object.</li>
591
+ <li><tt>ActionMailer.deliver(message)</tt> is deprecated, just call <tt>message.deliver</tt>.</li>
592
+ <li><tt>template_root</tt> is deprecated, pass options to a render call inside a proc from the <tt>format.mime_type</tt> method inside the <tt>mail</tt> generation block</li>
593
+ <li>The <tt>body</tt> method to define instance variables is deprecated (<tt>body {:ivar =&gt; value}</tt>), just declare instance variables in the method directly and they will be available in the view.</li>
594
+ <li>Mailers being in <tt>app/models</tt> is deprecated, use <tt>app/mailers</tt> instead.</li>
595
+ </ul>
596
+ <p>More Information:</p>
597
+ <ul>
598
+ <li><a href="http://lindsaar.net/2010/1/26/new-actionmailer-api-in-rails-3">New Action Mailer <span class="caps">API</span> in Rails 3</a></li>
599
+ <li><a href="http://lindsaar.net/2010/1/23/mail-gem-version-2-released">New Mail Gem for Ruby</a></li>
600
+ </ul>
601
+ <h3 id="credits">13 Credits</h3>
602
+ <p>See the <a href="http://contributors.rubyonrails.org/">full list of contributors to Rails</a> for the many people who spent many hours making Rails 3. Kudos to all of them.</p>
603
+ <p>Rails 3.0 Release Notes were compiled by <a href="http://lindsaar.net">Mikel Lindsaar</a>.</p>
604
+
605
+ <h3>Feedback</h3>
606
+ <p>
607
+ You're encouraged to help improve the quality of this guide.
608
+ </p>
609
+ <p>
610
+ If you see any typos or factual errors you are confident to
611
+ patch, please clone <a href="https://github.com/lifo/docrails">docrails</a>
612
+ and push the change yourself. That branch of Rails has public write access.
613
+ Commits are still reviewed, but that happens after you've submitted your
614
+ contribution. <a href="https://github.com/lifo/docrails">docrails</a> is
615
+ cross-merged with master periodically.
616
+ </p>
617
+ <p>
618
+ You may also find incomplete content, or stuff that is not up to date.
619
+ Please do add any missing documentation for master. Check the
620
+ <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a>
621
+ for style and conventions.
622
+ </p>
623
+ <p>
624
+ If for whatever reason you spot something to fix but cannot patch it yourself, please
625
+ <a href="https://github.com/rails/rails/issues">open an issue</a>.
626
+ </p>
627
+ <p>And last but not least, any kind of discussion regarding Ruby on Rails
628
+ documentation is very welcome in the <a href="http://groups.google.com/group/rubyonrails-docs">rubyonrails-docs mailing list</a>.
629
+ </p>
630
+ </div>
631
+ </div>
632
+ </div>
633
+
634
+ <hr class="hide" />
635
+ <div id="footer">
636
+ <div class="wrapper">
637
+ <p>This work is licensed under a <a href="http://creativecommons.org/licenses/by-sa/3.0/">Creative Commons Attribution-Share Alike 3.0</a> License</p>
638
+ <p>"Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved.</p>
639
+ </div>
640
+ </div>
641
+
642
+ <script type="text/javascript" src="javascripts/guides.js"></script>
643
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shCore.js"></script>
644
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushRuby.js"></script>
645
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushXml.js"></script>
646
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushSql.js"></script>
647
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushPlain.js"></script>
648
+ <script type="text/javascript">
649
+ SyntaxHighlighter.all()
650
+ </script>
651
+ </body>
652
+ </html>