-
Notifications
You must be signed in to change notification settings - Fork 0
/
3_1_release_notes.html
773 lines (708 loc) · 47.2 KB
/
3_1_release_notes.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
<!DOCTYPE html>
<html lang="zh-TW">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Ruby on Rails 3.1 Release Notes — Ruby on Rails 指南</title>
<meta name="description" content="Ruby on Rails 指南：系統學習 Rails（Rails 4.2 版本）" >
<meta name="keywords" content="Ruby on Rails Guides 指南 中文 學習 免費 網路 Web 開發" >
<meta name="author" content="http://git.io/G_R1sA">
<meta property="fb:admins" content="1340181291">
<meta property="og:title" content="Ruby on Rails 3.1 Release Notes — Ruby on Rails 指南" >
<meta property="og:site_name" content="Ruby on Rails 指南">
<meta property="og:image" content="http://rails.ruby.tw/images/rails_guides_cover.jpg">
<meta property="og:url" content="http://rails.ruby.tw/">
<meta property="og:type" content="article">
<meta property="og:description" content="Ruby on Rails 指南：系統學習 Rails（Rails 4.2 版本）">
<link rel="stylesheet" href="stylesheets/application.css">
<link href="http://fonts.googleapis.com/css?family=Noto+Sans:400,700|Noto+Serif:700|Source+Code+Pro" rel="stylesheet">
<link href="images/favicon.ico" rel="shortcut icon" type="image/x-icon">
</head>
<body class="guide">
<div id="fb-root"></div>
<script>(function(d, s, id) {
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) return;
js = d.createElement(s); js.id = id;
js.src = "//connect.facebook.net/zh-TW/sdk.js#xfbml=1&appId=837401439623727&version=v2.0";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));</script>
<script type="text/javascript">
window.twttr=(function(d,s,id){var t,js,fjs=d.getElementsByTagName(s)[0];if(d.getElementById(id)){return}js=d.createElement(s);js.id=id;js.src="https://platform.twitter.com/widgets.js";fjs.parentNode.insertBefore(js,fjs);return window.twttr||(t={_e:[],ready:function(f){t._e.push(f)}})}(document,"script","twitter-wjs"));
</script>
<div id="topNav">
<div class="wrapper">
<strong class="more-info-label">更多內容 <a href="http://rubyonrails.org/">rubyonrails.org:</a></strong>
<span class="red-button more-info-button">
更多內容
</span>
<ul class="more-info-links s-hidden">
<li class="more-info"><a href="http://rubyonrails.org/">綜覽</a></li>
<li class="more-info"><a href="http://rubyonrails.org/download">下載</a></li>
<li class="more-info"><a href="http://rubyonrails.org/deploy">部署</a></li>
<li class="more-info"><a href="https://github.com/rails/rails">原始碼</a></li>
<li class="more-info"><a href="http://rubyonrails.org/screencasts">影片</a></li>
<li class="more-info"><a href="http://rubyonrails.org/documentation">文件</a></li>
<li class="more-info"><a href="http://rubyonrails.org/community">社群</a></li>
<li class="more-info"><a href="http://weblog.rubyonrails.org/">Blog</a></li>
</ul>
</div>
</div>
<div id="header">
<div class="wrapper clearfix">
<h1><a href="index.html" title="回首頁">Guides.rubyonrails.org</a></h1>
<ul class="nav">
<li><a class="nav-item" href="index.html">首頁</a></li>
<li class="guides-index guides-index-large">
<a href="index.html" id="guidesMenu" class="guides-index-item nav-item">指南目錄</a>
<div id="guides" class="clearfix" style="display: none;">
<hr>
<dl class="L">
<dt>起步走</dt>
<dd><a href="getting_started.html">Rails 起步走</a></dd>
<dt>Models</dt>
<dd><a href="active_record_basics.html">Active Record 基礎</a></dd>
<dd><a href="active_record_migrations.html">Active Record 遷移</a></dd>
<dd><a href="active_record_validations.html">Active Record 驗證</a></dd>
<dd><a href="active_record_callbacks.html">Active Record 回呼</a></dd>
<dd><a href="association_basics.html">Active Record 關聯</a></dd>
<dd><a href="active_record_querying.html">Active Record 查詢</a></dd>
<dt>Views</dt>
<dd><a href="layouts_and_rendering.html">Rails 算繪與版型</a></dd>
<dd><a href="form_helpers.html">Action View 表單輔助方法</a></dd>
<dt>Controllers</dt>
<dd><a href="action_controller_overview.html">Action Controller 綜覽</a></dd>
<dd><a href="routing.html">Rails 路由：深入淺出</a></dd>
</dl>
<dl class="R">
<dt>深入了解</dt>
<dd><a href="active_support_core_extensions.html">Active Support 核心擴展</a></dd>
<dd><a href="i18n.html">Rails 國際化 API</a></dd>
<dd><a href="action_mailer_basics.html">Action Mailer 基礎</a></dd>
<dd><a href="active_job_basics.html">Active Job 基礎</a></dd>
<dd><a href="security.html">Rails 安全指南</a></dd>
<dd><a href="debugging_rails_applications.html">除錯 Rails 應用程式</a></dd>
<dd><a href="configuring.html">Rails 應用程式設定</a></dd>
<dd><a href="command_line.html">Rake 任務與 Rails 命令列工具</a></dd>
<dd><a href="asset_pipeline.html">Asset Pipeline</a></dd>
<dd><a href="working_with_javascript_in_rails.html">在 Rails 使用 JavaScript</a></dd>
<dd><a href="constant_autoloading_and_reloading.html">Constant Autoloading and Reloading</a></dd>
<dt>擴充 Rails</dt>
<dd><a href="rails_on_rack.html">Rails on Rack</a></dd>
<dd><a href="generators.html">客製與新建 Rails 產生器</a></dd>
<dd><a href="rails_application_templates.html">Rails 應用程式模版</a></dd>
<dt>貢獻 Ruby on Rails</dt>
<dd><a href="contributing_to_ruby_on_rails.html">貢獻 Ruby on Rails</a></dd>
<dd><a href="api_documentation_guidelines.html">API 文件準則</a></dd>
<dd><a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南準則</a></dd>
<dt>維護方針</dt>
<dd><a href="maintenance_policy.html">維護方針</a></dd>
<dt>發佈記</dt>
<dd><a href="upgrading_ruby_on_rails.html">升級 Ruby on Rails</a></dd>
<dd><a href="4_2_release_notes.html">Ruby on Rails 4.2 發佈記</a></dd>
<dd><a href="4_1_release_notes.html">Ruby on Rails 4.1 發佈記</a></dd>
<dd><a href="4_0_release_notes.html">Ruby on Rails 4.0 發佈記</a></dd>
<dd><a href="3_2_release_notes.html">Ruby on Rails 3.2 發佈記</a></dd>
<dd><a href="3_1_release_notes.html">Ruby on Rails 3.1 發佈記</a></dd>
<dd><a href="3_0_release_notes.html">Ruby on Rails 3.0 發佈記</a></dd>
<dd><a href="2_3_release_notes.html">Ruby on Rails 2.3 發佈記</a></dd>
<dd><a href="2_2_release_notes.html">Ruby on Rails 2.2 發佈記</a></dd>
<dt>Rails 指南翻譯術語</dt>
<dd><a href="translation_terms.html">翻譯術語</a></dd>
</dl>
</div>
</li>
<li><a class="nav-item" href="//github.com/docrails-tw/guides">貢獻翻譯</a></li>
<li><a class="nav-item" href="contributing_to_ruby_on_rails.html">貢獻</a></li>
<li><a class="nav-item" href="credits.html">致謝</a></li>
<li class="guides-index guides-index-small">
<select class="guides-index-item nav-item">
<option value="index.html">指南目錄</option>
<optgroup label="起步走">
<option value="getting_started.html">Rails 起步走</option>
</optgroup>
<optgroup label="Models">
<option value="active_record_basics.html">Active Record 基礎</option>
<option value="active_record_migrations.html">Active Record 遷移</option>
<option value="active_record_validations.html">Active Record 驗證</option>
<option value="active_record_callbacks.html">Active Record 回呼</option>
<option value="association_basics.html">Active Record 關聯</option>
<option value="active_record_querying.html">Active Record 查詢</option>
</optgroup>
<optgroup label="Views">
<option value="layouts_and_rendering.html">Rails 算繪與版型</option>
<option value="form_helpers.html">Action View 表單輔助方法</option>
</optgroup>
<optgroup label="Controllers">
<option value="action_controller_overview.html">Action Controller 綜覽</option>
<option value="routing.html">Rails 路由：深入淺出</option>
</optgroup>
<optgroup label="深入了解">
<option value="active_support_core_extensions.html">Active Support 核心擴展</option>
<option value="i18n.html">Rails 國際化 API</option>
<option value="action_mailer_basics.html">Action Mailer 基礎</option>
<option value="active_job_basics.html">Active Job 基礎</option>
<option value="security.html">Rails 安全指南</option>
<option value="debugging_rails_applications.html">除錯 Rails 應用程式</option>
<option value="configuring.html">Rails 應用程式設定</option>
<option value="command_line.html">Rake 任務與 Rails 命令列工具</option>
<option value="asset_pipeline.html">Asset Pipeline</option>
<option value="working_with_javascript_in_rails.html">在 Rails 使用 JavaScript</option>
<option value="constant_autoloading_and_reloading.html">Constant Autoloading and Reloading</option>
</optgroup>
<optgroup label="擴充 Rails">
<option value="rails_on_rack.html">Rails on Rack</option>
<option value="generators.html">客製與新建 Rails 產生器</option>
<option value="rails_application_templates.html">Rails 應用程式模版</option>
</optgroup>
<optgroup label="貢獻 Ruby on Rails">
<option value="contributing_to_ruby_on_rails.html">貢獻 Ruby on Rails</option>
<option value="api_documentation_guidelines.html">API 文件準則</option>
<option value="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南準則</option>
</optgroup>
<optgroup label="維護方針">
<option value="maintenance_policy.html">維護方針</option>
</optgroup>
<optgroup label="發佈記">
<option value="upgrading_ruby_on_rails.html">升級 Ruby on Rails</option>
<option value="4_2_release_notes.html">Ruby on Rails 4.2 發佈記</option>
<option value="4_1_release_notes.html">Ruby on Rails 4.1 發佈記</option>
<option value="4_0_release_notes.html">Ruby on Rails 4.0 發佈記</option>
<option value="3_2_release_notes.html">Ruby on Rails 3.2 發佈記</option>
<option value="3_1_release_notes.html">Ruby on Rails 3.1 發佈記</option>
<option value="3_0_release_notes.html">Ruby on Rails 3.0 發佈記</option>
<option value="2_3_release_notes.html">Ruby on Rails 2.3 發佈記</option>
<option value="2_2_release_notes.html">Ruby on Rails 2.2 發佈記</option>
</optgroup>
<optgroup label="Rails 指南翻譯術語">
<option value="translation_terms.html">翻譯術語</option>
</optgroup>
</select>
</li>
</ul>
</div>
</div>
</div>
<hr class="hide">
<div id="feature">
<div class="wrapper">
<h2>Ruby on Rails 3.1 Release Notes</h2><p>Highlights in Rails 3.1:</p>
<ul>
<li>Streaming</li>
<li>Reversible Migrations</li>
<li>Assets Pipeline</li>
<li>jQuery as the default JavaScript library</li>
</ul>
<p>This release notes cover the major changes, but don't include every little bug fix and change. If you want to see everything, check out the <a href="https://github.com/rails/rails/commits/3-1-stable">list of commits</a> in the main Rails repository on GitHub.</p>
<div id="subCol">
<h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
<ol class="chapters">
<li>
<a href="#upgrading-to-rails-3-1">Upgrading to Rails 3.1</a>
<ul>
<li><a href="#rails-3-1-requires-at-least-ruby-1-8-7">Rails 3.1 requires at least Ruby 1.8.7</a></li>
<li><a href="#what-to-update-in-your-apps">What to update in your apps</a></li>
</ul>
</li>
<li>
<a href="#creating-a-rails-3-1-application">Creating a Rails 3.1 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="#assets-pipeline">Assets Pipeline</a></li>
<li><a href="#http-streaming">HTTP Streaming</a></li>
<li><a href="#default-js-library-is-now-jquery">Default JS library is now jQuery</a></li>
<li><a href="#identity-map">Identity Map</a></li>
</ul>
</li>
<li><a href="#railties">Railties</a></li>
<li>
<a href="#action-pack">Action Pack</a>
<ul>
<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-record">Active Record</a></li>
<li><a href="#active-model">Active Model</a></li>
<li><a href="#active-resource">Active Resource</a></li>
<li><a href="#active-support">Active Support</a></li>
<li><a href="#credits">Credits</a></li>
</ol>
</div>
</div>
</div>
<div id="container">
<div class="wrapper">
<div id="mainCol">
<h3 id="upgrading-to-rails-3-1">1 Upgrading to Rails 3.1</h3><p>If you're upgrading an existing application, it's a great idea to have good test coverage before going in. You should also first upgrade to Rails 3 in case you haven't and make sure your application still runs as expected before attempting to update to Rails 3.1. Then take heed of the following changes:</p><h4 id="rails-3-1-requires-at-least-ruby-1-8-7">1.1 Rails 3.1 requires at least Ruby 1.8.7</h4><p>Rails 3.1 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.1 is also compatible with Ruby 1.9.2.</p><div class="info"><p>Note that Ruby 1.8.7 p248 and p249 have marshaling bugs that crash Rails. 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, so if you want to use 1.9.x jump on 1.9.2 for smooth sailing.</p></div><h4 id="what-to-update-in-your-apps">1.2 What to update in your apps</h4><p>The following changes are meant for upgrading your application to Rails 3.1.3, the latest 3.1.x version of Rails.</p><h5 id="gemfile">1.2.1 Gemfile</h5><p>Make the following changes to your <code>Gemfile</code>.</p><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
gem 'rails', '= 3.1.3'
gem 'mysql2'
# Needed for the new asset pipeline
group :assets do
gem 'sass-rails', "~> 3.1.5"
gem 'coffee-rails', "~> 3.1.1"
gem 'uglifier', ">= 1.0.3"
end
# jQuery is the default JavaScript library in Rails 3.1
gem 'jquery-rails'
</pre>
</div>
<h5 id="config-application-rb">1.2.2 config/application.rb</h5>
<ul>
<li>
<p>The asset pipeline requires the following additions:</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
config.assets.enabled = true
config.assets.version = '1.0'
</pre>
</div>
</li>
<li>
<p>If your application is using the "/assets" route for a resource you may want change the prefix used for assets to avoid conflicts:</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# Defaults to '/assets'
config.assets.prefix = '/asset-files'
</pre>
</div>
</li>
</ul>
<h5 id="config-environments-development-rb">1.2.3 config/environments/development.rb</h5>
<ul>
<li><p>Remove the RJS setting <code>config.action_view.debug_rjs = true</code>.</p></li>
<li>
<p>Add the following, if you enable the asset pipeline.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# Do not compress assets
config.assets.compress = false
# Expands the lines which load the assets
config.assets.debug = true
</pre>
</div>
</li>
</ul>
<h5 id="config-environments-production-rb">1.2.4 config/environments/production.rb</h5>
<ul>
<li>
<p>Again, most of the changes below are for the asset pipeline. You can read more about these in the <a href="asset_pipeline.html">Asset Pipeline</a> guide.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# Compress JavaScripts and CSS
config.assets.compress = true
# Don't fallback to assets pipeline if a precompiled asset is missed
config.assets.compile = false
# Generate digests for assets URLs
config.assets.digest = true
# Defaults to Rails.root.join("public/assets")
# config.assets.manifest = YOUR_PATH
# Precompile additional assets (application.js, application.css, and all non-JS/CSS are already added)
# config.assets.precompile `= %w( search.js )
# Force all access to the app over SSL, use Strict-Transport-Security, and use secure cookies.
# config.force_ssl = true
</pre>
</div>
</li>
</ul>
<h5 id="config-environments-test-rb">1.2.5 config/environments/test.rb</h5><div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# Configure static asset server for tests with Cache-Control for performance
config.serve_static_assets = true
config.static_cache_control = "public, max-age=3600"
</pre>
</div>
<h5 id="config-initializers-wrap-parameters-rb">1.2.6 config/initializers/wrap_parameters.rb</h5>
<ul>
<li>
<p>Add this file with the following contents, if you wish to wrap parameters into a nested hash. This is on by default in new applications.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# Be sure to restart your server when you modify this file.
# This file contains settings for ActionController::ParamsWrapper which
# is enabled by default.
# Enable parameter wrapping for JSON. You can disable this by setting :format to an empty array.
ActiveSupport.on_load(:action_controller) do
wrap_parameters :format => [:json]
end
# Disable root element in JSON by default.
ActiveSupport.on_load(:active_record) do
self.include_root_in_json = false
end
</pre>
</div>
</li>
</ul>
<h5 id="remove-cache-and-concat-options-in-asset-helpers-references-in-views">1.2.7 Remove :cache and :concat options in asset helpers references in views</h5>
<ul>
<li>With the Asset Pipeline the :cache and :concat options aren't used anymore, delete these options from your views.</li>
</ul>
<h3 id="creating-a-rails-3-1-application">2 Creating a Rails 3.1 application</h3><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
# You should have the 'rails' RubyGem installed
$ rails new myapp
$ cd myapp
</pre>
</div>
<h4 id="vendoring-gems">2.1 Vendoring Gems</h4><p>Rails now uses a <code>Gemfile</code> in the application root to determine the gems you require for your application to start. This <code>Gemfile</code> is processed by the <a href="https://github.com/carlhuda/bundler">Bundler</a> gem, which then installs all your dependencies. It can even install all the dependencies locally to your application so that it doesn't depend on the system gems.</p><p>More information: - <a href="http://gembundler.com">bundler homepage</a></p><h4 id="living-on-the-edge">2.2 Living on the Edge</h4><p><code>Bundler</code> and <code>Gemfile</code> makes freezing your Rails application easy as pie with the new dedicated <code>bundle</code> command. If you want to bundle straight from the Git repository, you can pass the <code>--edge</code> flag:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ rails new myapp --edge
</pre>
</div>
<p>If you have a local checkout of the Rails repository and want to generate an application using that, you can pass the <code>--dev</code> flag:</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ ruby /path/to/rails/railties/bin/rails new myapp --dev
</pre>
</div>
<h3 id="rails-architectural-changes">3 Rails Architectural Changes</h3><h4 id="assets-pipeline">3.1 Assets Pipeline</h4><p>The major change in Rails 3.1 is the Assets Pipeline. It makes CSS and JavaScript first-class code citizens and enables proper organization, including use in plugins and engines.</p><p>The assets pipeline is powered by <a href="https://github.com/sstephenson/sprockets">Sprockets</a> and is covered in the <a href="asset_pipeline.html">Asset Pipeline</a> guide.</p><h4 id="http-streaming">3.2 HTTP Streaming</h4><p>HTTP Streaming is another change that is new in Rails 3.1. This lets the browser download your stylesheets and JavaScript files while the server is still generating the response. This requires Ruby 1.9.2, is opt-in and requires support from the web server as well, but the popular combo of NGINX and Unicorn is ready to take advantage of it.</p><h4 id="default-js-library-is-now-jquery">3.3 Default JS library is now jQuery</h4><p>jQuery is the default JavaScript library that ships with Rails 3.1. But if you use Prototype, it's simple to switch.</p><div class="code_container">
<pre class="brush: plain; gutter: false; toolbar: false">
$ rails new myapp -j prototype
</pre>
</div>
<h4 id="identity-map">3.4 Identity Map</h4><p>Active Record has an Identity Map in Rails 3.1. An identity map keeps previously instantiated records and returns the object associated with the record if accessed again. The identity map is created on a per-request basis and is flushed at request completion.</p><p>Rails 3.1 comes with the identity map turned off by default.</p><h3 id="railties">4 Railties</h3>
<ul>
<li><p>jQuery is the new default JavaScript library.</p></li>
<li><p>jQuery and Prototype are no longer vendored and is provided from now on by the jquery-rails and prototype-rails gems.</p></li>
<li><p>The application generator accepts an option <code>-j</code> which can be an arbitrary string. If passed "foo", the gem "foo-rails" is added to the <code>Gemfile</code>, and the application JavaScript manifest requires "foo" and "foo_ujs". Currently only "prototype-rails" and "jquery-rails" exist and provide those files via the asset pipeline.</p></li>
<li><p>Generating an application or a plugin runs <code>bundle install</code> unless <code>--skip-gemfile</code> or <code>--skip-bundle</code> is specified.</p></li>
<li><p>The controller and resource generators will now automatically produce asset stubs (this can be turned off with <code>--skip-assets</code>). These stubs will use CoffeeScript and Sass, if those libraries are available.</p></li>
<li><p>Scaffold and app generators use the Ruby 1.9 style hash when running on Ruby 1.9. To generate old style hash, <code>--old-style-hash</code> can be passed.</p></li>
<li><p>Scaffold controller generator creates format block for JSON instead of XML.</p></li>
<li><p>Active Record logging is directed to STDOUT and shown inline in the console.</p></li>
<li><p>Added <code>config.force_ssl</code> configuration which loads <code>Rack::SSL</code> middleware and force all requests to be under HTTPS protocol.</p></li>
<li><p>Added <code>rails plugin new</code> command which generates a Rails plugin with gemspec, tests and a dummy application for testing.</p></li>
<li><p>Added <code>Rack::Etag</code> and <code>Rack::ConditionalGet</code> to the default middleware stack.</p></li>
<li><p>Added <code>Rack::Cache</code> to the default middleware stack.</p></li>
<li><p>Engines received a major update - You can mount them at any path, enable assets, run generators etc.</p></li>
</ul>
<h3 id="action-pack">5 Action Pack</h3><h4 id="action-controller">5.1 Action Controller</h4>
<ul>
<li><p>A warning is given out if the CSRF token authenticity cannot be verified.</p></li>
<li><p>Specify <code>force_ssl</code> in a controller to force the browser to transfer data via HTTPS protocol on that particular controller. To limit to specific actions, <code>:only</code> or <code>:except</code> can be used.</p></li>
<li><p>Sensitive query string parameters specified in <code>config.filter_parameters</code> will now be filtered out from the request paths in the log.</p></li>
<li><p>URL parameters which return <code>nil</code> for <code>to_param</code> are now removed from the query string.</p></li>
<li><p>Added <code>ActionController::ParamsWrapper</code> to wrap parameters into a nested hash, and will be turned on for JSON request in new applications by default. This can be customized in <code>config/initializers/wrap_parameters.rb</code>.</p></li>
<li><p>Added <code>config.action_controller.include_all_helpers</code>. By default <code>helper :all</code> is done in <code>ActionController::Base</code>, which includes all the helpers by default. Setting <code>include_all_helpers</code> to <code>false</code> will result in including only application_helper and the helper corresponding to controller (like foo_helper for foo_controller).</p></li>
<li><p><code>url_for</code> and named url helpers now accept <code>:subdomain</code> and <code>:domain</code> as options.</p></li>
<li>
<p>Added <code>Base.http_basic_authenticate_with</code> to do simple http basic authentication with a single class method call.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class PostsController < ApplicationController
USER_NAME, PASSWORD = "dhh", "secret"
before_filter :authenticate, :except => [ :index ]
def index
render :text => "Everyone can see me!"
end
def edit
render :text => "I'm only accessible if you know the password"
end
private
def authenticate
authenticate_or_request_with_http_basic do |user_name, password|
user_name == USER_NAME && password == PASSWORD
end
end
end
</pre>
</div>
<p>..can now be written as</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class PostsController < ApplicationController
http_basic_authenticate_with :name => "dhh", :password => "secret", :except => :index
def index
render :text => "Everyone can see me!"
end
def edit
render :text => "I'm only accessible if you know the password"
end
end
</pre>
</div>
</li>
<li>
<p>Added streaming support, you can enable it with:</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class PostsController < ActionController::Base
stream
end
</pre>
</div>
<p>You can restrict it to some actions by using <code>:only</code> or <code>:except</code>. Please read the docs at <a href="http://api.rubyonrails.org/v3.1.0/classes/ActionController/Streaming.html"><code>ActionController::Streaming</code></a> for more information.</p>
</li>
<li><p>The redirect route method now also accepts a hash of options which will only change the parts of the url in question, or an object which responds to call, allowing for redirects to be reused.</p></li>
</ul>
<h4 id="action-dispatch">5.2 Action Dispatch</h4>
<ul>
<li><p><code>config.action_dispatch.x_sendfile_header</code> now defaults to <code>nil</code> and <code>config/environments/production.rb</code> doesn't set any particular value for it. This allows servers to set it through <code>X-Sendfile-Type</code>.</p></li>
<li><p><code>ActionDispatch::MiddlewareStack</code> now uses composition over inheritance and is no longer an array.</p></li>
<li><p>Added <code>ActionDispatch::Request.ignore_accept_header</code> to ignore accept headers.</p></li>
<li><p>Added <code>Rack::Cache</code> to the default stack.</p></li>
<li><p>Moved etag responsibility from <code>ActionDispatch::Response</code> to the middleware stack.</p></li>
<li><p>Rely on <code>Rack::Session</code> stores API for more compatibility across the Ruby world. This is backwards incompatible since <code>Rack::Session</code> expects <code>#get_session</code> to accept four arguments and requires <code>#destroy_session</code> instead of simply <code>#destroy</code>.</p></li>
<li><p>Template lookup now searches further up in the inheritance chain.</p></li>
</ul>
<h4 id="action-view">5.3 Action View</h4>
<ul>
<li><p>Added an <code>:authenticity_token</code> option to <code>form_tag</code> for custom handling or to omit the token by passing <code>:authenticity_token => false</code>.</p></li>
<li><p>Created <code>ActionView::Renderer</code> and specified an API for <code>ActionView::Context</code>.</p></li>
<li><p>In place <code>SafeBuffer</code> mutation is prohibited in Rails 3.1.</p></li>
<li><p>Added HTML5 <code>button_tag</code> helper.</p></li>
<li><p><code>file_field</code> automatically adds <code>:multipart => true</code> to the enclosing form.</p></li>
<li>
<p>Added a convenience idiom to generate HTML5 data-* attributes in tag helpers from a <code>:data</code> hash of options:</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
tag("div", :data => {:name => 'Stephen', :city_state => %w(Chicago IL)})
# => <div data-name="Stephen" data-city-state="[&quot;Chicago&quot;,&quot;IL&quot;]" />
</pre>
</div>
</li>
</ul>
<p>Keys are dasherized. Values are JSON-encoded, except for strings and symbols.</p>
<ul>
<li><p><code>csrf_meta_tag</code> is renamed to <code>csrf_meta_tags</code> and aliases <code>csrf_meta_tag</code> for backwards compatibility.</p></li>
<li><p>The old template handler API is deprecated and the new API simply requires a template handler to respond to call.</p></li>
<li><p>rhtml and rxml are finally removed as template handlers.</p></li>
<li><p><code>config.action_view.cache_template_loading</code> is brought back which allows to decide whether templates should be cached or not.</p></li>
<li><p>The submit form helper does not generate an id "object_name_id" anymore.</p></li>
<li><p>Allows <code>FormHelper#form_for</code> to specify the <code>:method</code> as a direct option instead of through the <code>:html</code> hash. <code>form_for(@post, remote: true, method: :delete)</code> instead of <code>form_for(@post, remote: true, html: { method: :delete })</code>.</p></li>
<li><p>Provided <code>JavaScriptHelper#j()</code> as an alias for <code>JavaScriptHelper#escape_javascript()</code>. This supersedes the <code>Object#j()</code> method that the JSON gem adds within templates using the JavaScriptHelper.</p></li>
<li><p>Allows AM/PM format in datetime selectors.</p></li>
<li><p><code>auto_link</code> has been removed from Rails and extracted into the <a href="https://github.com/tenderlove/rails_autolink">rails_autolink gem</a></p></li>
</ul>
<h3 id="active-record">6 Active Record</h3>
<ul>
<li>
<p>Added a class method <code>pluralize_table_names</code> to singularize/pluralize table names of individual models. Previously this could only be set globally for all models through <code>ActiveRecord::Base.pluralize_table_names</code>.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class User < ActiveRecord::Base
self.pluralize_table_names = false
end
</pre>
</div>
</li>
<li>
<p>Added block setting of attributes to singular associations. The block will get called after the instance is initialized.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class User < ActiveRecord::Base
has_one :account
end
user.build_account{ |a| a.credit_limit = 100.0 }
</pre>
</div>
</li>
<li><p>Added <code>ActiveRecord::Base.attribute_names</code> to return a list of attribute names. This will return an empty array if the model is abstract or the table does not exist.</p></li>
<li><p>CSV Fixtures are deprecated and support will be removed in Rails 3.2.0.</p></li>
<li>
<p><code>ActiveRecord#new</code>, <code>ActiveRecord#create</code> and <code>ActiveRecord#update_attributes</code> all accept a second hash as an option that allows you to specify which role to consider when assigning attributes. This is built on top of Active Model's new mass assignment capabilities:</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class Post < ActiveRecord::Base
attr_accessible :title
attr_accessible :title, :published_at, :as => :admin
end
Post.new(params[:post], :as => :admin)
</pre>
</div>
</li>
<li><p><code>default_scope</code> can now take a block, lambda, or any other object which responds to call for lazy evaluation.</p></li>
<li><p>Default scopes are now evaluated at the latest possible moment, to avoid problems where scopes would be created which would implicitly contain the default scope, which would then be impossible to get rid of via Model.unscoped.</p></li>
<li><p>PostgreSQL adapter only supports PostgreSQL version 8.2 and higher.</p></li>
<li><p><code>ConnectionManagement</code> middleware is changed to clean up the connection pool after the rack body has been flushed.</p></li>
<li><p>Added an <code>update_column</code> method on Active Record. This new method updates a given attribute on an object, skipping validations and callbacks. It is recommended to use <code>update_attributes</code> or <code>update_attribute</code> unless you are sure you do not want to execute any callback, including the modification of the <code>updated_at</code> column. It should not be called on new records.</p></li>
<li><p>Associations with a <code>:through</code> option can now use any association as the through or source association, including other associations which have a <code>:through</code> option and <code>has_and_belongs_to_many</code> associations.</p></li>
<li><p>The configuration for the current database connection is now accessible via <code>ActiveRecord::Base.connection_config</code>.</p></li>
<li>
<p>limits and offsets are removed from COUNT queries unless both are supplied.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
People.limit(1).count # => 'SELECT COUNT(*) FROM people'
People.offset(1).count # => 'SELECT COUNT(*) FROM people'
People.limit(1).offset(1).count # => 'SELECT COUNT(*) FROM people LIMIT 1 OFFSET 1'
</pre>
</div>
</li>
<li><p><code>ActiveRecord::Associations::AssociationProxy</code> has been split. There is now an <code>Association</code> class (and subclasses) which are responsible for operating on associations, and then a separate, thin wrapper called <code>CollectionProxy</code>, which proxies collection associations. This prevents namespace pollution, separates concerns, and will allow further refactorings.</p></li>
<li><p>Singular associations (<code>has_one</code>, <code>belongs_to</code>) no longer have a proxy and simply returns the associated record or <code>nil</code>. This means that you should not use undocumented methods such as <code>bob.mother.create</code> - use <code>bob.create_mother</code> instead.</p></li>
<li><p>Support the <code>:dependent</code> option on <code>has_many :through</code> associations. For historical and practical reasons, <code>:delete_all</code> is the default deletion strategy employed by <code>association.delete(*records)</code>, despite the fact that the default strategy is <code>:nullify</code> for regular has_many. Also, this only works at all if the source reflection is a belongs_to. For other situations, you should directly modify the through association.</p></li>
<li><p>The behavior of <code>association.destroy</code> for <code>has_and_belongs_to_many</code> and <code>has_many :through</code> is changed. From now on, 'destroy' or 'delete' on an association will be taken to mean 'get rid of the link', not (necessarily) 'get rid of the associated records'.</p></li>
<li><p>Previously, <code>has_and_belongs_to_many.destroy(*records)</code> would destroy the records themselves. It would not delete any records in the join table. Now, it deletes the records in the join table.</p></li>
<li><p>Previously, <code>has_many_through.destroy(*records)</code> would destroy the records themselves, and the records in the join table. [Note: This has not always been the case; previous version of Rails only deleted the records themselves.] Now, it destroys only the records in the join table.</p></li>
<li><p>Note that this change is backwards-incompatible to an extent, but there is unfortunately no way to 'deprecate' it before changing it. The change is being made in order to have consistency as to the meaning of 'destroy' or 'delete' across the different types of associations. If you wish to destroy the records themselves, you can do <code>records.association.each(&:destroy)</code>.</p></li>
<li>
<p>Add <code>:bulk => true</code> option to <code>change_table</code> to make all the schema changes defined in a block using a single ALTER statement.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
change_table(:users, :bulk => true) do |t|
t.string :company_name
t.change :birthdate, :datetime
end
</pre>
</div>
</li>
<li><p>Removed support for accessing attributes on a <code>has_and_belongs_to_many</code> join table. <code>has_many :through</code> needs to be used.</p></li>
<li><p>Added a <code>create_association!</code> method for <code>has_one</code> and <code>belongs_to</code> associations.</p></li>
<li>
<p>Migrations are now reversible, meaning that Rails will figure out how to reverse your migrations. To use reversible migrations, just define the <code>change</code> method.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class MyMigration < ActiveRecord::Migration
def change
create_table(:horses) do |t|
t.column :content, :text
t.column :remind_at, :datetime
end
end
end
</pre>
</div>
</li>
<li><p>Some things cannot be automatically reversed for you. If you know how to reverse those things, you should define <code>up</code> and <code>down</code> in your migration. If you define something in change that cannot be reversed, an <code>IrreversibleMigration</code> exception will be raised when going down.</p></li>
<li>
<p>Migrations now use instance methods rather than class methods:</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class FooMigration < ActiveRecord::Migration
def up # Not self.up
...
end
end
</pre>
</div>
</li>
<li><p>Migration files generated from model and constructive migration generators (for example, add_name_to_users) use the reversible migration's <code>change</code> method instead of the ordinary <code>up</code> and <code>down</code> methods.</p></li>
<li>
<p>Removed support for interpolating string SQL conditions on associations. Instead, a proc should be used.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
has_many :things, :conditions => 'foo = #{bar}' # before
has_many :things, :conditions => proc { "foo = #{bar}" } # after
</pre>
</div>
<p>Inside the proc, <code>self</code> is the object which is the owner of the association, unless you are eager loading the association, in which case <code>self</code> is the class which the association is within.</p>
<p>You can have any "normal" conditions inside the proc, so the following will work too:</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
has_many :things, :conditions => proc { ["foo = ?", bar] }
</pre>
</div>
</li>
<li><p>Previously <code>:insert_sql</code> and <code>:delete_sql</code> on <code>has_and_belongs_to_many</code> association allowed you to call 'record' to get the record being inserted or deleted. This is now passed as an argument to the proc.</p></li>
<li>
<p>Added <code>ActiveRecord::Base#has_secure_password</code> (via <code>ActiveModel::SecurePassword</code>) to encapsulate dead-simple password usage with BCrypt encryption and salting.</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
# Schema: User(name:string, password_digest:string, password_salt:string)
class User < ActiveRecord::Base
has_secure_password
end
</pre>
</div>
</li>
<li><p>When a model is generated <code>add_index</code> is added by default for <code>belongs_to</code> or <code>references</code> columns.</p></li>
<li><p>Setting the id of a <code>belongs_to</code> object will update the reference to the object.</p></li>
<li><p><code>ActiveRecord::Base#dup</code> and <code>ActiveRecord::Base#clone</code> semantics have changed to closer match normal Ruby dup and clone semantics.</p></li>
<li><p>Calling <code>ActiveRecord::Base#clone</code> will result in a shallow copy of the record, including copying the frozen state. No callbacks will be called.</p></li>
<li><p>Calling <code>ActiveRecord::Base#dup</code> will duplicate the record, including calling after initialize hooks. Frozen state will not be copied, and all associations will be cleared. A duped record will return <code>true</code> for <code>new_record?</code>, have a <code>nil</code> id field, and is saveable.</p></li>
<li><p>The query cache now works with prepared statements. No changes in the applications are required.</p></li>
</ul>
<h3 id="active-model">7 Active Model</h3>
<ul>
<li><p><code>attr_accessible</code> accepts an option <code>:as</code> to specify a role.</p></li>
<li><p><code>InclusionValidator</code>, <code>ExclusionValidator</code>, and <code>FormatValidator</code> now accepts an option which can be a proc, a lambda, or anything that respond to <code>call</code>. This option will be called with the current record as an argument and returns an object which respond to <code>include?</code> for <code>InclusionValidator</code> and <code>ExclusionValidator</code>, and returns a regular expression object for <code>FormatValidator</code>.</p></li>
<li><p>Added <code>ActiveModel::SecurePassword</code> to encapsulate dead-simple password usage with BCrypt encryption and salting.</p></li>
<li><p><code>ActiveModel::AttributeMethods</code> allows attributes to be defined on demand.</p></li>
<li><p>Added support for selectively enabling and disabling observers.</p></li>
<li><p>Alternate <code>I18n</code> namespace lookup is no longer supported.</p></li>
</ul>
<h3 id="active-resource">8 Active Resource</h3>
<ul>
<li>
<p>The default format has been changed to JSON for all requests. If you want to continue to use XML you will need to set <code>self.format = :xml</code> in the class. For example,</p>
<div class="code_container">
<pre class="brush: ruby; gutter: false; toolbar: false">
class User < ActiveResource::Base
self.format = :xml
end
</pre>
</div>
</li>
</ul>
<h3 id="active-support">9 Active Support</h3>
<ul>
<li><p><code>ActiveSupport::Dependencies</code> now raises <code>NameError</code> if it finds an existing constant in <code>load_missing_constant</code>.</p></li>
<li><p>Added a new reporting method <code>Kernel#quietly</code> which silences both <code>STDOUT</code> and <code>STDERR</code>.</p></li>
<li><p>Added <code>String#inquiry</code> as a convenience method for turning a String into a <code>StringInquirer</code> object.</p></li>
<li><p>Added <code>Object#in?</code> to test if an object is included in another object.</p></li>
<li><p><code>LocalCache</code> strategy is now a real middleware class and no longer an anonymous class.</p></li>
<li><p><code>ActiveSupport::Dependencies::ClassCache</code> class has been introduced for holding references to reloadable classes.</p></li>
<li><p><code>ActiveSupport::Dependencies::Reference</code> has been refactored to take direct advantage of the new <code>ClassCache</code>.</p></li>
<li><p>Backports <code>Range#cover?</code> as an alias for <code>Range#include?</code> in Ruby 1.8.</p></li>
<li><p>Added <code>weeks_ago</code> and <code>prev_week</code> to Date/DateTime/Time.</p></li>
<li><p>Added <code>before_remove_const</code> callback to <code>ActiveSupport::Dependencies.remove_unloadable_constants!</code>.</p></li>
</ul>
<p>Deprecations:</p>
<ul>
<li>
<code>ActiveSupport::SecureRandom</code> is deprecated in favor of <code>SecureRandom</code> from the Ruby standard library.</li>
</ul>
<h3 id="credits">10 Credits</h3><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, the stable and robust framework it is. Kudos to all of them.</p><p>Rails 3.1 Release Notes were compiled by <a href="https://github.com/vijaydev.">Vijay Dev</a></p>
<h3>反饋</h3>
<p>
歡迎幫忙改善指南的品質。
</p>
<p>
如發現任何錯誤之處，歡迎修正。開始貢獻前，可以先閱讀<a href="http://edgeguides.rubyonrails.org/contributing_to_ruby_on_rails.html#contributing-to-the-rails-documentation">貢獻指南：文件</a>。
</p>
<p>翻譯如有錯誤，深感抱歉，歡迎 <a href="https://github.com/docrails-tw/guides/fork">Fork</a> 修正，或至此處<a href="https://github.com/docsrails-tw/guides/issues/new">回報</a>。</p>
<p>
文章可能有未完成或過時的內容。請先檢查 <a href="http://edgeguides.rubyonrails.org">Edge Guides</a> 來確定問題在 master 是否已經修掉了。再上 master 補上缺少的文件。內容參考 <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails 指南準則</a>來了解行文風格。
</p>
<p>最後，任何關於 Ruby on Rails 文件的討論，歡迎至 <a href="http://groups.google.com/group/rubyonrails-docs">rubyonrails-docs 郵件論壇</a>。
</p>
</div>
</div>
</div>
<hr class="hide">
<div id="footer">
<div class="wrapper">
<p>本著作係採用<a href="https://creativecommons.org/licenses/by-sa/4.0/deed.zh_TW">創用 CC 姓名標示-相同方式分享 4.0 國際授權條款</a>授權。</p>
<p>“Rails”、“Ruby on Rails”，以及 Rails logo 為 David Heinemeier Hansson 的商標。版權所有。</p>
</div>
</div>
<script src="javascripts/jquery.min.js"></script>
<script src="javascripts/responsive-tables.js"></script>
<script src="javascripts/guides.js"></script>
<script src="javascripts/syntaxhighlighter/shCore.js"></script>
<script src="javascripts/syntaxhighlighter/shBrushRuby.js"></script>
<script src="javascripts/syntaxhighlighter/shBrushXml.js"></script>
<script src="javascripts/syntaxhighlighter/shBrushSql.js"></script>
<script src="javascripts/syntaxhighlighter/shBrushPlain.js"></script>
<script type="text/javascript">
SyntaxHighlighter.all();
$(guidesIndex.bind);
</script>
<script>
(function(i,s,o,g,r,a,m){i["GoogleAnalyticsObject"]=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,"script","//www.google-analytics.com/analytics.js","ga");
ga("create", "UA-49903900-1", "auto");
ga("require", "displayfeatures");
ga("send", "pageview");
</script>
</body>
</html>