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
data/guides/output/rails_application_templates.html ADDED
@@ -0,0 +1,368 @@
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: Rails Application Templates</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>Rails Application Templates</h2>
99
+ <p>Application templates are simple Ruby files containing <span class="caps">DSL</span> for adding plugins/gems/initializers etc. to your freshly created Rails project or an existing Rails project.</p>
100
+ <p>By referring to this guide, you will be able to:</p>
101
+ <ul>
102
+ <li>Use templates to generate/customize Rails applications</li>
103
+ <li>Write your own reusable application templates using the Rails template <span class="caps">API</span></li>
104
+ </ul>
105
+
106
+ <div id="subCol">
107
+ <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
108
+ <ol class="chapters">
109
+ <li><a href="#usage">Usage</a></li><li><a href="#template-api">Template <span class="caps">API</span></a><ul><li><a href="#gem-name-options">gem(name, options = {})</a></li> <li><a href="#gem_group-names-block">gem_group(*names, &amp;block)</a></li> <li><a href="#add_source-source-options">add_source(source, options = {})</a></li> <li><a href="#plugin-name-options">plugin(name, options = {})</a></li> <li><a href="#vendor-lib-file-initializer-filename-data-nil-block">vendor/lib/file/initializer(filename, data = nil, &amp;block)</a></li> <li><a href="#rakefile-filename-data-nil-block">rakefile(filename, data = nil, &amp;block)</a></li> <li><a href="#generate-what-args">generate(what, args)</a></li> <li><a href="#run-command">run(command)</a></li> <li><a href="#rake-command-options">rake(command, options = {})</a></li> <li><a href="#route-routing_code">route(routing_code)</a></li> <li><a href="#inside-dir">inside(dir)</a></li> <li><a href="#ask-question">ask(question)</a></li> <li><a href="#yes-question-or-no-question">yes?(question) or no?(question)</a></li> <li><a href="#git-command">git(:command)</a></li></ul></li></ol></div>
110
+ </div>
111
+ </div>
112
+
113
+ <div id="container">
114
+ <div class="wrapper">
115
+ <div id="mainCol">
116
+ <h3 id="usage">1 Usage</h3>
117
+ <p>To apply a template, you need to provide the Rails generator with the location of the template you wish to apply, using -m option. This can either be path to a file or a <span class="caps">URL</span>.</p>
118
+ <div class="code_container">
119
+ <pre class="brush: plain; gutter: false; toolbar: false">
120
+ $ rails new blog -m ~/template.rb
121
+ $ rails new blog -m http://example.com/template.rb
122
+ </pre>
123
+ </div>
124
+ <p>You can use the rake task <tt>rails:template</tt> to apply templates to an existing Rails application. The location of the template needs to be passed in to an environment variable named <span class="caps">LOCATION</span>. Again, this can either be path to a file or a <span class="caps">URL</span>.</p>
125
+ <div class="code_container">
126
+ <pre class="brush: plain; gutter: false; toolbar: false">
127
+ $ rake rails:template LOCATION=~/template.rb
128
+ $ rake rails:template LOCATION=http://example.com/template.rb
129
+ </pre>
130
+ </div>
131
+ <h3 id="template-api">2 Template <span class="caps">API</span></h3>
132
+ <p>Rails templates <span class="caps">API</span> is very self explanatory and easy to understand. Here&#8217;s an example of a typical Rails template:</p>
133
+ <div class="code_container">
134
+ <pre class="brush: ruby; gutter: false; toolbar: false">
135
+ # template.rb
136
+ run &quot;rm public/index.html&quot;
137
+ generate(:scaffold, &quot;person name:string&quot;)
138
+ route &quot;root :to =&gt; 'people#index'&quot;
139
+ rake(&quot;db:migrate&quot;)
140
+
141
+ git :init
142
+ git :add =&gt; &quot;.&quot;
143
+ git :commit =&gt; &quot;-a -m 'Initial commit'&quot;
144
+ </pre>
145
+ </div>
146
+ <p>The following sections outlines the primary methods provided by the <span class="caps">API</span>:</p>
147
+ <h4 id="gem-name-options">2.1 gem(name, options = {})</h4>
148
+ <p>Adds a <tt>gem</tt> entry for the supplied gem to the generated application’s <tt>Gemfile</tt>.</p>
149
+ <p>For example, if your application depends on the gems <tt>bj</tt> and <tt>nokogiri</tt>:</p>
150
+ <div class="code_container">
151
+ <pre class="brush: ruby; gutter: false; toolbar: false">
152
+ gem &quot;bj&quot;
153
+ gem &quot;nokogiri&quot;
154
+ </pre>
155
+ </div>
156
+ <p>Please note that this will <span class="caps">NOT</span> install the gems for you and you will have to run <tt>bundle install</tt> to do that.</p>
157
+ <div class="code_container">
158
+ <pre class="brush: ruby; gutter: false; toolbar: false">
159
+ bundle install
160
+ </pre>
161
+ </div>
162
+ <h4 id="gem_group-names-block">2.2 gem_group(*names, &amp;block)</h4>
163
+ <p>Wraps gem entries inside a group.</p>
164
+ <p>For example, if you want to load <tt>rspec-rails</tt> only in <tt>development</tt> and <tt>test</tt> group:</p>
165
+ <div class="code_container">
166
+ <pre class="brush: ruby; gutter: false; toolbar: false">
167
+ gem_group :development, :test do
168
+ gem &quot;rspec-rails&quot;
169
+ end
170
+ </pre>
171
+ </div>
172
+ <h4 id="add_source-source-options">2.3 add_source(source, options = {})</h4>
173
+ <p>Adds the given source to the generated application&#8217;s <tt>Gemfile</tt>.</p>
174
+ <p>For example, if you need to source a gem from &#8220;http://code.whytheluckystiff.net&#8221;:</p>
175
+ <div class="code_container">
176
+ <pre class="brush: ruby; gutter: false; toolbar: false">
177
+ add_source &quot;http://code.whytheluckystiff.net&quot;
178
+ </pre>
179
+ </div>
180
+ <h4 id="plugin-name-options">2.4 plugin(name, options = {})</h4>
181
+ <p>Installs a plugin to the generated application.</p>
182
+ <p>Plugin can be installed from Git:</p>
183
+ <div class="code_container">
184
+ <pre class="brush: ruby; gutter: false; toolbar: false">
185
+ plugin 'authentication', :git =&gt; 'git://github.com/foor/bar.git'
186
+ </pre>
187
+ </div>
188
+ <p>You can even install plugins as git submodules:</p>
189
+ <div class="code_container">
190
+ <pre class="brush: ruby; gutter: false; toolbar: false">
191
+ plugin 'authentication', :git =&gt; 'git://github.com/foor/bar.git',
192
+ :submodule =&gt; true
193
+ </pre>
194
+ </div>
195
+ <p>Please note that you need to <tt>git :init</tt> before you can install a plugin as a submodule.</p>
196
+ <p>Or use plain old <span class="caps">SVN</span>:</p>
197
+ <div class="code_container">
198
+ <pre class="brush: ruby; gutter: false; toolbar: false">
199
+ plugin 'usingsvn', :svn =&gt; 'svn://example.com/usingsvn/trunk'
200
+ </pre>
201
+ </div>
202
+ <h4 id="vendor-lib-file-initializer-filename-data-nil-block">2.5 vendor/lib/file/initializer(filename, data = nil, &amp;block)</h4>
203
+ <p>Adds an initializer to the generated application’s <tt>config/initializers</tt> directory.</p>
204
+ <p>Lets say you like using <tt>Object#not_nil?</tt> and <tt>Object#not_blank?</tt>:</p>
205
+ <div class="code_container">
206
+ <pre class="brush: ruby; gutter: false; toolbar: false">
207
+ initializer 'bloatlol.rb', &lt;&lt;-CODE
208
+ class Object
209
+ def not_nil?
210
+ !nil?
211
+ end
212
+
213
+ def not_blank?
214
+ !blank?
215
+ end
216
+ end
217
+ CODE
218
+ </pre>
219
+ </div>
220
+ <p>Similarly <tt>lib()</tt> creates a file in the <tt>lib/</tt> directory and <tt>vendor()</tt> creates a file in the <tt>vendor/</tt> directory.</p>
221
+ <p>There is even <tt>file()</tt>, which accepts a relative path from <tt>Rails.root</tt> and creates all the directories/file needed:</p>
222
+ <div class="code_container">
223
+ <pre class="brush: ruby; gutter: false; toolbar: false">
224
+ file 'app/components/foo.rb', &lt;&lt;-CODE
225
+ class Foo
226
+ end
227
+ CODE
228
+ </pre>
229
+ </div>
230
+ <p>That’ll create <tt>app/components</tt> directory and put <tt>foo.rb</tt> in there.</p>
231
+ <h4 id="rakefile-filename-data-nil-block">2.6 rakefile(filename, data = nil, &amp;block)</h4>
232
+ <p>Creates a new rake file under <tt>lib/tasks</tt> with the supplied tasks:</p>
233
+ <div class="code_container">
234
+ <pre class="brush: ruby; gutter: false; toolbar: false">
235
+ rakefile(&quot;bootstrap.rake&quot;) do
236
+ &lt;&lt;-TASK
237
+ namespace :boot do
238
+ task :strap do
239
+ puts &quot;i like boots!&quot;
240
+ end
241
+ end
242
+ TASK
243
+ end
244
+ </pre>
245
+ </div>
246
+ <p>The above creates <tt>lib/tasks/bootstrap.rake</tt> with a <tt>boot:strap</tt> rake task.</p>
247
+ <h4 id="generate-what-args">2.7 generate(what, args)</h4>
248
+ <p>Runs the supplied rails generator with given arguments.</p>
249
+ <div class="code_container">
250
+ <pre class="brush: ruby; gutter: false; toolbar: false">
251
+ generate(:scaffold, &quot;person&quot;, &quot;name:string&quot;, &quot;address:text&quot;, &quot;age:number&quot;)
252
+ </pre>
253
+ </div>
254
+ <h4 id="run-command">2.8 run(command)</h4>
255
+ <p>Executes an arbitrary command. Just like the backticks. Let&#8217;s say you want to remove the <tt>public/index.html</tt> file:</p>
256
+ <div class="code_container">
257
+ <pre class="brush: ruby; gutter: false; toolbar: false">
258
+ run &quot;rm public/index.html&quot;
259
+ </pre>
260
+ </div>
261
+ <h4 id="rake-command-options">2.9 rake(command, options = {})</h4>
262
+ <p>Runs the supplied rake tasks in the Rails application. Let&#8217;s say you want to migrate the database:</p>
263
+ <div class="code_container">
264
+ <pre class="brush: ruby; gutter: false; toolbar: false">
265
+ rake &quot;db:migrate&quot;
266
+ </pre>
267
+ </div>
268
+ <p>You can also run rake tasks with a different Rails environment:</p>
269
+ <div class="code_container">
270
+ <pre class="brush: ruby; gutter: false; toolbar: false">
271
+ rake &quot;db:migrate&quot;, :env =&gt; 'production'
272
+ </pre>
273
+ </div>
274
+ <h4 id="route-routing_code">2.10 route(routing_code)</h4>
275
+ <p>This adds a routing entry to the <tt>config/routes.rb</tt> file. In above steps, we generated a person scaffold and also removed <tt>public/index.html</tt>. Now to make <tt>PeopleController#index</tt> as the default page for the application:</p>
276
+ <div class="code_container">
277
+ <pre class="brush: ruby; gutter: false; toolbar: false">
278
+ route &quot;root :to =&gt; 'person#index'&quot;
279
+ </pre>
280
+ </div>
281
+ <h4 id="inside-dir">2.11 inside(dir)</h4>
282
+ <p>Enables you to run a command from the given directory. For example, if you have a copy of edge rails that you wish to symlink from your new apps, you can do this:</p>
283
+ <div class="code_container">
284
+ <pre class="brush: ruby; gutter: false; toolbar: false">
285
+ inside('vendor') do
286
+ run &quot;ln -s ~/commit-rails/rails rails&quot;
287
+ end
288
+ </pre>
289
+ </div>
290
+ <h4 id="ask-question">2.12 ask(question)</h4>
291
+ <p><tt>ask()</tt> gives you a chance to get some feedback from the user and use it in your templates. Lets say you want your user to name the new shiny library you’re adding:</p>
292
+ <div class="code_container">
293
+ <pre class="brush: ruby; gutter: false; toolbar: false">
294
+ lib_name = ask(&quot;What do you want to call the shiny library ?&quot;)
295
+ lib_name &lt;&lt; &quot;.rb&quot; unless lib_name.index(&quot;.rb&quot;)
296
+
297
+ lib lib_name, &lt;&lt;-CODE
298
+ class Shiny
299
+ end
300
+ CODE
301
+ </pre>
302
+ </div>
303
+ <h4 id="yes-question-or-no-question">2.13 yes?(question) or no?(question)</h4>
304
+ <p>These methods let you ask questions from templates and decide the flow based on the user’s answer. Lets say you want to freeze rails only if the user want to:</p>
305
+ <div class="code_container">
306
+ <pre class="brush: ruby; gutter: false; toolbar: false">
307
+ rake(&quot;rails:freeze:gems&quot;) if yes?(&quot;Freeze rails gems ?&quot;)
308
+ no?(question) acts just the opposite.
309
+ </pre>
310
+ </div>
311
+ <h4 id="git-command">2.14 git(:command)</h4>
312
+ <p>Rails templates let you run any git command:</p>
313
+ <div class="code_container">
314
+ <pre class="brush: ruby; gutter: false; toolbar: false">
315
+ git :init
316
+ git :add =&gt; &quot;.&quot;
317
+ git :commit =&gt; &quot;-a -m 'Initial commit'&quot;
318
+ </pre>
319
+ </div>
320
+
321
+ <h3>Feedback</h3>
322
+ <p>
323
+ You're encouraged to help improve the quality of this guide.
324
+ </p>
325
+ <p>
326
+ If you see any typos or factual errors you are confident to
327
+ patch, please clone <a href="https://github.com/lifo/docrails">docrails</a>
328
+ and push the change yourself. That branch of Rails has public write access.
329
+ Commits are still reviewed, but that happens after you've submitted your
330
+ contribution. <a href="https://github.com/lifo/docrails">docrails</a> is
331
+ cross-merged with master periodically.
332
+ </p>
333
+ <p>
334
+ You may also find incomplete content, or stuff that is not up to date.
335
+ Please do add any missing documentation for master. Check the
336
+ <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a>
337
+ for style and conventions.
338
+ </p>
339
+ <p>
340
+ If for whatever reason you spot something to fix but cannot patch it yourself, please
341
+ <a href="https://github.com/rails/rails/issues">open an issue</a>.
342
+ </p>
343
+ <p>And last but not least, any kind of discussion regarding Ruby on Rails
344
+ documentation is very welcome in the <a href="http://groups.google.com/group/rubyonrails-docs">rubyonrails-docs mailing list</a>.
345
+ </p>
346
+ </div>
347
+ </div>
348
+ </div>
349
+
350
+ <hr class="hide" />
351
+ <div id="footer">
352
+ <div class="wrapper">
353
+ <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>
354
+ <p>"Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved.</p>
355
+ </div>
356
+ </div>
357
+
358
+ <script type="text/javascript" src="javascripts/guides.js"></script>
359
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shCore.js"></script>
360
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushRuby.js"></script>
361
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushXml.js"></script>
362
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushSql.js"></script>
363
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushPlain.js"></script>
364
+ <script type="text/javascript">
365
+ SyntaxHighlighter.all()
366
+ </script>
367
+ </body>
368
+ </html>
data/guides/output/rails_on_rack.html ADDED
@@ -0,0 +1,408 @@
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: Rails on Rack</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>Rails on Rack</h2>
99
+ <p>This guide covers Rails integration with Rack and interfacing with other Rack components. By referring to this guide, you will be able to:</p>
100
+ <ul>
101
+ <li>Create Rails Metal applications</li>
102
+ <li>Use Rack Middlewares in your Rails applications</li>
103
+ <li>Understand Action Pack&#8217;s internal Middleware stack</li>
104
+ <li>Define a custom Middleware stack</li>
105
+ </ul>
106
+
107
+ <div id="subCol">
108
+ <h3 class="chapter"><img src="images/chapters_icon.gif" alt="" />Chapters</h3>
109
+ <ol class="chapters">
110
+ <li><a href="#introduction-to-rack">Introduction to Rack</a></li><li><a href="#rails-on-rack">Rails on Rack</a><ul><li><a href="#rails-application-s-rack-object">Rails Application&#8217;s Rack Object</a></li> <li><a href="#rails-server"><tt>rails server</tt></a></li> <li><a href="#rackup"><tt>rackup</tt></a></li></ul></li><li><a href="#action-controller-middleware-stack">Action Controller Middleware Stack</a><ul><li><a href="#inspecting-middleware-stack">Inspecting Middleware Stack</a></li> <li><a href="#configuring-middleware-stack">Configuring Middleware Stack</a></li> <li><a href="#internal-middleware-stack">Internal Middleware Stack</a></li> <li><a href="#customizing-internal-middleware-stack">Customizing Internal Middleware Stack</a></li> <li><a href="#using-rack-builder">Using Rack Builder</a></li></ul></li><li><a href="#resources">Resources</a><ul><li><a href="#learning-rack">Learning Rack</a></li> <li><a href="#understanding-middlewares">Understanding Middlewares</a></li></ul></li></ol></div>
111
+ </div>
112
+ </div>
113
+
114
+ <div id="container">
115
+ <div class="wrapper">
116
+ <div id="mainCol">
117
+ <div class="warning"><p>This guide assumes a working knowledge of Rack protocol and Rack concepts such as middlewares, url maps and <tt>Rack::Builder</tt>.</p></div>
118
+ <h3 id="introduction-to-rack">1 Introduction to Rack</h3>
119
+ <blockquote>
120
+ <p>Rack provides a minimal, modular and adaptable interface for developing web applications in Ruby. By wrapping <span class="caps">HTTP</span> requests and responses in the simplest way possible, it unifies and distills the <span class="caps">API</span> for web servers, web frameworks, and software in between (the so-called middleware) into a single method call.</p>
121
+ </blockquote>
122
+ <p>- <a href="http://rack.rubyforge.org/doc/">Rack <span class="caps">API</span> Documentation</a></p>
123
+ <p>Explaining Rack is not really in the scope of this guide. In case you are not familiar with Rack&#8217;s basics, you should check out the <a href="#resources">Resources</a> section below.</p>
124
+ <h3 id="rails-on-rack">2 Rails on Rack</h3>
125
+ <h4 id="rails-application-s-rack-object">2.1 Rails Application&#8217;s Rack Object</h4>
126
+ <p><tt>ActionController::Dispatcher.new</tt> is the primary Rack application object of a Rails application. Any Rack compliant web server should be using <tt>ActionController::Dispatcher.new</tt> object to serve a Rails application.</p>
127
+ <h4 id="rails-server">2.2 <tt>rails server</tt></h4>
128
+ <p><tt>rails server</tt> does the basic job of creating a <tt>Rack::Builder</tt> object and starting the webserver. This is Rails&#8217; equivalent of Rack&#8217;s <tt>rackup</tt> script.</p>
129
+ <p>Here&#8217;s how <tt>rails server</tt> creates an instance of <tt>Rack::Builder</tt></p>
130
+ <div class="code_container">
131
+ <pre class="brush: ruby; gutter: false; toolbar: false">
132
+ app = Rack::Builder.new {
133
+ use Rails::Rack::LogTailer unless options[:detach]
134
+ use Rails::Rack::Debugger if options[:debugger]
135
+ use ActionDispatch::Static
136
+ run ActionController::Dispatcher.new
137
+ }.to_app
138
+ </pre>
139
+ </div>
140
+ <p>Middlewares used in the code above are primarily useful only in the development environment. The following table explains their usage:</p>
141
+ <table>
142
+ <tr>
143
+ <th>Middleware</th>
144
+ <th>Purpose</th>
145
+ </tr>
146
+ <tr>
147
+ <td><tt>Rails::Rack::LogTailer</tt></td>
148
+ <td>Appends log file output to console</td>
149
+ </tr>
150
+ <tr>
151
+ <td><tt>ActionDispatch::Static</tt></td>
152
+ <td>Serves static files inside <tt>Rails.root/public</tt> directory</td>
153
+ </tr>
154
+ <tr>
155
+ <td><tt>Rails::Rack::Debugger</tt></td>
156
+ <td>Starts Debugger</td>
157
+ </tr>
158
+ </table>
159
+ <h4 id="rackup">2.3 <tt>rackup</tt></h4>
160
+ <p>To use <tt>rackup</tt> instead of Rails&#8217; <tt>rails server</tt>, you can put the following inside <tt>config.ru</tt> of your Rails application&#8217;s root directory:</p>
161
+ <div class="code_container">
162
+ <pre class="brush: ruby; gutter: false; toolbar: false">
163
+ # Rails.root/config.ru
164
+ require &quot;config/environment&quot;
165
+
166
+ use Rails::Rack::LogTailer
167
+ use ActionDispatch::Static
168
+ run ActionController::Dispatcher.new
169
+ </pre>
170
+ </div>
171
+ <p>And start the server:</p>
172
+ <div class="code_container">
173
+ <pre class="brush: plain; gutter: false; toolbar: false">
174
+ $ rackup config.ru
175
+ </pre>
176
+ </div>
177
+ <p>To find out more about different <tt>rackup</tt> options:</p>
178
+ <div class="code_container">
179
+ <pre class="brush: plain; gutter: false; toolbar: false">
180
+ $ rackup --help
181
+ </pre>
182
+ </div>
183
+ <h3 id="action-controller-middleware-stack">3 Action Controller Middleware Stack</h3>
184
+ <p>Many of Action Controller&#8217;s internal components are implemented as Rack middlewares. <tt>ActionController::Dispatcher</tt> uses <tt>ActionController::MiddlewareStack</tt> to combine various internal and external middlewares to form a complete Rails Rack application.</p>
185
+ <div class="note"><p><tt>ActionController::MiddlewareStack</tt> is Rails&#8217; equivalent of <tt>Rack::Builder</tt>, but built for better flexibility and more features to meet Rails&#8217; requirements.</p></div>
186
+ <h4 id="inspecting-middleware-stack">3.1 Inspecting Middleware Stack</h4>
187
+ <p>Rails has a handy rake task for inspecting the middleware stack in use:</p>
188
+ <div class="code_container">
189
+ <pre class="brush: plain; gutter: false; toolbar: false">
190
+ $ rake middleware
191
+ </pre>
192
+ </div>
193
+ <p>For a freshly generated Rails application, this might produce something like:</p>
194
+ <div class="code_container">
195
+ <pre class="brush: ruby; gutter: false; toolbar: false">
196
+ use ActionDispatch::Static
197
+ use Rack::Lock
198
+ use ActiveSupport::Cache::Strategy::LocalCache
199
+ use Rack::Runtime
200
+ use Rails::Rack::Logger
201
+ use ActionDispatch::ShowExceptions
202
+ use ActionDispatch::RemoteIp
203
+ use Rack::Sendfile
204
+ use ActionDispatch::Callbacks
205
+ use ActiveRecord::ConnectionAdapters::ConnectionManagement
206
+ use ActiveRecord::QueryCache
207
+ use ActionDispatch::Cookies
208
+ use ActionDispatch::Session::CookieStore
209
+ use ActionDispatch::Flash
210
+ use ActionDispatch::ParamsParser
211
+ use Rack::MethodOverride
212
+ use ActionDispatch::Head
213
+ use ActionDispatch::BestStandardsSupport
214
+ run Blog::Application.routes
215
+ </pre>
216
+ </div>
217
+ <p>Purpose of each of this middlewares is explained in the <a href="#internal-middleware-stack">Internal Middlewares</a> section.</p>
218
+ <h4 id="configuring-middleware-stack">3.2 Configuring Middleware Stack</h4>
219
+ <p>Rails provides a simple configuration interface <tt>config.middleware</tt> for adding, removing and modifying the middlewares in the middleware stack via <tt>application.rb</tt> or the environment specific configuration file <tt>environments/&lt;environment&gt;.rb</tt>.</p>
220
+ <h5 id="adding-a-middleware">3.2.1 Adding a Middleware</h5>
221
+ <p>You can add a new middleware to the middleware stack using any of the following methods:</p>
222
+ <ul>
223
+ <li><tt>config.middleware.use(new_middleware, args)</tt> &#8211; Adds the new middleware at the bottom of the middleware stack.</li>
224
+ </ul>
225
+ <ul>
226
+ <li><tt>config.middleware.insert_before(existing_middleware, new_middleware, args)</tt> &#8211; Adds the new middleware before the specified existing middleware in the middleware stack.</li>
227
+ </ul>
228
+ <ul>
229
+ <li><tt>config.middleware.insert_after(existing_middleware, new_middleware, args)</tt> &#8211; Adds the new middleware after the specified existing middleware in the middleware stack.</li>
230
+ </ul>
231
+ <div class="code_container">
232
+ <pre class="brush: ruby; gutter: false; toolbar: false">
233
+ # config/application.rb
234
+
235
+ # Push Rack::BounceFavicon at the bottom
236
+ config.middleware.use Rack::BounceFavicon
237
+
238
+ # Add Lifo::Cache after ActiveRecord::QueryCache.
239
+ # Pass { :page_cache =&gt; false } argument to Lifo::Cache.
240
+ config.middleware.insert_after ActiveRecord::QueryCache, Lifo::Cache, :page_cache =&gt; false
241
+ </pre>
242
+ </div>
243
+ <h5 id="swapping-a-middleware">3.2.2 Swapping a Middleware</h5>
244
+ <p>You can swap an existing middleware in the middleware stack using <tt>config.middleware.swap</tt>.</p>
245
+ <div class="code_container">
246
+ <pre class="brush: ruby; gutter: false; toolbar: false">
247
+ # config/application.rb
248
+
249
+ # Replace ActionController::Failsafe with Lifo::Failsafe
250
+ config.middleware.swap ActionController::Failsafe, Lifo::Failsafe
251
+ </pre>
252
+ </div>
253
+ <h5 id="middleware-stack-is-an-array">3.2.3 Middleware Stack is an Array</h5>
254
+ <p>The middleware stack behaves just like a normal <tt>Array</tt>. You can use any <tt>Array</tt> methods to insert, reorder, or remove items from the stack. Methods described in the section above are just convenience methods.</p>
255
+ <p>For example, the following removes the middleware matching the supplied class name:</p>
256
+ <div class="code_container">
257
+ <pre class="brush: ruby; gutter: false; toolbar: false">
258
+ config.middleware.delete(middleware)
259
+ </pre>
260
+ </div>
261
+ <h4 id="internal-middleware-stack">3.3 Internal Middleware Stack</h4>
262
+ <p>Much of Action Controller&#8217;s functionality is implemented as Middlewares. The following table explains the purpose of each of them:</p>
263
+ <table>
264
+ <tr>
265
+ <th>Middleware</th>
266
+ <th>Purpose</th>
267
+ </tr>
268
+ <tr>
269
+ <td><tt>Rack::Lock</tt></td>
270
+ <td>Sets <tt>env[&#8220;rack.multithread&#8221;]</tt> flag to <tt>true</tt> and wraps the application within a Mutex.</td>
271
+ </tr>
272
+ <tr>
273
+ <td><tt>ActionController::Failsafe</tt></td>
274
+ <td>Returns <span class="caps">HTTP</span> Status <tt>500</tt> to the client if an exception gets raised while dispatching.</td>
275
+ </tr>
276
+ <tr>
277
+ <td><tt>ActiveRecord::QueryCache</tt></td>
278
+ <td>Enables the Active Record query cache.</td>
279
+ </tr>
280
+ <tr>
281
+ <td><tt>ActionDispatch::Session::CookieStore</tt></td>
282
+ <td>Uses the cookie based session store.</td>
283
+ </tr>
284
+ <tr>
285
+ <td><tt>ActionDispatch::Session::CacheStore</tt></td>
286
+ <td>Uses the Rails cache based session store.</td>
287
+ </tr>
288
+ <tr>
289
+ <td><tt>ActionDispatch::Session::MemCacheStore</tt></td>
290
+ <td>Uses the memcached based session store.</td>
291
+ </tr>
292
+ <tr>
293
+ <td><tt>ActiveRecord::SessionStore</tt></td>
294
+ <td>Uses the database based session store.</td>
295
+ </tr>
296
+ <tr>
297
+ <td><tt>Rack::MethodOverride</tt></td>
298
+ <td>Sets <span class="caps">HTTP</span> method based on <tt>_method</tt> parameter or <tt>env[&#8220;HTTP_X_HTTP_METHOD_OVERRIDE&#8221;]</tt>.</td>
299
+ </tr>
300
+ <tr>
301
+ <td><tt>Rack::Head</tt></td>
302
+ <td>Discards the response body if the client sends a <tt>HEAD</tt> request.</td>
303
+ </tr>
304
+ </table>
305
+ <div class="info"><p>It&#8217;s possible to use any of the above middlewares in your custom Rack stack.</p></div>
306
+ <h4 id="customizing-internal-middleware-stack">3.4 Customizing Internal Middleware Stack</h4>
307
+ <p>It&#8217;s possible to replace the entire middleware stack with a custom stack using <tt>ActionController::Dispatcher.middleware=</tt>.</p>
308
+ <p>Put the following in an initializer:</p>
309
+ <div class="code_container">
310
+ <pre class="brush: ruby; gutter: false; toolbar: false">
311
+ # config/initializers/stack.rb
312
+ ActionController::Dispatcher.middleware = ActionController::MiddlewareStack.new do |m|
313
+ m.use ActionController::Failsafe
314
+ m.use ActiveRecord::QueryCache
315
+ m.use Rack::Head
316
+ end
317
+ </pre>
318
+ </div>
319
+ <p>And now inspecting the middleware stack:</p>
320
+ <div class="code_container">
321
+ <pre class="brush: plain; gutter: false; toolbar: false">
322
+ $ rake middleware
323
+ (in /Users/lifo/Rails/blog)
324
+ use ActionController::Failsafe
325
+ use ActiveRecord::QueryCache
326
+ use Rack::Head
327
+ run ActionController::Dispatcher.new
328
+ </pre>
329
+ </div>
330
+ <h4 id="using-rack-builder">3.5 Using Rack Builder</h4>
331
+ <p>The following shows how to replace use <tt>Rack::Builder</tt> instead of the Rails supplied <tt>MiddlewareStack</tt>.</p>
332
+ <p><strong>Clear the existing Rails middleware stack</strong></p>
333
+ <div class="code_container">
334
+ <pre class="brush: ruby; gutter: false; toolbar: false">
335
+ # config/application.rb
336
+ config.middleware.clear
337
+ </pre>
338
+ </div>
339
+ <p><br />
340
+ <strong>Add a <tt>config.ru</tt> file to <tt>Rails.root</tt></strong></p>
341
+ <div class="code_container">
342
+ <pre class="brush: ruby; gutter: false; toolbar: false">
343
+ # config.ru
344
+ use MyOwnStackFromScratch
345
+ run ActionController::Dispatcher.new
346
+ </pre>
347
+ </div>
348
+ <h3 id="resources">4 Resources</h3>
349
+ <h4 id="learning-rack">4.1 Learning Rack</h4>
350
+ <ul>
351
+ <li><a href="http://rack.github.com">Official Rack Website</a></li>
352
+ <li><a href="http://chneukirchen.org/blog/archive/2007/02/introducing-rack.html">Introducing Rack</a></li>
353
+ <li><a href="http://m.onkey.org/ruby-on-rack-1-hello-rack">Ruby on Rack #1 &#8211; Hello Rack!</a></li>
354
+ <li><a href="http://m.onkey.org/ruby-on-rack-2-the-builder">Ruby on Rack #2 &#8211; The Builder</a></li>
355
+ </ul>
356
+ <h4 id="understanding-middlewares">4.2 Understanding Middlewares</h4>
357
+ <ul>
358
+ <li><a href="http://railscasts.com/episodes/151-rack-middleware">Railscast on Rack Middlewares</a></li>
359
+ </ul>
360
+
361
+ <h3>Feedback</h3>
362
+ <p>
363
+ You're encouraged to help improve the quality of this guide.
364
+ </p>
365
+ <p>
366
+ If you see any typos or factual errors you are confident to
367
+ patch, please clone <a href="https://github.com/lifo/docrails">docrails</a>
368
+ and push the change yourself. That branch of Rails has public write access.
369
+ Commits are still reviewed, but that happens after you've submitted your
370
+ contribution. <a href="https://github.com/lifo/docrails">docrails</a> is
371
+ cross-merged with master periodically.
372
+ </p>
373
+ <p>
374
+ You may also find incomplete content, or stuff that is not up to date.
375
+ Please do add any missing documentation for master. Check the
376
+ <a href="ruby_on_rails_guides_guidelines.html">Ruby on Rails Guides Guidelines</a>
377
+ for style and conventions.
378
+ </p>
379
+ <p>
380
+ If for whatever reason you spot something to fix but cannot patch it yourself, please
381
+ <a href="https://github.com/rails/rails/issues">open an issue</a>.
382
+ </p>
383
+ <p>And last but not least, any kind of discussion regarding Ruby on Rails
384
+ documentation is very welcome in the <a href="http://groups.google.com/group/rubyonrails-docs">rubyonrails-docs mailing list</a>.
385
+ </p>
386
+ </div>
387
+ </div>
388
+ </div>
389
+
390
+ <hr class="hide" />
391
+ <div id="footer">
392
+ <div class="wrapper">
393
+ <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>
394
+ <p>"Rails", "Ruby on Rails", and the Rails logo are trademarks of David Heinemeier Hansson. All rights reserved.</p>
395
+ </div>
396
+ </div>
397
+
398
+ <script type="text/javascript" src="javascripts/guides.js"></script>
399
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shCore.js"></script>
400
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushRuby.js"></script>
401
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushXml.js"></script>
402
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushSql.js"></script>
403
+ <script type="text/javascript" src="javascripts/syntaxhighlighter/shBrushPlain.js"></script>
404
+ <script type="text/javascript">
405
+ SyntaxHighlighter.all()
406
+ </script>
407
+ </body>
408
+ </html>